Project

General

Profile

Actions

Installation » History » Revision 146

« Previous | Revision 146/175 (diff) | Next »
Tony Ciavarella, 05/23/2022 03:42 AM


Installation

Obtaining the Source Code

Release Tarballs

Disorder doesn't have any official releases yet. If/when that happens, release source tarballs will be 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

There's also a git mirror for those of you who fail to acknowledge the existence of any other SCM tools:

git clone https://git.squallline.com/oss/disorder.git

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:

These dependencies require manual intervention if your system doesn't already have them:
  • The meson build system >= 0.50
  • A C++ compiler capable of understanding the ISO C++ 2014 Standard
    • GCC >= 4.9.0
    • Clang++ >= 3.4.0
    • Visual Studio >= 2017
      • If you intend to use Visual Studio to build this thing on Windows, you're going to need at least 2017.
      • gcc or clang can build disorder on windows in a cygwin environment.
    • (optional) C++ version of the SEDRIS SRM >= 4.4.0
These dependencies will be acquired automatically during the build process if they aren't already on the build system:
  • 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.10.0
  • At least one of the following geospatial conversion libraries:
    • GeographicLib >= 1.45
    • Patches to support other geospatial conversion libraries are welcome
The library is actively compiled and tested on the following platforms as part of continuous integration
OS Compiler C++ Standard
Linux g++ 10.x c++14
Linux g++ 10.x c++17
Linux g++ 10.x c++20
Linux clang++ 12.x c++14
Linux clang++ 12.x c++17
Linux clang++ 12.x c++20
Windows 10 Visual Studio 2017 c++14
Windows 10 Visual Studio 2019 c++14
Windows 10 Visual Studio 2019 c++17
Windows 10 Visual Studio 2022 c++14
Windows 10 Visual Studio 2022 c++17
Windows 10 Visual Studio 2022 c++20

The library likely works on may other platform and compiler combinations, but these are the ones actively tested. Portability patches to support other platforms are welcome.

Some platform specific hints follow.

Debian Linux and Derivatives

If you don't already have meson, get it and its dependencies (python 3 and ninja):

sudo apt-get install meson

That's it. You can optionally install the Disorder build dependencies from the package manager. If the dependencies aren't installed on the system, Disorder will automatically download their source code and build them with the library.

If you'd rather install them on your system:

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

This may install older packages than the ones that Disorder is known to work with. That may not work out so awesome. Consider yourself warned.

If you've got some of the dependencies installed on your system but you want Disorder to download and build the versions the library likes, specify the -Dwrap_mode=forcefallback option to meson. That will make it ignore your system libraries.

Windows

You're going to need a python interpreter, meson, and ninja. The meson documentation describes how to get that done.

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 really want something different than the default.

To get a list of available options:

meson configure

Here are some useful options:
Option Argument Description
cpp_std c++14, c++17, c++20 select the desired C++ standard (default: c++14)
default_library shared, static, both select the type of library to make (default: static)
buildtype plain, debug, debugoptimized, release, minsize, custom type of build to produce see Running Meson for more details (default: debug)
wrap_mode default, nofallback, nodownload, forcefallback controls how dependencies are found see Meson FAQ for more details (default: default)
build_examples true, false whether or not to build the disorder examples (default: false)
build_tools true, false whether or not to build the disorder tools (default: false)

Options are applied as arguments to meson setup when running the configuration step described below. The options are specified as -D<option>=<value> where <option> is the option to set and <value> is the value to set it to. For example, to use the C++17 standard, supply -Dcpp_std=c++17 to meson.

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 meson build system to configure and generate a ninja recipe for compilation.

On Windows, meson will download all the dependencies, build, and utilize them out of the subprojects subdirectory.

On linux-like systems, meson 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 you don't want the default behavior on your platform, you can override it using options. The options for configuring disorder's dependencies can be found via meson configure.

Some of said options are thusly enumerated for your convenience:

ASIO

Option Argument Description
asio default, standalone, boost Select the preferred version of the ASIO library. The default option prefers the standalone version with a fallback to boost if the standalone version is not found. (default: default)
asio_root path to the root of the standalone ASIO library (eg. /opt/asio-1.12.2) Tells disorder where to find the standalone ASIO library.

Boost

Option Argument Description
boost auto, require, exclude This option controls how the boost library is used. The auto option prefers C++ standard things falling back to boost when possible. The require option mandates boost header usage over system stuff. The exclude option never uses boost. (default: auto)
boost_root non-standard installation location of boost This is a standard option provided by Meson. Use this option or (boost_include and boost_librarydir) but not all three. See the Meson Manual for more details.
boost_include non-standard installation location of boost headers This is a standard option provided by Meson. Use this option with boost_librarydir when boost_root isn't good enough. See the Meson Manual for more details.
boost_librarydir non-standard installation location of boost libraries This is a standard option provided by Meson. Use this option with boost_include when boost_root isn't good enough. See the Meson Manual for more details.

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.

