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