diff options
Diffstat (limited to 'docs/BUILDING.md')
-rw-r--r-- | docs/BUILDING.md | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/docs/BUILDING.md b/docs/BUILDING.md new file mode 100644 index 0000000..60a3260 --- /dev/null +++ b/docs/BUILDING.md @@ -0,0 +1,231 @@ +# Building from Source + +The source code is built using CMake, the process of building uscxml is +essentially the same on every platform: + +1. Read the <b>[Platform Notes](#platform-notes)</b> below to prepare your system. +2. Checkout uscxml into a convenient directory: + + <tt>git clone git://github.com/tklab-tud/uscxml.git</tt> + +3. Create a new directory for an *out-of-source* build. I usually create sub-directories +in <tt><USCXML_SRC>/build/</tt>. +4. Run cmake (or ccmake / CMake-GUI) to create the files required by your actual build-system. +5. Use your actual build-system or development environment to build uscxml. +6. Read the SCXML draft and have a look at the tests to get started. + +If you want to build for another IDE or build-system, just create a new +*out-of-source* build directory and start over with cmake. To get an idea of +supported IDEs and build-environments on your platform, type <tt>cmake --help</tt> +or run the CMake-GUI and look for the *Generators* section at the end of the +output. Default on Unices is Makefiles. + +# Build Dependencies + +Overview of the uscxml dependencies. See the [Platform Notes](#platform-notes) for details. + +<b>Note:</b> We download pre-compiled versions of most dependencies at cmake configure-time. If you want +to provide you own libraries, remove them from <tt><USCXML_SRC>/contrib/prebuilt/</tt> and provide +your own. + +<table> + <tr><th>Platform</th><th>Dependency</th><th>Version</th><th>Comment</th></tr> + <tr> + <td rowspan="10"><b>Everyone</b></td> + <td><a href="http://www.cmake.org/cmake/resources/software.html">CMake</a><br />required</td> + <td>>= 2.8.6</td> + <td>The build-system used for uscxml.</td></tr> + <tr> + <td><a href="http://libevent.org">libevent</a><br />pre-compiled</td> + <td>>= 2.1.x</td> + <td>Event queues with callbacks and the HTTP server.</td></tr> + <tr> + <td><a href="http://curl.haxx.se">curl</a><br />pre-compiled</td> + <td>>= 7.29.0</td> + <td>URL downloads.</td></tr> + <tr> + <td><a href="http://code.google.com/p/v8/">v8</a><br />pre-compiled</td> + <td>svn checkout</td> + <td>ECMAScript datamodel implementation.</td></tr> + <tr> + <td><a href="http://www.swi-prolog.org">SWI Prolog</a><br />pre-compiled for unices</td> + <td>>= 6.3.x</td> + <td>Prolog datamodel implementation.</td></tr> + <tr> + <td><a href="http://code.google.com/p/google-glog/">glog</a><br />pre-compiled</td> + <td>>= 0.3.3</td> + <td>Logging library.</td></tr> + <tr> + <td><a href="https://github.com/jezhiggins/arabica">Arabica</a><br />pre-compiled</td> + <td>>= git checkout</td> + <td>XML DOM / XPath / XML Events.</td></tr> + <tr> + <td><a href="http://www.sqlite.org">SQLite</a><br />optional</td> + <td>>= 3.7.15.2</td> + <td>Persistence and sqlite invoker.</td></tr> + <tr> + <td><a href="http://www.openscenegraph.com">OpenSceneGraph</a><br />optional</td> + <td>>= 3.1.X</td> + <td>3D invokers (scenegraph, osgconvert).</td></tr> + <tr> + <td><a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a><br />recommended</td> + <td></td> + <td>Used by <tt>make docs</tt> to generate documentation from source comments.</td></tr> + </tr> + <tr bgcolor="grey"><td bgcolor="#dddddd" colspan="4"></td></tr> + + <tr> + <td rowspan="3"><b>Mac OSX</b></td> + <td><a href="http://developer.apple.com/xcode/">XCode</a><br />required</td> + <td>4.2.1 works</td> + <td>Apples SDK with all the toolchains.</td></tr> + <tr> + <td><a href="http://www.macports.org/">MacPorts</a><br />recommended</td> + <td>>= 2.0.3</td> + <td>Build system for a wide selection of open-source packages.</td></tr> + <tr> + <td><a href="http://www.xmlsoft.org">libxml2</a><br />pre-installed</td> + <td>>= 2.6.16</td> + <td>Actual XML parser used by Arabica.</td></tr> + </tr> + + <tr> + <td rowspan="1"><b>Linux</b></td> + <td><a href="http://www.xmlsoft.org">libxml2</a><br />required</td> + <td>>= 2.6.16</td> + <td>Actual XML parser used by Arabica.</td></tr> + </tr> + + <tr> + <td rowspan="1"><b>Windows</b></td> + <td bgcolor="#ffffdd"><a href="http://www.microsoft.com/visualstudio/en-us">Visual Studio 10</a><br />required</td> + <td>v10 pro works</td> + <td>As a student, you can get your version through MSAA.</td></tr> + </tr> +</table> + +# Platform Notes + +This section will detail the preparation of the respective platforms to ultimately compile uscxml. + +## Mac OSX + +You will have to install <tt>cmake</tt> via Macports: + + sudo port install cmake + +The rest is pre-installed or downloaded at configure-time as pre-compiled libraries. +Just download the source and invoke CMake to create Makefiles or a Xcode project. + +### Console / Make + + $ cd <USCXML_SRCDIR> + $ mkdir -p build/cli && cd build/cli + $ cmake ../.. + [...] + -- Build files have been written to: .../build/cli + $ make + +You can test whether everything works by starting the mmi-browser with a test.scxml file: + + $ ./bin/mmi-browser ../../test/samples/uscxml/test-ecmascript.scxml + +### Xcode + + $ cd <USCXML_SRCDIR> + $ mkdir -p build/xcode && cd build/xcode + $ cmake -G Xcode ../.. + [...] + -- Build files have been written to: .../build/xcode + $ open uscxml.xcodeproj + +You can of course reuse the same source directory for many build directories. + +## Linux + +Depending on your distribution, you will most likely have apt-get or yum available as package managers. +If you do not, I'll have to assume that you are knowledgable enough to resolve build dependencies on your own. + +### Preparing *apt-get based* distributions + +This would be all distributions based on Debian, like Ubuntu, Linux Mint and the like. + + # build system and compiler + $ sudo apt-get install git cmake cmake-curses-gui make g++ + + # uscxml required dependencies + $ sudo apt-get install libxml2-dev + +There may still be packages missing due to the set of dependencies among packages +in the various distributons. Try to run cmake and resolve dependencies until you +are satisfied. + +### Preparing *yum based* distributions + +This would be all distributions based on Redhat, e.g. Fedora. + + # build system and compiler + $ sudo yum install git cmake cmake-gui gcc-c++ + + # uscxml required dependencies + $ sudo yum install xml2-devel + +### Console / Make + +Instructions are a literal copy of building uscxml for MacOSX on the console from above: + + $ cd <USCXML_SRCDIR> + $ mkdir -p build/cli && cd build/cli + $ cmake ../.. + [...] + -- Build files have been written to: .../build/cli + $ make + +You can test whether everything works by starting the mmi-browser with a test.scxml file: + + $ ./bin/mmi-browser ../../test/samples/uscxml/test-ecmascript.scxml + +### Eclipse CDT + +<b>Note:</b> Eclipse does not like the project to be a subdirectory in the source. +You have to choose your build directory with the generated project accordingly. + + $ mkdir -p build/uscxml/eclipse && cd build/uscxml/eclipse + $ cmake -G "Eclipse CDT4 - Unix Makefiles" <USCXML_SRCDIR> + [...] + -- Build files have been written to: .../build/uscxml/eclipse + +Now open Eclipse CDT and import the out-of-source directory as an existing project into workspace, leaving the "Copy projects +into workspace" checkbox unchecked. There are some more [detailed instruction](http://www.cmake.org/Wiki/Eclipse_CDT4_Generator) available +in the cmake wiki as well. + +### Compiling Dependencies + +If the packages in your distribution are too old, you will have to compile current +binaries. This applies especially for SWI and CMake as they *need* to be rather +current. Have a look at the build dependencies above for minimum versions. + +## Windows + +Building from source on windows is somewhat more involved and instructions are necessarily in prose form. These instructions were +created using Windows 7 and MS Visual Studio 2010. + +### Prepare compilation + +1. Use git to **checkout** the source from <tt>git://github.com/tklab-tud/uscxml.git</tt> + into any convenient directory. + +2. Start the **CMake-GUI** and enter the checkout directory in the "Where is the source + code" text field. Choose any convenient directory to build the binaries in. + +3. Hit "**Configure**" and choose your toolchain and compiler - I only tested with + Visual Studio 10. Hit "Configure" again until there are no more red items in + the list. If these instructions are still correct and you did as described + above, you should be able to "Generate" the Visual Project Solution. + +Now you can generate the MS Visual Studio project file <tt><USCXML_BUILDIR>/uscxml.sln</tt>. +Just open it up to continue in your IDE. + +<b>Note:</b> We only tested with the MSVC compiler. You can try to compile +with MinGW but you would have to build all the dependent libraries as well. + |