Project

General

Profile

Installation » History » Version 81

Tony Ciavarella, 11/12/2018 07:45 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 71 Tony Ciavarella
* A "Python":http://www.python.org interpreter (needed to use the "waf":https://waf.io/ build system)
30 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
31
** "GCC":http://gcc.gnu.org >= 4.7.0
32
** "Clang++":http://clang.llvm.org >= 3.1.0
33 78 Tony Ciavarella
** Visual Studio >= 2013 (version 12.x)
34
*** If you intend to use Visual Studio to build this thing on Windows, you're going to need at least 2013.
35 63 Tony Ciavarella
*** The express version may work, but using it to build an open source project may be a violation of Microsoft's silly license.
36 78 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 because SEDRIS won't build on cygwin out of the box.
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 42 Tony Ciavarella
All the dependencies are available via the package system.  To install the Boost and Eigen 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 37 Tony Ciavarella
51 33 Tony Ciavarella
If you don't already have python, this will get the required bits of that:
52 35 Tony Ciavarella
<pre>sudo apt-get install python</pre>
53 34 Tony Ciavarella
54 13 Tony Ciavarella
h2. Configuration
55
56
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.
57
58 46 Tony Ciavarella
h3. General
59
60
The basic idea of configuration is to allow disorder to learn enough about your build platform to be able to compile.  Disorder uses the 
61 47 Tony Ciavarella
"waf":https://code.google.com/p/waf/ build system to configure and compile. In general terms, you want to invoke waf with the configure target like this:
62 46 Tony Ciavarella
<pre>./waf configure</pre>
63
64 80 Tony Ciavarella
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:
65 46 Tony Ciavarella
<pre>./waf --help</pre>
66
67 80 Tony Ciavarella
Some of said options are thusly enumerated for your convenience:
68 1 Tony Ciavarella
69 80 Tony Ciavarella
h4. ASIO
70
71
|_. Option |_. Argument |_. Description |
72
| --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. |
73
| --asio-preferred-flavor | desired flavor of the ASIO library (standalone or boost) | Tells disorder which version of the ASIO library to use. |
74
75 46 Tony Ciavarella
h4. Boost
76 1 Tony Ciavarella
77 49 Tony Ciavarella
|_. Option |_. Argument |_. Description |
78 80 Tony Ciavarella
| --exclude-boost | none | Tells disorder to not use Boost. |
79 46 Tony Ciavarella
| --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. |
80 48 Tony Ciavarella
| --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. |
81 46 Tony Ciavarella
| --boost-mt | none | Links disorder against the multi-threaded versions of the Boost libraries. |
82
| --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. |
83
| --boost-toolset | desired toolset (eg. msvc, vc90, or gcc) | Overrides the automatic toolset detection as specified. |
84
85 49 Tony Ciavarella
h4. Eigen
86 46 Tony Ciavarella
87 50 Tony Ciavarella
|_. Option |_. Argument |_. Description |
88 1 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. |
89
90 80 Tony Ciavarella
h4. GeographicLib
91
92
|_. Option |_. Argument |_. Description |
93
| --geographiclib-root | path to the root of the GeographicLib tree (eg. /opt/GeographicLib-1.48) | Tells disorder where to find GeographicLib. |
94
| --geographiclib-static | none | Links disorder against the static GeographicLib instead of the default dynamic one. |
95
96 1 Tony Ciavarella
h4. SEDRIS SRM
97 49 Tony Ciavarella
98 46 Tony Ciavarella
|_. Option |_. Argument |_. Description |
99 80 Tony Ciavarella
| --sedris-srm-root | path to the root of the SEDRIS SRM tree (eg. /opt/srm) | Tells disorder where to find the SEDRIS SRM. |
100 46 Tony Ciavarella
| --sedris-srm-static | none | Links disorder against the static SEDRIS SRM library instead of the default dynamic one. |
101
| --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. |
102
103 69 Tony Ciavarella
h4. Google Test/Mock
104
105
|_. Option |_. Argument |_. Description |
106
| --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. |
107
| --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. |
108
109 64 Tony Ciavarella
h4. GLUT
110
111
|_. Option |_. Argument |_. Description |
112
| --glut-root | path to the root of the GLUT tree (eg. /opt/freeglut) | Tells disorder where to find GLUT. |
113
| --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. |
114 69 Tony Ciavarella
115
h4. 0mq
116
117
|_. Option |_. Argument |_. Description |
118
| --zmq-root | path to the 0MQ root (eg. /opt/zeromq-4.0.4) | Tells disorder where to find 0MQ. |
119 64 Tony Ciavarella
120 15 Tony Ciavarella
h3. Linux
121 13 Tony Ciavarella
122
From inside the root of the Disorder tree do this in your favorite terminal emulator:
123 68 Tony Ciavarella
<pre>./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here> --eigen-root=/opt/eigen</pre>
124
For example, if your SEDRIS SRM is in /opt/sedris/srm and your Eigen is in /opt/eigen:
125
<pre>./waf configure --sedris-srm-root=/opt/sedris/srm --eigen-root=/opt/eigen</pre>
126 1 Tony Ciavarella
127
That command will take several seconds and print a bunch of hopefully green stuff.  The output should end up looking something like this:
128
<pre>
129 76 Tony Ciavarella
Setting top to                           : /usr/local/src/disorder 
130
Setting out to                           : /usr/local/src/disorder/bin 
131 74 Tony Ciavarella
Checking for 'g++' (C++ compiler)        : /usr/bin/g++ 
132
Checking for program 'doxygen'           : /usr/bin/doxygen 
133
Checking for program 'tar'               : /bin/tar 
134
Checking boost includes                  : 1.62.0 
135
Checking boost libs                      : ok 
136
Checking for boost linkage               : ok 
137
Checking for header boost/asio.hpp       : yes 
138
Checking for header boost/config.hpp     : yes 
139
Checking for header boost/detail/endian.hpp : yes 
140
Checking for header boost/filesystem/operations.hpp : yes 
141
Checking for header boost/preprocessor.hpp          : yes 
142
Checking for header boost/optional.hpp              : yes 
143
Checking for C++11 compiler support                 : yes 
144
Checking for program 'pkg-config'                   : /usr/bin/pkg-config 
145
Checking for 'eigen3'                               : yes 
146
Checking for header Eigen/Dense                     : yes 
147
Checking for SEDRIS SRM                             : /opt/srm 
148
Checking for SEDRIS SRM include directory           : /opt/srm/src/include 
149
Checking for SEDRIS SRM library directory           : /opt/srm/lib/linux-4.9.0-2-amd64-i386-gnu-/OPT 
150
SEDRIS SRM library                                  : /opt/srm/lib/linux-4.9.0-2-amd64-i386-gnu-/OPT/libsrm.a 
151
SEDRIS SRM library mode                             : static 
152
Checking for header srf_all.h                       : yes 
153
Checking for library pthread                        : yes 
154
Checking for gtest source directory                 : /usr/src/googletest/googletest 
155
Checking for gtest-all.cc                           : /usr/src/googletest/googletest/src/gtest-all.cc 
156
Checking for gtest include directory                : /usr/src/googletest/googletest/include 
157
Checking for header gtest/gtest.h                   : yes 
158
Checking for gmock source directory                 : /usr/src/googletest/googlemock 
159
Checking for gmock-all.cc                           : /usr/src/googletest/googlemock/src/gmock-all.cc 
160
Checking for gmock_main.cc                          : /usr/src/googletest/googlemock/src/gmock_main.cc 
161
Checking for gmock include directory                : /usr/src/googletest/googlemock/include 
162
Checking for header gmock/gmock.h                   : yes 
163
Checking for library GL                             : yes 
164
Checking for library glut                           : yes 
165
Checking GLUT sanity                                : yes 
166
Checking for 0MQ                                    : yes 
167
Checking 0MQ sanity                                 : yes 
168
Checking for sane chrono duration modulo            : yes 
169
Checking for defaulted move functions               : yes 
170
Checking for array initializer lists                : yes 
171
Checking for sane std::chrono                       : yes 
172
'configure' finished successfully (6.832s)
173 13 Tony Ciavarella
</pre>
174
175 18 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.
176 13 Tony Ciavarella
177 19 Tony Ciavarella
h4. Clang++
178 16 Tony Ciavarella
179 32 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:
180 16 Tony Ciavarella
<pre>CXX=<put the path to clang++ here> ./waf configure --sedris-srm-root=<put the path to the SEDRIS SRM root here></pre>
181
182 19 Tony Ciavarella
For example:
183 16 Tony Ciavarella
<pre>CXX=/usr/bin/clang++ ./waf configure --sedris-srm-root=/opt/sedris/srm</pre>
184
185 13 Tony Ciavarella
h3. Windows
186
187
On windows, your $PATH environment variable needs to include the path to the Python interpreter.
188
189 30 Tony Ciavarella
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.
190 1 Tony Ciavarella
191 30 Tony Ciavarella
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.
192
193
Once you are finished editing configure.bat, it's time to execute it.  From the command line:
194
<pre>configure.bat</pre>
195
196
If everything is successful, you should get something that looks like this:
197
<pre>
198
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
199
Setting top to                           : C:\oss\disorder
200
Setting out to                           : C:\oss\disorder\bin
201
Checking for 'msvc' (c++ compiler)       : c:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\BIN\amd64\CL.exe
202
Checking for program doxygen             : not found
203
Checking for Eigen library               : c:\oss\eigen-3.0.4
204
Checking for header Eigen/Dense          : yes
205
Checking for SEDRIS SRM                  : c:\oss\sedris\srm
206
Checking for SEDRIS SRM include directory : c:\oss\sedris\srm\src\include
207
Checking for SEDRIS SRM library directory : c:\oss\sedris\srm\lib\[Debug/Release]
208
Checking for header srf_all.h             : yes
209
Configuring boost libraries               : debug variant
210
Checking boost ABI tag                    : gd
211
Checking boost includes                   : 1_48
212
Checking boost libs                       : ok
213
Checking for boost linkage                : ok
214
Checking for header boost/asio.hpp        : yes
215
Checking for header boost/bind.hpp        : yes
216
Checking for header boost/date_time.hpp   : yes
217
Checking for header boost/detail/endian.hpp : yes
218
Checking for header boost/format.hpp        : yes
219
Checking for header boost/function.hpp      : yes
220
Checking for header boost/functional/factory.hpp : yes
221
Checking for header boost/ptr_container/ptr_vector.hpp : yes
222
Checking for header boost/scoped_ptr.hpp               : yes
223
Checking for header boost/static_assert.hpp            : yes
224
Checking for header boost/thread.hpp                   : yes
225
Configuring boost libraries                            : optimized variant
226
Checking boost ABI tag                                 :
227
Checking boost includes                                : 1_48
228
Checking boost libs                                    : ok
229
Checking for boost linkage                             : ok
230
Checking for header boost/asio.hpp                     : yes
231
Checking for header boost/bind.hpp                     : yes
232
Checking for header boost/date_time.hpp                : yes
233
Checking for header boost/detail/endian.hpp            : yes
234
Checking for header boost/format.hpp                   : yes
235
Checking for header boost/function.hpp                 : yes
236
Checking for header boost/functional/factory.hpp       : yes
237
Checking for header boost/ptr_container/ptr_vector.hpp : yes
238
Checking for header boost/scoped_ptr.hpp               : yes
239
Checking for header boost/static_assert.hpp            : yes
240
Checking for header boost/thread.hpp                   : yes
241
'configure' finished successfully (31.262s)
242
</pre>
243
244
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.
245 10 Tony Ciavarella
246 1 Tony Ciavarella
h2. Compiling
247
248 20 Tony Ciavarella
The basic strategy for building Disorder is to invoke the waf build system with the desired build variant.
249 1 Tony Ciavarella
250 20 Tony Ciavarella
Disorder has two build variants:
251 23 Tony Ciavarella
* debug: produces a library that contains debugging symbols and disables most compiler optimizations
252
* optimized: produces a library stripped of debugging symbols and enables compiler optimizations for performance
253 1 Tony Ciavarella
254 23 Tony Ciavarella
It might be reasonable to use the @debug@ variant in a development environment and the @optimized@ variant in a production environment.
255 1 Tony Ciavarella
256 23 Tony Ciavarella
The @debug@ variant is produced by the @build_debug@ build target and the @optimized@ variant is produced by the @build_optimized@ build target.
257
258 26 Tony Ciavarella
The results of the build are put in the @bin@ subdirectory under the name of the variant.  
259 23 Tony Ciavarella
260 26 Tony Ciavarella
Both variants can coexist peacefully in the tree at the same time.
261 23 Tony Ciavarella
262 20 Tony Ciavarella
h3. Linux
263 1 Tony Ciavarella
264 23 Tony Ciavarella
On Linux, to build the Disorder @debug@ variant:
265 20 Tony Ciavarella
<pre>./waf build_debug</pre>
266
267
h3. Windows
268
269 23 Tony Ciavarella
On Windows, the waf script is invoked indirectly.  To build the @optimized@ variant:
270
<pre>python.exe waf build_optimized</pre>
271 12 Tony Ciavarella
272 43 Tony Ciavarella
h2. Ensuring Build Correctness
273
274 44 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.
275 43 Tony Ciavarella
276 67 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 waf to run_unit_test_<variant> like this for the @optimized@ variant:
277
<pre>./waf run_unit_test_optimized</pre>
278 43 Tony Ciavarella
279 1 Tony Ciavarella
That should result in something like this:
280
<pre>
281 67 Tony Ciavarella
...
282
[----------] Global test environment tear-down
283 73 Tony Ciavarella
[==========] 772 tests from 75 test cases ran. (2071 ms total)
284
[  PASSED  ] 772 tests.
285
286 67 Tony Ciavarella
*PASS*: All tests passed!  This silly thing actually works properly.  Hooray!
287 73 Tony Ciavarella
Waf: Leaving directory `/usr/local/src/disorder/bin/debug'
288
'run_unit_test_debug' finished successfully (2.821s)
289 43 Tony Ciavarella
</pre>
290
291
If you see
292
<pre>Something failed!  That's not good.  This build cannot be trusted until the damn thing is fixed.</pre>
293
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.
294
295 1 Tony Ciavarella
h2. Building Against the Disorder Library
296 28 Tony Ciavarella
297
h3. Compiling
298
299
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.
300
301
h3. Linking
302
303 29 Tony Ciavarella
Just link your program against Disorder's static library that can be found in the @bin/<build variant>@ directory.