Installation » History » Revision 82
Revision 81 (Tony Ciavarella, 11/12/2018 07:45 PM) → Revision 82/175 (Tony Ciavarella, 11/28/2019 02:06 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":https://www.mercurial-scm.org 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: * "ASIO":http://think-async.com >= 1.12.1 ** Either the standalone version of ASIO or the one built into boost can be used. * "Eigen":http://eigen.tuxfamily.org >= 3.0.5 * "Google Test/Mock":https://github.com/google/googletest >= 1.7.0 * At least one of the following geospatial conversion libraries: ** "GeographicLib":https://geographiclib.sourceforge.io >= 1.45 ** C++ version of the "SEDRIS SRM":http://www.sedris.org/srm_4.4/srm_c_cpp.htm >= 4.4.0 ** Patches to support other geospatial conversion libraries are welcome * A "Python 3":http://www.python.org "Python":http://www.python.org interpreter (needed to use the "meson":https://mesonbuild.com/ "waf":https://waf.io/ build system) * The ninja 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 (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":http://cygwin.org/ environment, but you should expect some pain. 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 in the package system are way too old. You'll have to download the source code and build them 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 libasio-dev libeigen3-dev libgeographic-dev googletest google-mock</pre> If you don't already have meson, python, this will get the that and its dependencies (python 3 and ninja): required bits of that: <pre>sudo apt-get install meson</pre> python</pre> h2. Options There are various options available to control things. If you don't know what you want, you can skip this section as disorder will try to do something sane. Don't worry, you can change options later and rebuild if you decide you want something different than the default. To get a list of available options: <pre>meson configure</pre> Here are some useful options: |_. Option |_. Argument |_. Description | | cpp_std | c++11, c++14, c++17 | select the desired C++ standard (default: c++11) | | default_library | shared, static, both | select the type of library to make (default: shared on Linux, static on Windows) | | buildtype | plain, debug, debugoptimized, release, minsize, custom | type of build to produce (default: debug) | | wrap_mode | default, nofallback, nodownload, forcefallback | controls how dependencies are found see "Meson FAQ":https://mesonbuild.com/FAQ.html#does-wrap-download-sources-behind-my-back for more details (default: default) | Options are applied as arguments to meson setup when running the configuration step described below. The options are specified as @--<option>=<value>@ where <option> is the option to set and <value> is the value to set it to. For example, to use the C++14 standard, supply @--cpp_std=c++14@ to meson. h3. Geogspatial Libraries By default Disorder will use the "GeographicLib":https://geographiclib.sourceforge.io library. No extra setup is necessary. h4. Using SEDRIS SRM Because the SEDRIS SRM creators don't give away their source code without having an account in their system and forcing people to agree to their license, Disorder is not distributed with the SEDRIS SRM and cannot automatically download it for you. The following additional steps are required to use the SEDRIS SRM: * Download the "SEDRIS SRM":http://www.sedris.org/srm_4.4/srm_c_cpp.htm source code .tgz file. *NOTE*: Always pick the Unix version even on Windows. They are the same except for the compression format. * Put the srm_c_cpp_sdk_4.4.tgz file in a subdirectory off the root of the disorder source tree called subprojects/packagecache * Use @--enabled_geospatial_libraries=sedris_srm@ option when configuring disorder ** @--enabled_geospatial_libraries=sedris_srm,geographic_lib@ can be used to include support for both libraries allowing run-time selection of the one that gets used *** If both libraries are enabled and you want to use SEDIRS_SRM by default instead of GeographicLib, also apply the @--preferred_geospatial_library=sedris_srm@ option 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 "meson":https://mesonbuild.com "waf":https://code.google.com/p/waf/ build system to configure and generate a "ninja":https://ninja-build.org recipe for compilation. On Windows, meson will download all compile. In general terms, you want to invoke waf with the dependencies, build, and utilize them out of the @subprojects@ subdirectory. configure target like this: <pre>./waf configure</pre> On linux-like systems, meson waf will attempt to find dependencies installed in the general system location falling back to downloading them and using them out of the @subprojects@ subdirectory. If but you don't want the default behavior on your platform, you can override it using options. this behavior in the event of non-standard installation location or fanciful whimsy. The options for configuring disorder's dependencies can be found via @meson configure@. by issuing the following command: <pre>./waf --help</pre> Some of said options are thusly enumerated for your convenience: h4. ASIO |_. Option |_. Argument |_. Description | | asio --asio-root | default, standalone, boost | Select path to the preferred version root of the standalone ASIO library (eg. /opt/asio-1.10.8) | Tells disorder where to find the standalone ASIO library. The default option prefers | | --asio-preferred-flavor | desired flavor of the standalone ASIO library (standalone or boost) | Tells disorder which version with a fallback of the ASIO library to boost if the standalone version is use. | h4. Boost |_. Option |_. Argument |_. Description | | --exclude-boost | none | Tells disorder to not found. (default: default) use Boost. | | asio_root --boost-includes | path to the Boost includes root of (eg. /opt/boost_1_49_0) | Tells disorder where to find the standalone ASIO library include files for the Boost libraries. | | --boost-libs | path to the directory where the compiled Boost libraries are (eg. /opt/asio-1.10.8) /opt/boost_1_49_0/stage/lib) | Tells disorder where to find Boost's compiled library files. | | --boost-mt | none | Links disorder against the standalone ASIO library. 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 --eigen-root | path to the root of the Eigen library (eg. /opt/eigen-3.1.2) | Tells disorder where to find the Eigen library. | h3. Creating a Build Directory and Configuring Disorder h4. GeographicLib Once you've decided on |_. Option |_. Argument |_. Description | | --geographiclib-root | path to the options, make a <build_dir> 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. | 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. | | --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 and configure (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. | h4. 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 <options> should be replaced with to find the desired options: Google Test source tree. | <pre>meson <build_dir> <options></pre> | --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. | h4. GLUT |_. Option |_. Argument |_. Description | For example | --glut-root | path to use the C++17 standard and a <build_dir> called "build-c++17": root of the GLUT tree (eg. /opt/freeglut) | Tells disorder where to find GLUT. | <pre>meson build-c++17 --cpp_std=c++17</pre> | --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. | If you see an error message from that step, it must be fixed in order h4. 0mq |_. Option |_. Argument |_. Description | | --zmq-root | path to proceed. the 0MQ root (eg. /opt/zeromq-4.0.4) | Tells disorder where to find 0MQ. | 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> --eigen-root=/opt/eigen</pre> For example, if your SEDRIS SRM is in /opt/sedris/srm and your Eigen is in /opt/eigen: <pre>./waf configure --sedris-srm-root=/opt/sedris/srm --eigen-root=/opt/eigen</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 : /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) </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> meson <build_dir> <options></pre> ./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here></pre> For example, to make a release build using C++14 with a buid directory of build-clang-c++14-release: example: <pre>CXX=/usr/bin/clang++ meson build-clang-c++14-release --cpp_std=c++14 --buildtype=release</pre> ./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. If you're using The easiest way to configure Disorder on Windows is to use a modified version of the Visual Studio compiler, you must run provided batch file to tell Disorder where your prerequisites live. Copy the configuration and compilation steps template from within @tools/windows/configure.bat@ to the appropriate 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 command prompt 10.0\VC\BIN\amd64\CL.exe Checking for the configuration 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 want don't see that last line that says @'configure' finished successfully@, then something is screwed up and it needs to build for. be fixed. Fix it and try again. h2. Compiling The basic strategy for building Disorder is to invoke the ninja waf build system from within with the desired build directory 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 configuration step. @build_debug@ build target and the @optimized@ variant is produced by the @build_optimized@ build target. This 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 generally all it takes: <pre>cd invoked indirectly. To build the @optimized@ variant: ninja</pre> <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 ninja waf to run run_unit_test_<variant> like this for the unit test like this: @optimized@ variant: <pre>ninja test</pre> <pre>./waf run_unit_test_optimized</pre> That should result in something like this: <pre> ... [----------] Global test environment tear-down [==========] 2350 772 tests from 128 75 test suites cases ran. (900 (2071 ms total) [ PASSED ] 2350 772 tests. RUN FINISHED; exit value 0; real time: 990ms; user: 130ms; system: 970ms *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) </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 less happy 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. Disorder does not have any known flaky unit tests. If a test doesn't work, something is broken. h2. Building Against the Disorder Library h3. Installing Disorder Disorder can be installed somewhere on your system. To do that, issue the @ninja install@ command from inside your build directory. If you want to control where that sticks stuff, add @DESTDIR=<dest_dir>@ to the front that where <dest_dir> is where you want to install it. For example, to install disorder under /opt: <pre>DESTDIR=/opt ninja install</pre> h3. Compiling Your Project Against Disorder In order to compile your goodness against the Disorder library, you'll need to have the installed header files from the @src@ directory in the Disorder tree and Eigen's include directory in your compiler's include path. The geospatial libraries aren't exposed so you don't You do not need those anything from SEDRIS SRM in your include path. h3. Linking Your Project With Disorder Just link your program against Disorder's static library that can be found in the @<build>/src/disorder@ @bin/<build variant>@ directory.