Installation » History » Revision 61
Revision 60 (Tony Ciavarella, 04/22/2014 11:23 PM) → Revision 61/175 (Tony Ciavarella, 04/22/2014 11:25 PM)
h1. Installation
h2. Obtaining the Source Code
h3. Release Tarballs
Release source tarballs are available on the "Files":http://oss.squalllinesoftware.com/projects/disorder/files page. This is what you want if you are looking for stability and something ready for production use. You'll probably want to use the most recent version found on that page.
h3. SCM
The Disorder source code is hosted in a "Mercurial":http://mercurial.selenic.com repository. This is what you want if you are looking for the very latest bleeding edge of the code for contributing to Disorder, forking an evil fork, or whatever other reason you may have.
Read the "Mercurial Documentation":http://hgbook.red-bean.com/ if you aren't familiar with that and you want to go this route.
To clone the repository including the full history:
<pre>hg clone http://hg.squalllinesoftware.com/oss/disorder</pre>
h2. Prerequisites
Given the assumption that a somewhat sane build environment for C++ already exists on the build machine, the following third party things are required to build Disorder:
* "Boost":http://www.boost.org >= 1.49.0
* "Eigen":http://eigen.tuxfamily.org >= 3.0.5
* C++ version of the "SEDRIS SRM":http://www.sedris.org/srm_4.4/srm_c_cpp.htm >= 4.4.0
** The SEDRIS SRM is optional but you will need some kind of sophisticated geospatial thing if you don't use the SEDRIS SRM and you'll have to implement your own version of disorder's geospatial Convertor interface.
* A "Python":http://www.python.org interpreter (needed to use the "waf":https://code.google.com/p/waf/ build system)
* A C++ compiler capable of understanding the "ISO C++ 2011 Standard":http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=50372
** "GCC":http://gcc.gnu.org >= 4.7.0
** "Clang++":http://clang.llvm.org >= 3.1.0
** Visual Studio > 2013
*** If you intend to use Visual Studio to build this thing on Windows, you're out of luck. Visual Stupido is way behind in standards compliance. They haven't even bothered to comply with the C99 standard yet. Their C++11 support doesn't include such things as "noexcept" or "constexpr" and as such, disorder will not compile. If/when they actually support enough of the C++11 standard for disorder to compile, building in Visual Stupido will be supported. Yes, disorder could be hacked with excessive preprocessor nonsense to build on Visual Stupido 2012/2013, but doing that seems counter productive unless you want to pay me to do it.
*** If such a day comes where Visual Studio is supported, the Express version may work, but using it to build an open source project may be a violation of Microsoft's silly license.
*** You can, of course, use gcc to build disorder on windows in a "cygwin":http://cygwin.org/ environment, but you should expect pain because SEDRIS won't build on cygwin out of the box.
Build and install these things in accordance with the instructions for your operating system provided by each vendor. Some hints for certain platforms follow.
h3. Debian Linux and Derivatives
h4. Debian 6.x (Squeeze)
The binary packages for "Boost":http://www.boost.org and "Eigen":http://eigen.tuxfamily.org in the package system are way too old. You'll have to download the source for them and build "Boost":http://www.boost.org yourself.
h4. Debian >= 7.x (Wheezy)
All the dependencies are available via the package system. To install the Boost and Eigen build dependencies on Debian and maybe other derivatives:
<pre>sudo apt-get install libboost-dev libboost-system-dev libboost-thread-dev libboost-date-time-dev libeigen3-dev</pre>
If you don't already have python, this will get the required bits of that:
<pre>sudo apt-get install python</pre>
h3. Sabayon Linux
To install boost via the entropy package system:
<pre>sudo equo install boost</pre>
As of 2/22/2013, the Eigen verison in entropy is a bit outdated (3.0.6). You can use it, but you probably should download the latest version from "Eigen":http://eigen.tuxfamily.org which doesn't require any compilation. Just extract the content of the archive somewhere and remember to tell Disorder where to find it with --eigen-root=<put actual path to eigen root here> during the configuration step.
If you don't already have python, this will get the required bits of that: <pre>sudo equo install python</pre>
h2. Configuration
If everything is setup properly, this step will be a breeze, but it is important to resolve any errors produced by the configuration step prior to attempting to compile Disorder.
h3. General
The basic idea of configuration is to allow disorder to learn enough about your build platform to be able to compile. Disorder uses the
"waf":https://code.google.com/p/waf/ build system to configure and compile. In general terms, you want to invoke waf with the configure target like this:
<pre>./waf configure</pre>
On linux-like systems, waf will attempt to find "Boost":http://www.boost.org and "Eigen":http://eigen.tuxfamily.org but you can override this behavior in the event of non-standard installation location or fanciful whimsy. You will always have to tell it where to find the SEDRIS SRM however. The options for configuring disorder's dependencies can be found by issuing the following command:
<pre>./waf --help</pre>
Said options are thusly enumerated for your convenience:
h4. Boost
|_. Option |_. Argument |_. Description |
| --boost-includes | path to the Boost includes root (eg. /opt/boost_1_49_0) | Tells disorder where to find the include files for the Boost libraries. |
| --boost-libs | path to the directory where the compiled Boost libraries are (eg. /opt/boost_1_49_0/stage/lib) | Tells disorder where to find Boost's compiled library files. |
| --boost-static | none | Links disorder against static Boost libraries instead of the default shared library linkage. |
| --boost-mt | none | Links disorder against the multi-threaded versions of the Boost libraries. |
| --boost-abi | desired tags from dgsyp | Select Boost libraries with tags. See Boost documentation ("Unixes":http://www.boost.org/doc/libs/1_53_0/more/getting_started/unix-variants.html#library-naming, "windows":http://www.boost.org/doc/libs/1_53_0/more/getting_started/windows.html#library-naming) for more information. |
| --boost-toolset | desired toolset (eg. msvc, vc90, or gcc) | Overrides the automatic toolset detection as specified. |
h4. Eigen
|_. Option |_. Argument |_. Description |
| --eigen-root | path to the root of the Eigen library (eg. /opt/eigen-3.1.2) | Tells disorder where to find the Eigen library. |
h4. SEDRIS SRM
|_. Option |_. Argument |_. Description |
| --sedris-srm-root | path to the root of the SEDRIS SRM tree (eg. /opt/srm) | Tells disorder where to find the SEDRIS SRM. This argument is *required*. |
| --sedris-srm-static | none | Links disorder against the static SEDRIS SRM library instead of the default dynamic one. |
| --sedris-srm-build-variant | build variant directory (eg. linux-3.5.0-sabayon-i386-gnu-/OPT) to find the compiled output files | Overrides the default selection of the first build variant found. |
h3. Linux
From inside the root of the Disorder tree do this in your favorite terminal emulator:
<pre>./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here></pre>
For example, if your SEDRIS SRM is in /opt/sedris/srm:
<pre>./waf configure --sedris-srm-root=/opt/sedris/srm</pre>
That command will take several seconds and print a bunch of hopefully green stuff. The output should end up looking something like this:
<pre>
Setting top to : /opt/disorder
Setting out to : /opt/disorder/bin
Checking for 'g++' (c++ compiler) : /usr/bin/g++
Checking for program doxygen : /usr/bin/doxygen
Checking for program tar : /bin/tar
Checking boost ABI tag :
Checking boost includes : 1_49
Checking boost libs : ok
Checking for boost linkage : ok
Checking for header boost/asio.hpp : yes
Checking for header boost/bind.hpp : yes
Checking for header boost/date_time.hpp : yes
Checking for header boost/detail/endian.hpp : yes
Checking for header boost/format.hpp : yes
Checking for header boost/function.hpp : yes
Checking for header boost/functional/factory.hpp : yes
Checking for header boost/ptr_container/ptr_vector.hpp : yes
Checking for header boost/scoped_ptr.hpp : yes
Checking for header boost/static_assert.hpp : yes
Checking for header boost/thread.hpp : yes
Checking for program pkg-config : /usr/bin/pkg-config
Checking for 'eigen3' : yes
Checking for header Eigen/Dense : yes
Checking for SEDRIS SRM : /opt/sedris/srm
Checking for SEDRIS SRM include directory : /opt/sedris/srm/src/include
Checking for SEDRIS SRM library directory : /opt/sedris/srm/lib/linux-3.1.0-1-amd64-i386-gnu-/OPT
SEDRIS SRM library : /opt/sedris/srm/lib/linux-3.1.0-1-amd64-i386-gnu-/OPT/libsrm.so
Checking for header srf_all.h : yes
'configure' finished successfully (25.518s)
</pre>
If you get an error instead of that last line saying that 'configure' finished successfully, you must fix whatever is making it unhappy and try again.
h4. Clang++
To use the "Clang":http://clang.llvm.org/ C++ compiler instead of "GCC":http://gcc.gnu.org/, assuming clang++ is installed on the build system:
<pre>CXX=<put the path to clang++ here> ./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here></pre>
For example:
<pre>CXX=/usr/bin/clang++ ./waf configure --sedris-srm-root=/opt/sedris/srm</pre>
h3. Windows
On windows, your $PATH environment variable needs to include the path to the Python interpreter.
The easiest way to configure Disorder on Windows is to use a modified version of the provided batch file to tell Disorder where your prerequisites live. Copy the template from @tools/windows/configure.bat@ to the root of the Disorder tree.
This file contains some variables near the middle that must be set according to your system configuration. An example is provided in the template for guidance.
Once you are finished editing configure.bat, it's time to execute it. From the command line:
<pre>configure.bat</pre>
If everything is successful, you should get something that looks like this:
<pre>
C:\oss\disorder>python waf configure --boost-includes=c:\oss\boost_1_48_0 --boost-libs=c:\oss\boost_1_48_0\stage\lib --boost-mt --boost-static --eigen-root=c:\oss\eigen-3.0.4 --sedris-srm-root=c:\oss\sedris\srm --sedris-srm-static
Setting top to : C:\oss\disorder
Setting out to : C:\oss\disorder\bin
Checking for 'msvc' (c++ compiler) : c:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\BIN\amd64\CL.exe
Checking for program doxygen : not found
Checking for Eigen library : c:\oss\eigen-3.0.4
Checking for header Eigen/Dense : yes
Checking for SEDRIS SRM : c:\oss\sedris\srm
Checking for SEDRIS SRM include directory : c:\oss\sedris\srm\src\include
Checking for SEDRIS SRM library directory : c:\oss\sedris\srm\lib\[Debug/Release]
Checking for header srf_all.h : yes
Configuring boost libraries : debug variant
Checking boost ABI tag : gd
Checking boost includes : 1_48
Checking boost libs : ok
Checking for boost linkage : ok
Checking for header boost/asio.hpp : yes
Checking for header boost/bind.hpp : yes
Checking for header boost/date_time.hpp : yes
Checking for header boost/detail/endian.hpp : yes
Checking for header boost/format.hpp : yes
Checking for header boost/function.hpp : yes
Checking for header boost/functional/factory.hpp : yes
Checking for header boost/ptr_container/ptr_vector.hpp : yes
Checking for header boost/scoped_ptr.hpp : yes
Checking for header boost/static_assert.hpp : yes
Checking for header boost/thread.hpp : yes
Configuring boost libraries : optimized variant
Checking boost ABI tag :
Checking boost includes : 1_48
Checking boost libs : ok
Checking for boost linkage : ok
Checking for header boost/asio.hpp : yes
Checking for header boost/bind.hpp : yes
Checking for header boost/date_time.hpp : yes
Checking for header boost/detail/endian.hpp : yes
Checking for header boost/format.hpp : yes
Checking for header boost/function.hpp : yes
Checking for header boost/functional/factory.hpp : yes
Checking for header boost/ptr_container/ptr_vector.hpp : yes
Checking for header boost/scoped_ptr.hpp : yes
Checking for header boost/static_assert.hpp : yes
Checking for header boost/thread.hpp : yes
'configure' finished successfully (31.262s)
</pre>
If you don't see that last line that says @'configure' finished successfully@, then something is screwed up and it needs to be fixed. Fix it and try again.
h2. Compiling
The basic strategy for building Disorder is to invoke the waf build system with the desired build variant.
Disorder has two build variants:
* debug: produces a library that contains debugging symbols and disables most compiler optimizations
* optimized: produces a library stripped of debugging symbols and enables compiler optimizations for performance
It might be reasonable to use the @debug@ variant in a development environment and the @optimized@ variant in a production environment.
The @debug@ variant is produced by the @build_debug@ build target and the @optimized@ variant is produced by the @build_optimized@ build target.
The results of the build are put in the @bin@ subdirectory under the name of the variant.
Both variants can coexist peacefully in the tree at the same time.
h3. Linux
On Linux, to build the Disorder @debug@ variant:
<pre>./waf build_debug</pre>
h3. Windows
On Windows, the waf script is invoked indirectly. To build the @optimized@ variant:
<pre>python.exe waf build_optimized</pre>
h2. Ensuring Build Correctness
Due to the complexity of varied compilers and build configurations, it is imperative that you preform the necessary testing on your build to ensure that it performs correctly.
Don't fret. It's easy and is well worth the time it takes for the peace of mind you gain. Just tell waf to test_all_<variant> like this for the @optimized@ variant:
<pre>./waf test_all_optimized</pre>
That should result in something like this:
<pre>
Waf: Entering directory `/opt/disorder/bin/optimized'
[PASS]: all 1 Asynchronous Log tests passed!
[PASS]: all 1789 Datum Factory tests passed!
[PASS]: all 1192 Dead Reckoner tests passed!
[PASS]: all 347 Entity Event tests passed!
[PASS]: all 191 Entity Freeze tests passed!
[PASS]: all 134 Entity Publisher tests passed!
[PASS]: all 75133 Geospatial tests passed!
[PASS]: all 13 Goofy Integer tests passed!
[PASS]: all 85 PDU Disseminator tests passed!
[PASS]: all 85 PDU Factory tests passed!
[PASS]: all 7659 PDU Size tests passed!
[PASS]: all 46 Timestamp tests passed!
[PASS]: all 2963 UDP Transport tests passed!
Waf: Leaving directory `/opt/disorder/bin/optimized'
'test_all_optimized' finished successfully (12.858s) (17.581s)
</pre>
If you see
<pre>Something failed! That's not good. This build cannot be trusted until the damn thing is fixed.</pre>
in red at the bottom instead of a green "finished successfully" message, you need to file a bug report and/or fix it yourself and send in a patch. Under no circumstances should you attempt to use a build that fails the test suite. A test failure means disorder isn't working as expected for some reason and that reason needs to be resolved for your simulation to function properly.
h2. Building Against the Disorder Library
h3. Compiling
In order to compile your goodness against the Disorder library, you'll need to have the header files from the @src@ directory in the Disorder tree and Eigen's include directory in your compiler's include path. You do not need anything from SEDRIS SRM in your include path.
h3. Linking
Just link your program against Disorder's static library that can be found in the @bin/<build variant>@ directory.