SEDRIS SRM

By default Disorder will use the GeographicLib library. If that's what you want, no extra setup is necessary.

If you want to use the SEDRIS SRM, there's a little more work to do. Because the SEDRIS SRM creators don't give away their source code without forcing people to have an account in their system and 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 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 -Denabled_geospatial_libraries=sedris_srm option when configuring disorder
    • -Denabled_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 -Dpreferred_geospatial_library=sedris_srm option

Creating a Build Directory and Configuring Disorder

Once you've decided on the options, make a <build_dir> directory and configure disorder where <options> should be replaced with the desired options:

meson <build_dir> <options>

For example, to use the C++17 standard and a <build_dir> called "build-c++17":
meson build-c++17 -Dcpp_std=c++17

If you see an error message from that step, it must be fixed in order to proceed.

Platform Specific Notes

Linux

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> meson <build_dir> <options>

For example, to make a release build using C++20 with a build directory of build-clang-c++20-release:

CXX=clang++ meson build-clang-c++20-release -Dcpp_std=c++20 -Dbuildtype=release

Windows

On windows, your $PATH environment variable needs to include the path to the Python interpreter.

If you're using the Visual Studio compiler, you must run the configuration and compilation steps from within the appropriate Visual Studio command prompt for the configuration you want to build for.

Also, shared libraries cannot be used on windows as Disorder does not properly export symbols. Patches welcome.

Stepping into Disorder while Debugging in Visual Studio

Visual Studio doesn't make overall .pdb files for static libraries. Instead, the default behavior is create .pdb files for each compilation unit and then put absolute path links to those .pdb files in each .o. Those absolute paths wind up in the static library. So, the debug information is only available if the debug session occurs on the same machine that built the static library and the build artifacts still exist in the original location or one recreates this mess on the machine one wishes to perform the debugging on.

The work around for this almost always unhelpful behavior is to replace the /Zi argument sent to cl.exe with /Z7. Meson does not provide a convenient way to do this, but it can be made to do it by slapping add_global_arguments('/Z7', language: 'cpp') in the meson.build at the top level of disorder and rebuilding it using -Dbuildtype=debug (for /MTd) or -Dbuildtype=debugoptimized (for /MT). This will spew one warning per build file about how it's overriding /Zi with /Z7. Cheerfully ignore that. Then the resultant disorder static library will contain built-in debug information without any need for .pdb files. That static library can be installed and moved/copied around at will. It will be significantly larger than when it's built with /Zi. When the static library is linked into an .exe or .dll, the debug information will not be put in that product .exe or .dll, at that point it will go into that thing's .pdb file.

Compiling

The basic strategy for building Disorder is to invoke the ninja build system from within the build directory produced by the configuration step.

This is generally all it takes:

cd build
ninja

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 to run the unit test from inside your build directory like this:

ninja test

That should result in something like this:

[0/1] Running all tests.
1/1 disorder unit test                      OK       0.42 s

Ok:                    1
Expected Fail:         0
Fail:                  0
Unexpected Pass:       0
Skipped:               0
Timeout:               0

Full log written to /usr/local/src/disorder/build/meson-logs/testlog.txt

Ninja thinks there is only one test, but it ran the full test suite which contains thousands of tests. Yes, it can do them all in less than a second depending on your hardware. If you see something besides "OK" on line 2 and "Ok: 1" on line 4, things are not okay. Look at the full log specified on the last output line to see exactly what went wrong.

If it's unhappy, please 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.

Building Against the Disorder Library

Installing Disorder

Disorder can be installed somewhere on your system to make a neat little package out of all the things you'll need to build something against the library. 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 in Linux:

DESTDIR=/opt ninja install

Windows wants you to type more stuff. To install disorder under C:\best_libraries_ever:

set DESTDIR=C:\best_libraries_ever
ninja install

Compiling Your Project Against Disorder

In order to compile your goodness against the Disorder library, you'll need to have the installed header files in your compiler's include path. The geospatial libraries aren't exposed so you don't need those in your include path.

Linking Your Project With Disorder

Just link your program against Disorder's library that can be found in the <build>/src/disorder directory. If you've installed Disorder using ninja, the library will be in the appropriate location under the installation root path.

On windows, if the linker complains about the GetAdaptersInfo symbol not being defined, link the damn thing with iphlpapi.lib. If you use meson, this will happen automatically when using the disorder_dep dependency.

Updated by Tony Ciavarella almost 2 years ago · 146 revisions