Installation¶

Obtaining the Source Code¶

Release Tarballs¶

Release source tarballs are available on the 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.

SCM¶

The Disorder source code is hosted in a Mercurial 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 if you aren't familiar with that and you want to go this route.

To clone the repository including the full history:

hg clone http://hg.squalllinesoftware.com/oss/disorder

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:

• ASIO >= 1.12.1
  • Either the standalone version of ASIO or the one built into boost can be used.
• Eigen >= 3.0.5
• Google Test/Mock >= 1.7.0
• At least one of the following geospatial conversion libraries:
  • GeographicLib >= 1.45
  • C++ version of the SEDRIS SRM >= 4.4.0
  • Patches to support other geospatial conversion libraries are welcome
• A Python interpreter (needed to use the waf build system)
• A C++ compiler capable of understanding the ISO C++ 2011 Standard
  • GCC >= 4.7.0
  • Clang++ >= 3.1.0
  • Visual Studio >= 2013 (version 12.x)
    • If you intend to use Visual Studio to build this thing on Windows, you're going to need at least 2013.
    • 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 environment, but you should expect some 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.

Debian Linux and Derivatives¶

Debian 6.x (Squeeze)¶

The binary packages in the package system are way too old. You'll have to download the source code and build them yourself.

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:

sudo apt-get install libasio-dev libeigen3-dev libgeographic-dev googletest google-mock

If you don't already have python, this will get the required bits of that:

sudo apt-get install python

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.

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 build system to configure and compile. In general terms, you want to invoke waf with the configure target like this:

./waf configure

On linux-like systems, waf will attempt to find dependencies installed in the general system location but you can override this behavior in the event of non-standard installation location or fanciful whimsy. The options for configuring disorder's dependencies can be found by issuing the following command:

./waf --help

Some of said options are thusly enumerated for your convenience:

ASIO¶

Option	Argument	Description
--asio-root	path to the root of the standalone ASIO library (eg. /opt/asio-1.10.8)	Tells disorder where to find the standalone ASIO library.
--asio-preferred-flavor	desired flavor of the ASIO library (standalone or boost)	Tells disorder which version of the ASIO library to use.

Boost¶

Option	Argument	Description
--exclude-boost	none	Tells disorder to not use Boost.
--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-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, windows) for more information.
--boost-toolset	desired toolset (eg. msvc, vc90, or gcc)	Overrides the automatic toolset detection as specified.

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.

GeographicLib¶

Option	Argument	Description
--geographiclib-root	path to the root of the GeographicLib tree (eg. /opt/GeographicLib-1.48)	Tells disorder where to find GeographicLib.
--geographiclib-static	none	Links disorder against the static GeographicLib instead of the default dynamic one.

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.
--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.

Google Test/Mock¶

Option	Argument	Description
--gtest-src-root	path to the root of the Google Test source tree (eg. /usr/src/gtest)	Tells disorder where to find the Google Test source tree.
--gmock-src-root	path to the root of the Google Mock source tree (eg. /usr/src/gmock)	Tells disorder where to find the Google Mock source tree.

GLUT¶

Option	Argument	Description
--glut-root	path to the root of the GLUT tree (eg. /opt/freeglut)	Tells disorder where to find GLUT.
--glut-lib	root name of the GLUT library	Tells disorder which GLUT library to link against. For example, specify 'glut' for libglut.so on linux or freeglut for freeglut.lib on windows.

0mq¶

Option	Argument	Description
--zmq-root	path to the 0MQ root (eg. /opt/zeromq-4.0.4)	Tells disorder where to find 0MQ.

Linux¶

From inside the root of the Disorder tree do this in your favorite terminal emulator:

./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here> --eigen-root=/opt/eigen

For example, if your SEDRIS SRM is in /opt/sedris/srm and your Eigen is in /opt/eigen:

./waf configure --sedris-srm-root=/opt/sedris/srm --eigen-root=/opt/eigen

That command will take several seconds and print a bunch of hopefully green stuff. The output should end up looking something like this:

Setting top to                           : /usr/local/src/disorder 
Setting out to                           : /usr/local/src/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 includes                  : 1.62.0 
Checking boost libs                      : ok 
Checking for boost linkage               : ok 
Checking for header boost/asio.hpp       : yes 
Checking for header boost/config.hpp     : yes 
Checking for header boost/detail/endian.hpp : yes 
Checking for header boost/filesystem/operations.hpp : yes 
Checking for header boost/preprocessor.hpp          : yes 
Checking for header boost/optional.hpp              : yes 
Checking for C++11 compiler support                 : 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/srm 
Checking for SEDRIS SRM include directory           : /opt/srm/src/include 
Checking for SEDRIS SRM library directory           : /opt/srm/lib/linux-4.9.0-2-amd64-i386-gnu-/OPT 
SEDRIS SRM library                                  : /opt/srm/lib/linux-4.9.0-2-amd64-i386-gnu-/OPT/libsrm.a 
SEDRIS SRM library mode                             : static 
Checking for header srf_all.h                       : yes 
Checking for library pthread                        : yes 
Checking for gtest source directory                 : /usr/src/googletest/googletest 
Checking for gtest-all.cc                           : /usr/src/googletest/googletest/src/gtest-all.cc 
Checking for gtest include directory                : /usr/src/googletest/googletest/include 
Checking for header gtest/gtest.h                   : yes 
Checking for gmock source directory                 : /usr/src/googletest/googlemock 
Checking for gmock-all.cc                           : /usr/src/googletest/googlemock/src/gmock-all.cc 
Checking for gmock_main.cc                          : /usr/src/googletest/googlemock/src/gmock_main.cc 
Checking for gmock include directory                : /usr/src/googletest/googlemock/include 
Checking for header gmock/gmock.h                   : yes 
Checking for library GL                             : yes 
Checking for library glut                           : yes 
Checking GLUT sanity                                : yes 
Checking for 0MQ                                    : yes 
Checking 0MQ sanity                                 : yes 
Checking for sane chrono duration modulo            : yes 
Checking for defaulted move functions               : yes 
Checking for array initializer lists                : yes 
Checking for sane std::chrono                       : yes 
'configure' finished successfully (6.832s)

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.

Clang++¶

To use the Clang C++ compiler instead of GCC, assuming clang++ is installed on the build system:

CXX=<put the path to clang++ here> ./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here>

For example:

CXX=/usr/bin/clang++ ./waf configure --sedris-srm-root=/opt/sedris/srm

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:

configure.bat

If everything is successful, you should get something that looks like this:

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)

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.

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.

Linux¶

On Linux, to build the Disorder debug variant:

./waf build_debug

Windows¶

On Windows, the waf script is invoked indirectly. To build the optimized variant:

python.exe waf build_optimized

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 run_unit_test_<variant> like this for the optimized variant:

./waf run_unit_test_optimized

That should result in something like this:

...
[----------] Global test environment tear-down
[==========] 772 tests from 75 test cases ran. (2071 ms total)
[  PASSED  ] 772 tests.

*PASS*: All tests passed!  This silly thing actually works properly.  Hooray!
Waf: Leaving directory `/usr/local/src/disorder/bin/debug'
'run_unit_test_debug' finished successfully (2.821s)

If you see

Something failed!  That's not good.  This build cannot be trusted until the damn thing is fixed.

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.

Building Against the Disorder Library¶

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.

Linking¶

Just link your program against Disorder's static library that can be found in the bin/<build variant> directory.