Project

General

Profile

Installation » History » Version 165

Tony Ciavarella, 07/29/2023 09:22 AM

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 94 Tony Ciavarella
Disorder doesn't have any official releases yet.  If/when that happens, release source tarballs will be 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 126 Tony Ciavarella
There's also a git mirror for those of you who fail to acknowledge the existence of any other SCM tools:
19
<pre>git clone https://git.squallline.com/oss/disorder.git</pre>
20
21 1 Tony Ciavarella
h2. Prerequisites
22
23 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:
24 114 Tony Ciavarella
25
These dependencies require manual intervention if your system doesn't already have them:
26 121 Tony Ciavarella
* The "meson":https://mesonbuild.com/ build system >= 0.50
27 114 Tony Ciavarella
** The "ninja":https://ninja-build.org build system
28
** A "Python 3":http://www.python.org interpreter
29 136 Tony Ciavarella
* A C++ compiler capable of understanding the "ISO C++ 2014 Standard":http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=50372
30
** "GCC":http://gcc.gnu.org >= 4.9.0
31
** "Clang++":http://clang.llvm.org >= 3.4.0
32 131 Tony Ciavarella
** Visual Studio >= 2017
33
*** If you intend to use Visual Studio to build this thing on Windows, you're going to need at least 2017.
34 114 Tony Ciavarella
*** gcc or clang can build disorder on windows in a "cygwin":http://cygwin.org/ environment.
35
** (optional) C++ version of the "SEDRIS SRM":http://www.sedris.org/srm_4.4/srm_c_cpp.htm >= 4.4.0
36
37
These dependencies will be acquired automatically during the build process if they aren't already on the build system:
38 82 Tony Ciavarella
* "ASIO":http://think-async.com >= 1.12.1
39 52 Tony Ciavarella
** Either the standalone version of ASIO or the one built into boost can be used.
40
* "Eigen":http://eigen.tuxfamily.org >= 3.0.5
41 136 Tony Ciavarella
* "Google Test/Mock":https://github.com/google/googletest >= 1.10.0
42 1 Tony Ciavarella
* At least one of the following geospatial conversion libraries:
43
** "GeographicLib":https://geographiclib.sourceforge.io >= 1.45
44
** Patches to support other geospatial conversion libraries are welcome
45 136 Tony Ciavarella
46 146 Tony Ciavarella
The library is actively compiled and tested on the following platforms as part of "continuous integration":https://jenkins.squallline.com/job/disorder
47 136 Tony Ciavarella
| *OS* | *Compiler* | *C++ Standard* |
48 147 Tony Ciavarella
|Linux|g++ 11.x|c++14|
49
|Linux|g++ 11.x|c++17|
50
|Linux|g++ 11.x|c++20|
51
|Linux|clang++ 13.x|c++14|
52
|Linux|clang++ 13.x|c++17|
53
|Linux|clang++ 13.x|c++20|
54 137 Tony Ciavarella
|Windows 10|Visual Studio 2017|c++14|
55
|Windows 10|Visual Studio 2019|c++14|
56
|Windows 10|Visual Studio 2019|c++17|
57 143 Tony Ciavarella
|Windows 10|Visual Studio 2022|c++14|
58
|Windows 10|Visual Studio 2022|c++17|
59 137 Tony Ciavarella
|Windows 10|Visual Studio 2022|c++20|
60 136 Tony Ciavarella
61
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.
62 1 Tony Ciavarella
63 115 Tony Ciavarella
Some platform specific hints follow.
64 1 Tony Ciavarella
65 8 Tony Ciavarella
h3. Debian Linux and Derivatives
66
67 107 Tony Ciavarella
If you don't already have meson, get it and its dependencies (python 3 and ninja):
68 105 Tony Ciavarella
<pre>sudo apt-get install meson</pre>
69 1 Tony Ciavarella
70 105 Tony Ciavarella
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.
71 82 Tony Ciavarella
72 105 Tony Ciavarella
If you'd rather install them on your system:
73 1 Tony Ciavarella
<pre>sudo apt-get install libasio-dev libeigen3-dev libgeographic-dev googletest google-mock</pre>
74 82 Tony Ciavarella
75 105 Tony Ciavarella
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.
76 1 Tony Ciavarella
77 125 Tony Ciavarella
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.
78 108 Tony Ciavarella
79 111 Tony Ciavarella
h3. Windows
80
81
You're going to need a python interpreter, meson, and ninja.  The "meson documentation":https://mesonbuild.com/Getting-meson.html describes how to get that done.
82
83 82 Tony Ciavarella
h2. Options
84 1 Tony Ciavarella
85 106 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 really want something different than the default.
86 46 Tony Ciavarella
87 82 Tony Ciavarella
To get a list of available options:
88
<pre>meson configure</pre>
89 1 Tony Ciavarella
90 82 Tony Ciavarella
Here are some useful options:
91
|_. Option |_. Argument |_. Description |
92 141 Tony Ciavarella
| cpp_std | c++14, c++17, c++20 | select the desired C++ standard (default: c++14) |
93 109 Tony Ciavarella
| default_library | shared, static, both | select the type of library to make (default: static) |
94 120 Tony Ciavarella
| buildtype | plain, debug, debugoptimized, release, minsize, custom | type of build to produce see "Running Meson":https://mesonbuild.com/Running-Meson.html for more details (default: debug) |
95 124 Tony Ciavarella
| 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) |
96 118 Tony Ciavarella
| build_examples | true, false | whether or not to build the disorder examples (default: false) |
97 122 Tony Ciavarella
| build_tools | true, false | whether or not to build the disorder tools (default: false) |
98 80 Tony Ciavarella
99 135 Tony Ciavarella
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.
100 1 Tony Ciavarella
101 82 Tony Ciavarella
h2. Configuration
102 13 Tony Ciavarella
103 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.
104 32 Tony Ciavarella
105 82 Tony Ciavarella
h3. General
106 13 Tony Ciavarella
107 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.
108 30 Tony Ciavarella
109 82 Tony Ciavarella
On Windows, meson will download all the dependencies, build, and utilize them out of the @subprojects@ subdirectory.
110 30 Tony Ciavarella
111 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.
112 1 Tony Ciavarella
113
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@.
114
115
Some of said options are thusly enumerated for your convenience:
116
117
h4. ASIO
118
119
|_. Option |_. Argument |_. Description |
120
| 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) |
121
| 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. |
122
123 128 Tony Ciavarella
h4. Boost
124
125
|_. Option |_. Argument |_. Description |
126
| 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) |
127 130 Tony Ciavarella
| 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":https://mesonbuild.com/Dependencies.html#boost for more details. |
128 129 Tony Ciavarella
| 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":https://mesonbuild.com/Dependencies.html#boost for more details. |
129
| 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":https://mesonbuild.com/Dependencies.html#boost for more details. |
130 128 Tony Ciavarella
131 1 Tony Ciavarella
h4. Eigen
132
133 30 Tony Ciavarella
|_. Option |_. Argument |_. Description |
134 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. |
135 90 Tony Ciavarella
136
h4. SEDRIS SRM
137
138
By default Disorder will use the "GeographicLib":https://geographiclib.sourceforge.io library.  If that's what you want, no extra setup is necessary.
139
140
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.
141
142
The following additional steps are required to use the SEDRIS SRM:
143
* 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.
144
* Put the srm_c_cpp_sdk_4.4.tgz file in a subdirectory off the root of the disorder source tree called subprojects/packagecache
145 117 Tony Ciavarella
* Use @-Denabled_geospatial_libraries=sedris_srm@ option when configuring disorder
146
** @-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
147
*** 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
148 30 Tony Ciavarella
149 161 Tony Ciavarella
h3. Building Disorder as a Shared Library
150
151
By default, disorder will be built as a static library.  If you'd rather have a shared library, configure disorder with @-Ddefault_library=shared@.  This will also build the GeographicLib dependency as a shared library by default.  If you'd rather link GeographicLib statically into the disorder shared library, also specify @-Dgeographiclib:default_library=static@.
152
153 82 Tony Ciavarella
h3. Creating a Build Directory and Configuring Disorder
154
155 1 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:
156 161 Tony Ciavarella
<pre>meson setup <build_dir> <options></pre>
157 139 Tony Ciavarella
For example, to use the C++17 standard and a <build_dir> called "build-c++17":
158 161 Tony Ciavarella
<pre>meson setup build-c++17 -Dcpp_std=c++17</pre>
159 10 Tony Ciavarella
160 82 Tony Ciavarella
If you see an error message from that step, it must be fixed in order to proceed.
161 1 Tony Ciavarella
162 110 Tony Ciavarella
h2. Platform Specific Notes
163
164 82 Tony Ciavarella
h3. Linux
165
166 23 Tony Ciavarella
h4. Clang++
167 1 Tony Ciavarella
168 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:
169 162 Tony Ciavarella
<pre>CXX=<put the path to clang++ here> meson setup <build_dir> <options></pre>
170 23 Tony Ciavarella
171 142 Tony Ciavarella
For example, to make a release build using C++20 with a build directory of build-clang-c++20-release:
172 162 Tony Ciavarella
<pre>CXX=clang++ meson setup build-clang-c++20-release -Dcpp_std=c++20 -Dbuildtype=release</pre>
173 23 Tony Ciavarella
174 26 Tony Ciavarella
h3. Windows
175 23 Tony Ciavarella
176 20 Tony Ciavarella
On windows, your $PATH environment variable needs to include the path to the Python interpreter.
177 1 Tony Ciavarella
178 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.
179 20 Tony Ciavarella
180 101 Tony Ciavarella
Also, shared libraries cannot be used on windows as Disorder does not properly export symbols.  Patches welcome.
181
182 155 Tony Ciavarella
h4. Stepping into Disorder while Debugging in Visual Studio
183
184
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.
185
186
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.
187
188 148 Tony Ciavarella
h4. Building display with Npcap
189
190 157 Tony Ciavarella
The "Npcap SDK":https://npcap.com is required in order to build display (the DIS packet capture replay tool) on Windows and the Npcap runtime is required to be installed to run display on Windows.  The "Npcap free license":https://github.com/nmap/npcap/blob/master/LICENSE does not allow for redistribution, so disorder cannot automatically fetch, build, and install it for you as a convenient meson subproject like most of the other dependencies of the library.  You actually have to do some manual stuff if you want to use display.  Don't panic.  It's not too difficult.  You can do it.
191 148 Tony Ciavarella
192 150 Tony Ciavarella
Steps to build display tool on Windows:
193 132 Tony Ciavarella
* Download and unzip the latest version of the Npcap SDK to an arbitrary location on the build machine.
194
* When configuring disorder, supply the -Dbuild_tools=true and -Dnpcap_sdk_root="<Npcap SDK directory>" arguments where <Npcap SDK directory> should be replaced the with actual location of the unzipped Npcap SDK archive.  For example, specify -Dnpcap_sdk_root="C:\windows\Program Files\Npcap SDK" if that's where you stuck it.
195
* Then just build disorder like normal.  It'll spit out an additional display.exe executable eventually.  If you use the ninja meson backend, the executable can be found in disorder/<build directory>/tools/display.
196
197 158 Tony Ciavarella
In order to run display, wpcap.dll and Packet.dll from the Npcap runtime need to be in the DLL search path.  One way to make that happen is to update the PATH environment variable to include C:\Windows\System32\Npcap which is the default installation location for those things.  The Npcap SDK is only required on the build machine and is not required to run the display executable.  Similarly, the Npcap runtime is not required on the build machine, only on a machine that runs display.
198 132 Tony Ciavarella
199 160 Tony Ciavarella
NOTE: It might be possible to use the @npcap_sdk_root@ option to build display against the last released SDK of the original more liberally licensed but defunct "WinPcap":https://www.winpcap.org but that's not something actively supported.  If you do try it and find some issues, patches are welcome to make this work.
200 159 Tony Ciavarella
201 20 Tony Ciavarella
h2. Compiling
202
203 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.
204 23 Tony Ciavarella
205 82 Tony Ciavarella
This is generally all it takes:
206
<pre>cd build
207
ninja</pre>
208 43 Tony Ciavarella
209 44 Tony Ciavarella
h2. Ensuring Build Correctness
210 43 Tony Ciavarella
211 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.
212
213 88 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 from inside your build directory like this:
214 82 Tony Ciavarella
<pre>ninja test</pre>
215 1 Tony Ciavarella
216 67 Tony Ciavarella
That should result in something like this:
217
<pre>
218 85 Tony Ciavarella
[0/1] Running all tests.
219 103 Tony Ciavarella
1/1 disorder unit test                      OK       0.42 s
220 1 Tony Ciavarella
221 84 Tony Ciavarella
Ok:                    1
222
Expected Fail:         0
223
Fail:                  0
224
Unexpected Pass:       0
225
Skipped:               0
226
Timeout:               0
227
228
Full log written to /usr/local/src/disorder/build/meson-logs/testlog.txt
229 73 Tony Ciavarella
</pre>
230 84 Tony Ciavarella
231 96 Tony Ciavarella
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.
232 43 Tony Ciavarella
233 93 Tony Ciavarella
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.
234 43 Tony Ciavarella
235
h2. Building Against the Disorder Library
236
237 82 Tony Ciavarella
h3. Installing Disorder
238 28 Tony Ciavarella
239 112 Tony Ciavarella
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:
240 1 Tony Ciavarella
<pre>DESTDIR=/opt ninja install</pre>
241 112 Tony Ciavarella
242
Windows wants you to type more stuff.  To install disorder under C:\best_libraries_ever:
243
<pre>set DESTDIR=C:\best_libraries_ever
244
ninja install
245 113 Tony Ciavarella
</pre>
246 28 Tony Ciavarella
247 82 Tony Ciavarella
h3. Compiling Your Project Against Disorder
248 28 Tony Ciavarella
249 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.
250
251 163 Tony Ciavarella
h4. Using Disorder as a Shared Library
252
253 165 Tony Ciavarella
When building your brilliant stuff against the disorder shared library, the @DISORDER_DSO@ preprocessor definition must defined in order for the symbols from the shared library to be imported properly.  If you build your thingy with meson, that will happen automatically when your thingy depends on the @disorder_dep@ meson dependency.  If you aren't using meson, then it can be done by adding @-DDISORDER_DSO@ to the command line of GCC-like compilers.  For cl.exe, the command line is @/DDISORDER_DSO@.  Stick @DISORDER_DSO@ in the right box in Visual Studio somewhere that might be close to something like Properties->C/C++->Preprocessor->Preprocessor Definitions on your project.  You can also define it programmatically in some file, like a precompiled header that is included in everything that uses disorder, if you prefer that.  There are probably more options.  Just get the damn thing defined prior to #including disorder stuff.
254 163 Tony Ciavarella
255 82 Tony Ciavarella
h3. Linking Your Project With Disorder
256
257 97 Tony Ciavarella
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.
258 145 Tony Ciavarella
259
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.