Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
convert options to sphinx
[simgrid.git] / docs / source / intro_install.rst
1 .. Copyright 2005-2018
2
3 .. _install:
4
5 Installing SimGrid
6 ==================
7
8
9 SimGrid should work out of the box on Linux, Mac OSX, FreeBSD, and
10 Windows (under Windows, you need to install the Windows Subsystem
11 Linux to get more than the Java bindings).
12
13 Pre-compiled Packages
14 ---------------------
15
16 Binaries for Linux
17 ^^^^^^^^^^^^^^^^^^
18
19 On Debian or Ubuntu, simply type:
20
21 .. code-block:: shell
22
23    apt install simgrid
24
25 If you build pre-compiled packages for other distributions, drop us an
26 email.
27
28 Stable Java Package
29 ^^^^^^^^^^^^^^^^^^^
30
31 The jar file can be retrieved from the `Release page
32 <https://framagit.org/simgrid/simgrid/tags>`_. This file is
33 self-contained, including the native components for Linux, Mac OS X and
34 Windows. Copy it to your project's classpath and you're set.
35
36 Nightly built Java Package
37 ^^^^^^^^^^^^^^^^^^^^^^^^^^
38
39 For non-Windows systems (Linux, Mac OS X, or FreeBSD), head to `Jenkins <https://ci.inria.fr/simgrid/job/SimGrid>`_.
40 In the build history, pick the last green (or at least yellow) build that is not blinking (i.e., not currently under
41 build). In the list, pick a system that is close to yours, and click on the ball in the Debug row. The build artefact
42 will appear at the top of the resulting page.
43
44 For Windows, head to `AppVeyor <https://ci.appveyor.com/project/simgrid/simgrid>`_.
45 Click on the artefact link on the right, and grab your file. If the latest build failed, there will be no artefact. Then
46 you will need to first click on "History" at the top and look for the last successful build.
47
48 Binary Java Troubleshooting
49 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
50
51 Here are some error messages that you may get when trying to use the
52 binary Java package.
53
54 Your architecture is not supported by this jarfile
55    If your system is not supported, you should compile your
56    own jarfile :ref:`by compiling SimGrid <install_src>` from the source.
57 Library not found: boost-context
58    You should obviously install the ``boost-context`` library on your
59    machine, for example with ``apt``.
60
61 .. _install_src:
62
63 Installing from the Source
64 --------------------------
65
66 Getting the Dependencies
67 ^^^^^^^^^^^^^^^^^^^^^^^^
68
69 C++ compiler (either g++, clang, or icc).
70   We use the C++11 standard, and older compilers tend to fail on
71   us. It seems that g++ 5.0 or higher is required nowadays (because of
72   boost).  SimGrid compiles well with `clang` or `icc` too.
73 Python 3.
74   SimGrid should build without Python, that is only needed by our regresion test suite.
75 cmake (v2.8.8).
76   ``ccmake`` provides a nicer graphical interface compared to ``cmake``.
77   Press ``t`` in ``ccmake`` if you need to see absolutely all
78   configuration options (e.g., if your python installation is not standard).
79 boost (at least v1.48, v1.59 recommended)
80   - On Debian / Ubuntu: ``apt install libboost-dev libboost-context-dev``
81   - On Max OS X with homebrew: ``brew install boost``
82 Java (optional):
83   - Debian / Ubuntu: ``apt install default-jdk libgcj18-dev`` (or
84     any version of libgcj)
85   - Mac OS X or Windows: Grab a `full JDK <http://www.oracle.com/technetwork/java/javase/downloads>`_
86 Lua (optional -- must be v5.3)
87   - SimGrid won't work with any other version of Lua.
88   - Debian / Ubuntu: ``apt install liblua5.3-dev lua5.3``
89   - Windows: ``choco install lua53``
90   - From the source
91       - You need to patch the sources to build dynamic libraries. First `download lua 5.3 <http://www.lua.org/download.html>`_
92       - Open the archive: ``tar xvfz lua-5.3.*.tar.gz``
93       - Enter the directory: ``cd lua-5.3*``
94       - Patch the sources: ``patch -p1 < /path/to/simgrid/...../tools/lualib.patch``
95       - Build and install lua: ``make linux && sudo make install``
96
97 For platform-specific details, please see below.
98
99 Getting the Sources
100 ^^^^^^^^^^^^^^^^^^^
101
102 Grab the last **stable release** from `FramaGit
103 <https://framagit.org/simgrid/simgrid/tags>`_, and compile it as follows:
104
105 .. code-block:: shell
106
107    tar xf SimGrid-3-XX.tar.gz
108    cd SimGrid-*
109    cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid .
110    make
111    make install
112
113 If you want to stay on the **bleeding edge**, get the current git version,
114 and recompile it as with stable archives. You may need some extra
115 dependencies.
116
117 .. code-block:: shell
118
119    git clone git@framagit.org:simgrid/simgrid.git
120    cd simgrid
121    cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid .
122    make
123    make install
124
125 .. _install_src_config:
126    
127 Build Configuration
128 ^^^^^^^^^^^^^^^^^^^
129
130 This section is about **compile-time options**, that are very
131 different from :ref:`run-time options <options>`. Compile-time options
132 fall into two categories. **SimGrid-specific options** define which part
133 of the framework to compile while **Generic options** are provided by
134 cmake itself.
135
136 Generic build-time options
137 """"""""""""""""""""""""""
138
139 These options specify for example the path to various system elements
140 (Python path, compiler to use, etc). In most case, CMake automatically
141 discovers the right value for these ones, but you can set them
142 manually on need.  Notable such variables include ``CC`` and ``CXX``,
143 defining respectively the paths to the C and C++ compilers, ``CFLAGS``
144 and ``CXXFLAGS`` respectively specifying extra options to pass to the C
145 and C++ compilers, or ``PYTHON_EXECUTABLE`` specifying the path to the
146 python executable.
147
148 The best way to discover the exact name of the option that you need to
149 change is to press ``t`` in the ``ccmake`` graphical interface, as all
150 options are shown (and documented) in the advanced mode.
151
152 Once you know their name, there are several ways to change the values of
153 build-time options. You can naturally use the ccmake graphical
154 interface for that, or you can use environment variables, or you can
155 prefer the ``-D`` flag of ``cmake``.
156
157 For example, you can change the compilers with environment variables
158 by issuing these commands before launching cmake:
159
160 .. code-block:: shell
161
162    export CC=gcc-5.1
163    export CXX=g++-5.1
164
165 The same can be done by passing ``-D`` parameters to cmake, as follows.
166 Note that the ending dot is mandatory (see :ref:`install_cmake_outsrc`).
167
168 .. code-block:: shell
169
170    cmake -DCC=clang -DCXX=clang++ .
171
172 SimGrid compilation options
173 """""""""""""""""""""""""""
174
175 Here is the list of all SimGrid-specific compile-time options (the
176 default choice is in uppercase).
177
178 CMAKE_INSTALL_PREFIX (path)
179   Where to install SimGrid (/opt/simgrid, /usr/local, or elsewhere).
180
181 enable_compile_optimizations (ON/off)
182   Request the compiler to produce efficient code. You probably want to
183   activate this option, unless you plan modify SimGrid itself:
184   efficient code takes more time to compile, and appears mangled to debuggers.
185
186 enable_compile_warnings (on/OFF)
187   Request the compiler to issue error messages whenever the source
188   code is not perfectly clean. If you are a SimGrid developer, you
189   have to activate this option to enforce the code quality. As a
190   regular user, this option is of little use.
191
192 enable_debug (ON/off)
193   Disabling this option discards all log messages of gravity
194   debug or below at compile time (see @ref XBT_log). The resulting
195   code is faster than if you discard these messages at
196   runtime. However, it obviously becomes impossible to get any debug
197   info from SimGrid if something goes wrong.
198
199 enable_documentation (ON/off)
200   Generates the documentation pages.
201
202 enable_java (on/OFF)
203   Generates the java bindings of SimGrid.
204
205 enable_jedule (on/OFF)
206   Produces execution traces from SimDag simulations, that can then be visualized with the
207   Jedule external tool.
208
209 enable_lua (on/OFF)
210   Generate the lua bindings to the SimGrid internals (requires lua-5.3).
211
212 enable_lib_in_jar (ON/off)
213   Embeds the native java bindings into the produced jar file.
214
215 enable_lto (ON/off)
216   Enables the *Link Time Optimization* in the C++ compiler.
217   This feature really speeds up the produced code, but it is fragile
218   with older gcc versions.
219
220 enable_maintainer_mode (on/OFF)
221   (dev only) Regenerates the XML parsers whenever the DTD is modified (requires flex and flexml).
222
223 enable_mallocators (ON/off)
224   Activates our internal memory caching mechanism. This produces faster
225   code, but it may fool the debuggers.
226
227 enable_model-checking (on/OFF)
228   Activates the formal verification mode. This will **hinder
229   simulation speed** even when the model-checker is not activated at
230   run time.
231
232 enable_ns3 (on/OFF)
233   Activates the ns-3 bindings. See section @ref pls_ns3.
234
235 enable_smpi (ON/off)
236   Allows to run MPI code on top of SimGrid.
237
238 enable_smpi_ISP_testsuite (on/OFF)
239   Adds many extra tests for the model-checker module.
240
241 enable_smpi_MPICH3_testsuite (on/OFF)
242   Adds many extra tests for the MPI module.
243
244 Reset the build configuration
245 """""""""""""""""""""""""""""
246
247 To empty the CMake cache (either when you add a new library or when
248 things go seriously wrong), simply delete your ``CMakeCache.txt``. You
249 may also want to directly edit this file in some circumstances.
250
251 .. _install_cmake_outsrc:
252
253 Out of Tree Compilation
254 ^^^^^^^^^^^^^^^^^^^^^^^
255
256 By default, the files produced during the compilation are placed in
257 the source directory. It is however often better to put them all in a
258 separate directory: cleaning the tree becomes as easy as removing this
259 directory, and you can have several such directories to test several
260 parameter sets or architectures.
261
262 For that, go to the directory where the files should be produced, and
263 invoke cmake (or ccmake) with the full path to the SimGrid source as
264 last argument.
265
266 .. code-block:: shell
267
268   mkdir build
269   cd build
270   cmake [options] ..
271   make
272
273 Existing Compilation Targets
274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275
276 In most cases, compiling and installing SimGrid is enough:
277
278 .. code-block:: shell
279
280   make
281   make install # try "sudo make install" if you don't have the permission to write
282
283 In addition, several compilation targets are provided in SimGrid. If
284 your system is well configured, the full list of targets is available
285 for completion when using the ``Tab`` key. Note that some of the
286 existing targets are not really for public consumption so don't worry
287 if some do not work for you.
288
289 - **make simgrid**: Build only the SimGrid library and not any example
290 - **make s4u-app-pingpong**: Build only this example (works for any example)
291 - **make java-all**: Build all Java examples and their dependencies
292 - **make clean**: Clean the results of a previous compilation
293 - **make install**: Install the project (doc/ bin/ lib/ include/)
294 - **make uninstall**: Uninstall the project (doc/ bin/ lib/ include/)
295 - **make dist**: Build a distribution archive (tar.gz)
296 - **make distcheck**: Check the dist (make + make dist + tests on the distribution)
297 - **make documentation**: Create SimGrid documentation
298
299 If you want to see what is really happening, try adding ``VERBOSE=1`` to
300 your compilation requests:
301
302 .. code-block:: shell
303
304   make VERBOSE=1
305
306 .. _install_src_test:
307
308 Testing your build
309 ^^^^^^^^^^^^^^^^^^
310
311 Once everything is built, you may want to test the result. SimGrid
312 comes with an extensive set of regression tests (as described in the
313 @ref inside_tests "insider manual"). The tests are run with ``ctest``,
314 that comes with CMake.  We run them every commit and the results are
315 on `our Jenkins <https://ci.inria.fr/simgrid/>`_.
316
317 .. code-block:: shell
318
319   ctest                     # Launch all tests
320   ctest -R s4u              # Launch only the tests whose names match the string "s4u"
321   ctest -j4                 # Launch all tests in parallel, at most 4 concurrent jobs
322   ctest --verbose           # Display all details on what's going on
323   ctest --output-on-failure # Only get verbose for the tests that fail
324
325   ctest -R s4u -j4 --output-on-failure # You changed S4U and want to check that you didn't break anything, huh?
326                                        # That's fine, I do so all the time myself.
327
328 .. _install_cmake_mac:
329
330 Mac OS X Specifics
331 ^^^^^^^^^^^^^^^^^^
332
333 SimGrid compiles like a charm with clang (version 3.0 or higher) on Mac OS X:
334
335 .. code-block:: shell
336
337   cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ .
338   make
339
340
341 Troubleshooting your Mac OS X build.
342
343 CMake Error: Parse error in cache file build_dir/CMakeCache.txt. Offending entry: /SDKs/MacOSX10.8.sdk
344   This was reported with the XCode version of clang 4.1. The work
345   around is to edit the ``CMakeCache.txt`` file directly, to change
346   the following entry:
347
348   ``CMAKE_OSX_SYSROOT:PATH=/Applications/XCode.app/Contents/Developer/Platforms/MacOSX.platform/Developer``
349
350   You can safely ignore the warning about "-pthread" not being used, if it appears.
351
352 /usr/include does not seem to exist
353   This directory does not exist by default on modern Mac OS X versions,
354   and you may need to create it with ``xcode-select -install``
355
356 .. _install_cmake_windows:
357
358 Windows Specifics
359 ^^^^^^^^^^^^^^^^^
360
361 The best solution to get SimGrid working on windows is to install the
362 Ubuntu subsystem of Windows 10. All of SimGrid (but the model-checker)
363 works in this setting.
364
365 Native builds not very well supported. Have a look to our `appveypor
366 configuration file
367 <https://framagit.org/simgrid/simgrid/blob/master/.appveyor.yml>`_ to
368 see how we manage to use mingw-64 to build the DLL that the Java file
369 needs.
370
371 The drawback of MinGW-64 is that the produced DLL are not compatible
372 with MS Visual C. `clang-cl <http://clang.llvm.org/docs/MSVCCompatibility.html">`_
373 sounds promising to fix this. If you get something working or if you
374 have any other improvement, please @ref community_contact "tell us".
375
376 Java Specifics
377 ^^^^^^^^^^^^^^
378
379 Once you have the `full JDK <http://www.oracle.com/technetwork/java/javase/downloads>`_ installed,
380 things should be as simple as:
381
382 .. code-block:: shell
383
384    cmake -Denable_java=ON .
385    make  simgrid-java_jar # Only build the jarfile
386
387 After the compilation, the file ```simgrid.jar``` is produced in the
388 root directory.
389
390 **Troubleshooting Java Builds**
391
392 Sometimes, the build system fails to find the JNI headers. First locate them as follows:
393
394 .. code-block:: shell
395
396   $ locate jni.h
397   /usr/lib/jvm/java-8-openjdk-amd64/include/jni.h
398   /usr/lib/jvm/java-9-openjdk-amd64/include/jni.h
399   /usr/lib/jvm/java-10-openjdk-amd64/include/jni.h
400
401
402 Then, set the JAVA_INCLUDE_PATH environment variable to the right
403 path, and relaunch cmake. If you have several versions of JNI installed
404 (as above), pick the one corresponding to the report of
405 ``javac -version``
406
407 .. code-block:: shell
408
409   export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-8-openjdk-amd64/include/
410   cmake -Denable_java=ON .
411   make
412
413 Note that the filename ```jni.h``` was removed from the path.
414
415 Linux Multi-Arch Specifics
416 ^^^^^^^^^^^^^^^^^^^^^^^^^^
417
418 On a multiarch x86_64 Linux, it should be possible to compile a 32-bit
419 version of SimGrid with something like:
420
421 .. code-block:: shell
422
423   CFLAGS=-m32 \
424   CXXFLAGS=-m32 \
425   PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig/ \
426   cmake . \
427   -DCMAKE_SYSTEM_PROCESSOR=i386 \
428   -DCMAKE_Fortran_COMPILER=/some/path/to/i686-linux-gnu-gfortran \
429   -DGFORTRAN_EXE=/some/path/to/i686-linux-gnu-gfortran \
430   -DCMAKE_Fortran_FLAGS=-m32
431
432 If needed, implement ``i686-linux-gnu-gfortran`` as a script:
433
434 .. code-block:: shell
435
436   #!/usr/bin/env sh
437   exec gfortran -m32 "$@"
438