Project

General

Profile

Installation » History » Version 85

Tony Ciavarella, 11/28/2019 02:10 PM

1 1 Tony Ciavarella
h1. Installation
2
3 5 Tony Ciavarella
h2. Obtaining the Source Code
4 1 Tony Ciavarella
5 2 Tony Ciavarella
h3. Release Tarballs
6
7 4 Tony Ciavarella
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.
8 2 Tony Ciavarella
9
h3. SCM
10
11 72 Tony Ciavarella
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.
12 2 Tony Ciavarella
13 54 Tony Ciavarella
Read the "Mercurial Documentation":http://hgbook.red-bean.com/ if you aren't familiar with that and you want to go this route.
14 27 Tony Ciavarella
15 53 Tony Ciavarella
To clone the repository including the full history:
16 54 Tony Ciavarella
<pre>hg clone http://hg.squalllinesoftware.com/oss/disorder</pre>
17 2 Tony Ciavarella
18 1 Tony Ciavarella
h2. Prerequisites
19
20 38 Tony Ciavarella
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:
21 81 Tony Ciavarella
* "ASIO":http://think-async.com >= 1.12.1
22 77 Tony Ciavarella
** Either the standalone version of ASIO or the one built into boost can be used.
23 1 Tony Ciavarella
* "Eigen":http://eigen.tuxfamily.org >= 3.0.5
24
* "Google Test/Mock":https://github.com/google/googletest >= 1.7.0
25 79 Tony Ciavarella
* At least one of the following geospatial conversion libraries:
26 77 Tony Ciavarella
** "GeographicLib":https://geographiclib.sourceforge.io >= 1.45
27
** C++ version of the "SEDRIS SRM":http://www.sedris.org/srm_4.4/srm_c_cpp.htm >= 4.4.0
28
** Patches to support other geospatial conversion libraries are welcome
29 82 Tony Ciavarella
* A "Python 3":http://www.python.org interpreter (needed to use the "meson":https://mesonbuild.com/ build system)
30
* The ninja build system
31 52 Tony Ciavarella
* 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
32
** "GCC":http://gcc.gnu.org >= 4.7.0
33
** "Clang++":http://clang.llvm.org >= 3.1.0
34 78 Tony Ciavarella
** Visual Studio >= 2013 (version 12.x)
35 63 Tony Ciavarella
*** If you intend to use Visual Studio to build this thing on Windows, you're going to need at least 2013.
36 82 Tony Ciavarella
*** You can, of course, use gcc to build disorder on windows in a "cygwin":http://cygwin.org/ environment, but you should expect some pain.
37 1 Tony Ciavarella
38 13 Tony Ciavarella
Build and install these things in accordance with the instructions for your operating system provided by each vendor.  Some hints for certain platforms follow.
39 1 Tony Ciavarella
40 8 Tony Ciavarella
h3. Debian Linux and Derivatives
41
42 39 Tony Ciavarella
h4. Debian 6.x (Squeeze)
43 41 Tony Ciavarella
44 78 Tony Ciavarella
The binary packages in the package system are way too old.  You'll have to download the source code and build them yourself.
45 1 Tony Ciavarella
46 39 Tony Ciavarella
h4. Debian >= 7.x (Wheezy)
47 33 Tony Ciavarella
48 82 Tony Ciavarella
All the dependencies are available via the package system.  To install the build dependencies on Debian and maybe other derivatives:
49 33 Tony Ciavarella
<pre>sudo apt-get install libasio-dev libeigen3-dev libgeographic-dev googletest google-mock</pre>
50 1 Tony Ciavarella
51 82 Tony Ciavarella
If you don't already have meson, this will get the that and its dependencies (python 3 and ninja):
52
<pre>sudo apt-get install meson</pre>
53 1 Tony Ciavarella
54 82 Tony Ciavarella
h2. Options
55 1 Tony Ciavarella
56 82 Tony Ciavarella
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.
57 46 Tony Ciavarella
58 82 Tony Ciavarella
To get a list of available options:
59
<pre>meson configure</pre>
60 1 Tony Ciavarella
61 82 Tony Ciavarella
Here are some useful options:
62
|_. Option |_. Argument |_. Description |
63
| cpp_std | c++11, c++14, c++17 | select the desired C++ standard (default: c++11) |
64
| default_library | shared, static, both | select the type of library to make (default: shared on Linux, static on Windows) |
65
| buildtype | plain, debug, debugoptimized, release, minsize, custom | type of build to produce (default: debug) |
66
| 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) |
67 80 Tony Ciavarella
68 82 Tony Ciavarella
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.
69 1 Tony Ciavarella
70 82 Tony Ciavarella
h3. Geogspatial Libraries
71 1 Tony Ciavarella
72 82 Tony Ciavarella
By default Disorder will use the "GeographicLib":https://geographiclib.sourceforge.io library.  No extra setup is necessary.
73 46 Tony Ciavarella
74 82 Tony Ciavarella
h4. Using SEDRIS SRM
75 1 Tony Ciavarella
76 82 Tony Ciavarella
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.
77 1 Tony Ciavarella
78 82 Tony Ciavarella
The following additional steps are required to use the SEDRIS SRM:
79
* 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.
80
* Put the srm_c_cpp_sdk_4.4.tgz file in a subdirectory off the root of the disorder source tree called subprojects/packagecache
81
* Use @--enabled_geospatial_libraries=sedris_srm@ option when configuring disorder
82
** @--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
83
*** 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
84 64 Tony Ciavarella
85 82 Tony Ciavarella
h2. Configuration
86 13 Tony Ciavarella
87 82 Tony Ciavarella
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.
88 32 Tony Ciavarella
89 82 Tony Ciavarella
h3. General
90 13 Tony Ciavarella
91 82 Tony Ciavarella
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 build system to configure and generate a "ninja":https://ninja-build.org recipe for compilation.
92 30 Tony Ciavarella
93 82 Tony Ciavarella
On Windows, meson will download all the dependencies, build, and utilize them out of the @subprojects@ subdirectory.
94 30 Tony Ciavarella
95 82 Tony Ciavarella
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.
96 30 Tony Ciavarella
97 82 Tony Ciavarella
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@.
98 30 Tony Ciavarella
99 82 Tony Ciavarella
Some of said options are thusly enumerated for your convenience:
100 30 Tony Ciavarella
101 82 Tony Ciavarella
h4. ASIO
102 30 Tony Ciavarella
103
|_. Option |_. Argument |_. Description |
104 82 Tony Ciavarella
| 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) |
105 83 Tony Ciavarella
| 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. |
106 30 Tony Ciavarella
107 82 Tony Ciavarella
h4. Eigen
108 30 Tony Ciavarella
109
|_. Option |_. Argument |_. Description |
110 82 Tony Ciavarella
| eigen_root | path to the root of the Eigen library (eg. /opt/eigen-3.1.2) | Tells disorder where to find the Eigen library. |
111 30 Tony Ciavarella
112 82 Tony Ciavarella
h3. Creating a Build Directory and Configuring Disorder
113 30 Tony Ciavarella
114 82 Tony Ciavarella
Once you've decided on the options, make a <build_dir> directory and configure disorder where <options> should be replaced with the desired options:
115
<pre>meson <build_dir> <options></pre>
116
For example to use the C++17 standard and a <build_dir> called "build-c++17":
117
<pre>meson build-c++17 --cpp_std=c++17</pre>
118 10 Tony Ciavarella
119 82 Tony Ciavarella
If you see an error message from that step, it must be fixed in order to proceed.
120 1 Tony Ciavarella
121 82 Tony Ciavarella
h3. Linux
122
123 20 Tony Ciavarella
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.
124 23 Tony Ciavarella
125
h4. Clang++
126 1 Tony Ciavarella
127 23 Tony Ciavarella
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:
128 82 Tony Ciavarella
<pre>CXX=<put the path to clang++ here> meson <build_dir> <options></pre>
129 23 Tony Ciavarella
130 82 Tony Ciavarella
For example, to make a release build using C++14 with a buid directory of build-clang-c++14-release:
131
<pre>CXX=/usr/bin/clang++ meson build-clang-c++14-release --cpp_std=c++14 --buildtype=release</pre>
132 23 Tony Ciavarella
133 26 Tony Ciavarella
h3. Windows
134 23 Tony Ciavarella
135 20 Tony Ciavarella
On windows, your $PATH environment variable needs to include the path to the Python interpreter.
136 1 Tony Ciavarella
137 82 Tony Ciavarella
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.
138 20 Tony Ciavarella
139
h2. Compiling
140
141 82 Tony Ciavarella
The basic strategy for building Disorder is to invoke the ninja build system from within the build directory produced by the configuration step.
142 23 Tony Ciavarella
143 82 Tony Ciavarella
This is generally all it takes:
144
<pre>cd build
145
ninja</pre>
146 43 Tony Ciavarella
147 44 Tony Ciavarella
h2. Ensuring Build Correctness
148 43 Tony Ciavarella
149 67 Tony Ciavarella
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.
150
151 82 Tony Ciavarella
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 like this:
152
<pre>ninja test</pre>
153 1 Tony Ciavarella
154 67 Tony Ciavarella
That should result in something like this:
155
<pre>
156 85 Tony Ciavarella
[0/1] Running all tests.
157
1/1 disorder unit test                      OK       0.92 s
158 1 Tony Ciavarella
159 84 Tony Ciavarella
Ok:                    1
160
Expected Fail:         0
161
Fail:                  0
162
Unexpected Pass:       0
163
Skipped:               0
164
Timeout:               0
165
166
Full log written to /usr/local/src/disorder/build/meson-logs/testlog.txt
167 73 Tony Ciavarella
</pre>
168 84 Tony Ciavarella
169
This output is misleading because it really ran the full test suite which contains thousands of tests, but if you see anything but 1 test in the "Ok", things are not okay.  Look at the full log specified on the last output line to see exactly what went wrong.
170 43 Tony Ciavarella
171 82 Tony Ciavarella
If you see a less happy 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.
172 43 Tony Ciavarella
173
h2. Building Against the Disorder Library
174
175 82 Tony Ciavarella
h3. Installing Disorder
176 28 Tony Ciavarella
177 82 Tony Ciavarella
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:
178
<pre>DESTDIR=/opt ninja install</pre>
179 28 Tony Ciavarella
180 82 Tony Ciavarella
h3. Compiling Your Project Against Disorder
181 28 Tony Ciavarella
182 82 Tony Ciavarella
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.
183
184
h3. Linking Your Project With Disorder
185
186
Just link your program against Disorder's library that can be found in the @<build>/src/disorder@ directory.