1 /*! @page install Installing Simgrid
5 SimGrid should work out of the box on Linux, Mac OSX, FreeBSD, and Windows (under windows, only the Java interfaces are
6 available at the moment).
8 The easiest way to install SimGrid is to go for a @ref install_binary "binary package". Under Debian or Ubuntu, this is
9 very easy as SimGrid is directly integrated to the official repositories. For other Linux variants, you probably want
10 to go for a @ref install_src "source install". Please contact us if you want to contribute the build scripts for your
11 preferred distribution. If you just want to use @ref install_binary_java "Java", simply copy the jar file on your disk
14 @section install_binary Installing a binary package
16 @subsection install_binary_linux Binary packages for linux
18 Most of the developers use a Debian or Ubuntu system, and some of us happen to be Debian Maintainers, so the packages
19 for these systems are well integrated with these systems and very up-to-date. To install them, simply type:
22 apt-get install simgrid
25 @subsection install_binary_java Using the binary jar file
27 The easiest way to install the Java bindings of SimGrid is to grab the jar file from the
28 [download page](https://gforge.inria.fr/frs/?group_id=12) and copy it in your classpath (typically, in the same
29 directory as your source code). If you go for that version, there is no need to install the C library as it is already
30 bundled within the jar file. Actually, only a bunch of architectures are supported this way to keep the jar file size
31 under control and because we don't have access to every exotic architectures ourselves.
33 If the jarfile fails on you, complaining that your architecture is not supported, drop us an email on
34 <mailto:simgrid-devel@lists.gforge.inria.fr>. We may extend the jarfile for you, provided we have access to this
35 particular architecture to build SimGrid on it.
37 If the error message is about the boost-context library, then you should install that library on your machine. This is
38 a known issue in the 3.12 release that will be fixed in the next release.
40 You can retrieve a nightly build of the jar file from our autobuilders.
41 For Windows, head to [AppVeyor](https://ci.appveyor.com/project/mquinson/simgrid).
42 Click on the artefact link on the right, and grab your file. If the latest build failed, there will be no artefact. Then
43 you will need to first click on "History" on the top and search for the last successful build.
44 For non-Windows systems (Linux, Mac or FreeBSD), head to [Jenkins](https://ci.inria.fr/simgrid/job/SimGrid-Multi).
45 In the build history, pick the last green (or at least yellow) build that is not blinking (i.e., not currently under
46 build). In the list, pick a system that is close to yours, and click on the ball in the Debug row. The build artefact
47 will appear on the top of the resulting page.
49 @section install_src Installing from source
51 @subsection install_src_deps Resolving the dependencies
53 Recompiling an official archive is not much more complex. SimGrid only uses very standard tools:
54 - C compiler, C++ compiler, make and friends.
55 - perl (but you may try to go without it)
56 - We use cmake to configure our compilation
57 ([download page](http://www.cmake.org/cmake/resources/software.html)).
58 You need cmake version 2.8.8 or higher. You may want to use ccmake
59 for a graphical interface over cmake.
61 - osX: with [fink](http://www.finkproject.org/): `fink install boost1.53.nopython`,
62 or with homebrew: `brew install boost`
63 - debian/ubuntu: `apt-get install libboost-dev libboost-context-dev`
64 - Java (only needed if you want to use the Java bindings): Grab a
65 [full JDK](http://www.oracle.com/technetwork/java/javase/downloads)
67 For platform specific details, please see @ref install_cmake_mac and @ref install_cmake_windows.
69 @subsection install_src_fetch Getting the sources
71 You can download the *@SimGridRelease.tar.gz* archive from the
72 [download page](https://gforge.inria.fr/frs/?group_id=12).
73 Then, recompiling the archive should be done in a few lines:
75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.sh}
76 tar xf @SimGridRelease.tar.gz
78 cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid .
81 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83 If you want to stay on the bleeding edge, you should get the latest git version, and recompile it as you would do for
84 an official archive. Depending on the files you change in the source tree, some extra tools may be needed.
87 git clone git://scm.gforge.inria.fr/simgrid/simgrid.git simgrid
90 @subsection install_src_config Configuring the build
92 Note that compile-time options are very different from @ref options "run-time options".
94 \subsubsection install_cmake_howto Setting compilation options
96 The default configuration should be fine for most usages, but if you need to change something, there are several ways
97 to do so. First, you can use environment variables. For example, you can change the compilers used by issuing these
98 commands before launching cmake:
105 Note that other variables are available, such as CFLAGS and CXXFLAGS to add options respectively for the C and C++
108 Another way to do so is to use the -D argument of cmake as follows. Note that the terminating dot is mandatory (see @ref
109 install_cmake_outsrc to understand its meaning).
112 cmake -DCC=clang -DCXX=clang++ .
115 Finally, you can use a graphical interface such as ccmake to change these settings. Simply follow the instructions after
116 starting the interface.
122 \subsubsection install_cmake_list SimGrid compilation options
124 In addition to the classical cmake configuration variables, SimGrid accepts several options, as listed below.
126 @li <b>CMAKE_INSTALL_PREFIX</b> (path): Where to install SimGrid (/opt/simgrid, /usr/local, or elsewhere).
128 @li <b>enable_compile_optimizations</b> (ON/OFF) to request the compiler to produce efficient code. You want to
129 activate it, unless you plan to debug SimGrid itself. Indeed, efficient code may be appear mangled to debuggers.
131 @li <b>enable_compile_warnings</b> (ON/OFF) to request the compiler to issue error messages whenever the source code
132 is not perfectly clean. If you are a SimGrid developer, you have to activate this option to enforce the code
133 quality. As a regular user, this option is likely to bring you issues only.
135 @li <b>enable_debug</b> (ON/OFF) allows to discard all log messages of gravity debug or below at compile time, if
136 simulation speed matters. As there is quite a bunch of such log messages in SimGrid internals, this can reveal
137 faster than discarding them at runtime as usual. However, it obviously becomes impossible to get any debug
138 message from SimGrid if something goes wrong.
140 @li <b>enable_documentation</b> (ON/OFF) to generate the documentation pages.
142 @li <b>enable_java</b> (ON/OFF) to enjoy the java bindings of SimGrid.
144 @li <b>enable_jedule</b> (ON/OFF) to get SimDag producing execution traces that can then be visualized with the
145 Jedule external tool.
147 @li <b>enable_lua</b> (ON/OFF) to enjoy the lua bindings of SimGrid. It adds an extra dependency on the lua library
148 and developer header files.
150 @li <b>enable_lib_in_jar</b> (ON/OFF) to XXX
152 @li <b>enable_lto</b> (ON/OFF) to XXX
154 @li <b>enable_maintainer_mode</b> (ON/OFF) is only needed if you plan to modify very specific parts of SimGrid
155 (e.g., the XML parsers and other related elements). Moreover, this adds an extra dependency on flex and flexml.
157 @li <b>enable_mallocators</b> (ON/OFF) has to be disabled when tracking memory issues within SimGrid, or the caching
158 mechanism used internally will fool the debuggers.
160 @li <b>enable_model-checking</b> (ON/OFF) if you actually plan to use the model-checking feature of
161 SimGrid. This execution mode is still under heavy work, but should be rather usable now. Be <b>warned</b> that
162 this option will hinder simulation speed even if you simulate without activating the model-checker. We are
163 working on improving this situation.
165 @li <b>enable_ns3</b> (ON/OFF) if you want to use ns-3. See section @ref pls_simgrid_configuration_ns3.
167 @li <b>enable_smpi</b> (ON/OFF) has to be disabled if you have issues with the module allowing to run MPI code on
168 top of SimGrid. This module is very stable, but if you don't really need it, you can disable it safely.
170 @li <b>enable_smpi_ISP_testsuite</b> (ON/OFF) to XXX
172 @li <b>enable_smpi_MPICH3_testsuite</b> (ON/OFF) to XXX
174 \subsubsection install_cmake_reset Resetting the compilation configuration
176 If you need to empty the cache of values saved by cmake (either because you added a new library or because something
177 seriously went wrong), you can simply delete the file CMakeCache.txt that is created at the root of the source tree.
178 You may also want to directly edit this file in some circumstances.
180 \subsubsection install_cmake_outsrc Compiling into a separate directory
182 By default, the files produced during the compilation are placed in
183 the source directory. As compilation generates a lot of files, it
184 is advised to put them all in a separate directory. It is then
185 easier to cleanup, and this allows to compile several configurations
186 out of the same source tree. For that, simply enter the directory
187 where you want the produced files to land, and invoke cmake (or
188 ccmake) with the full path to the SimGrid source as last argument.
189 This approach is called "out-of-source-tree compilation".
198 \subsubsection install_cmake_mac Building on Mac OS X
200 SimGrid compiles like a charm with clang (version 3.0 or higher) on Mac OS X:
203 cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ .
207 With the XCode version of clang 4.1, you may get the following error message:
209 CMake Error: Parse error in cache file build_dir/CMakeCache.txt. Offending entry: /SDKs/MacOSX10.8.sdk
212 In that case, edit the CMakeCache.txt file directly, so that the
213 CMAKE_OSX_SYSROOT is similar to the following. Don't worry about the
214 warning that the "-pthread" argument is not used, if it appears.
216 CMAKE_OSX_SYSROOT:PATH=/Applications/XCode.app/Contents/Developer/Platforms/MacOSX.platform/Developer
219 In the El Capitan version of Max OS X, Apple decided that users don't
220 need no /usr/include directory anymore. If you are hit by this pure
221 madness, just run the following command to restore that classical
222 UNIX directory: `xcode-select -install`
224 \subsubsection install_cmake_windows Building on Windows
226 Building from the source on Windows, may be something of an adventure.
227 We never managed to compile SimGrid with something else than MinGW-64
228 ourselves. We usually use the
229 <a href="http://www.activestate.com/activeperl/downloads">activestate</a>
230 version of Perl, and the
231 <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">msys</a>
232 version of git on this architecture, but YMMV. You can have a look at
233 the configuration scripts in the appveyor.yml file, but you are
234 basically on your own here. Sorry. We are not fluent with Windows so
235 we cannot really help.
237 The drawback of MinGW-64 is that the produced DLL are not compatible
238 with MS Visual C. If you need it, <a href="http://clang.llvm.org/docs/MSVCCompatibility.html">clang-cl</a>
239 sounds promising. If you manage to get something working, please tell
240 us how you achieved it.
242 \subsection install_src_compil SimGrid main compilation targets
244 In most cases, compiling and installing SimGrid is enough:
248 make install # try "sudo make install" if you don't have the permission to write
251 In addition, several compilation targets are provided in SimGrid. If
252 your system is well configured, the full list of targets is available
253 for completion when using the Tab key. Note that some of the existing
254 targets are not really for public consumption so don't worry if some
255 stuff doesn't work for you.
258 make simgrid Build only the SimGrid library and not any example
259 make masterslave Build only this example (and its dependencies)
260 make clean Clean the results of a previous compilation
261 make install Install the project (doc/ bin/ lib/ include/)
262 make uninstall Uninstall the project (doc/ bin/ lib/ include/)
263 make dist Build a distribution archive (tgz)
264 make distcheck Check the dist (make + make dist + tests on the distribution)
265 make documentation Create SimGrid documentation
268 If you want to see what is really happening, try adding VERBOSE=1 to
269 your compilation requests:
275 @subsection install_src_test Testing SimGrid
277 Once everything is built, you may want to test the result. SimGrid
278 comes with an extensive set of regression tests (see @ref
279 inside_tests "that page of the insider manual" for more
280 details). Running the tests is done using the ctest binary that comes
281 with cmake. These tests are run for every commit and the result is
282 publicly <a href="https://ci.inria.fr/simgrid/">available</a>.
285 ctest # Launch all tests
286 ctest -R msg # Launch only the tests which name match the string "msg"
287 ctest -j4 # Launch all tests in parallel, at most 4 at the same time
288 ctest --verbose # Display all details on what's going on
289 ctest --output-on-failure # Only get verbose for the tests that fail
291 ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that you didn't break anything, huh?
292 # That's fine, I do so all the time myself.
295 \section install_setting_own Setting up your own code
297 Do not build your simulator by modifying the SimGrid examples. Go
298 outside the SimGrid source tree and create your own working directory
299 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
301 Suppose your simulation has the following structure (remember it is
302 just an example to illustrate a possible way to compile everything;
303 feel free to organize it as you want).
305 \li <tt>sched.h</tt>: a description of the core of the
306 scheduler (i.e. which functions are can be used by the
307 agents). For example we could find the following functions
308 (master, forwarder, slave).
309 \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
310 implementing the core of the scheduler. Most of these
311 functions use the MSG functions defined in section \ref
313 \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
314 the MSG initialization (MSG_init()), the platform
315 creation (e.g. with MSG_create_environment()), the
316 deployment phase (e.g. with MSG_function_register() and
317 MSG_launch_application()) and the call to MSG_main()).
319 To compile such a program, we suggest to use the following
320 Makefile. It is a generic Makefile that we have used many times with
321 our students when we teach the C language.
324 # The first rule of a Makefile is the default target. It will be built when make is called with no parameter
325 # Here, we want to build the binary 'masterslave'
328 # This second rule lists the dependencies of the masterslave binary
329 # How this dependencies are linked is described in an implicit rule below
330 masterslave: masterslave.o sched.o
332 # These third give the dependencies of the each source file
333 masterslave.o: masterslave.c sched.h # list every .h that you use
334 sched.o: sched.c sched.h
337 SIMGRID_INSTALL_PATH = /opt/simgrid # Where you installed simgrid
338 CC = gcc # Your compiler
339 WARNING = -Wshadow -Wcast-align -Waggregate-return -Wmissing-prototypes \
340 -Wmissing-declarations -Wstrict-prototypes -Wmissing-prototypes \
341 -Wmissing-declarations -Wmissing-noreturn -Wredundant-decls \
342 -Wnested-externs -Wpointer-arith -Wwrite-strings -finline-functions
344 # CFLAGS = -g -O0 $(WARNINGS) # Use this line to make debugging easier
345 CFLAGS = -g -O2 $(WARNINGS) # Use this line to get better performance
347 # No change should be mandated past that line
348 #############################################
349 # The following are implicit rules, used by default to actually build
350 # the targets for which you listed the dependencies above.
352 # The blanks before the $(CC) must be a Tab char, not spaces
354 $(CC) -L$(SIMGRID_INSTALL_PATH)/lib/ $(CFLAGS) $^ -lsimgrid -o $@
356 $(CC) -I$(SIMGRID_INSTALL_PATH)/include $(CFLAGS) -c -o $@ $<
363 The comments of this file should be enough to understand what's going
364 on. If you are completely new to makefiles, you should install the
365 <tt>make-doc</tt> package and type this command in a terminal:
368 Sometimes, the following error message (or similar) will be produced.
370 masterworker.c:209: undefined reference to `sg_version_check'
371 masterworker.c:209: undefined reference to `MSG_init_nocheck'
372 (and possibly many other undefined references)
375 It means that the system does not manage to find simgrid when it tries
376 to execute your programs. Specify where to search with the
377 <tt>LD_LIBRARY_PATH</tt> variable. Try running the following command
378 before executing your code. If it helps, you should add this line to
379 your ~/.bashrc so that it gets executed each time you log into your
383 export LD_LIBRARY_PATH=/opt/simgrid/lib
386 @subsection install_src_32 Compiling a 32 bit version
388 On a multiarch x86_64 Linux, it should be possible to compile a 32 bit
389 version of SimGrid with something like:
394 PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig/ \
396 -DCMAKE_SYSTEM_PROCESSOR=i386 \
397 -DCMAKE_Fortran_COMPILER=/some/path/to/i686-linux-gnu-gfortran \
398 -DGFORTRAN_EXE=/some/path/to/i686-linux-gnu-gfortran \
399 -DCMAKE_Fortran_FLAGS=-m32
402 where i686-linux-gnu-gfortran can be implemented as:
406 exec gfortran -m32 "$@"