INSTALL

   1 This page summarizes how to compile SimGrid. The full Install
   2 documentation is available in doc/html/install.html or online at
   3
   4               http://simgrid.gforge.inria.fr/
   5
   6 Getting the Dependencies
   7 ------------------------
   8 SimGrid only uses very standard tools:
   9  - C compiler, C++ compiler, make and friends.
  10  - perl (but you may try to go without it)
  11  - cmake (version 2.8.8 or higher). You may want to use ccmake for a graphical interface over cmake.
  12  - boost:
  13    - Max OS X: with fink: fink install boost1.53.nopython, or with homebrew: brew install boost
  14    - Debian / Ubuntu: apt-get install libboost-dev libboost-context-dev
  15  - Java (if you want to build the Java bindings):
  16    - Mac OS X or Windows: Grab a full JDK
  17    - Debian / Ubuntu: apt-get install default-jdk
  18
  19 Build Configuration
  20 -------------------
  21 Note that compile-time options are very different from run-time options.
  22
  23 The default configuration should be fine for most usages, but if you
  24 need to change something, there are several ways to do so. First, you
  25 can use environment variables. For example, you can change the
  26 compilers used by issuing these commands before launching cmake:
  27
  28   export CC=gcc-4.7
  29   export CXX=g++-4.7
  30
  31 Note that other variables are available, such as CFLAGS and CXXFLAGS
  32 to add options respectively for the C and C++ compilers.
  33
  34 Another way to do so is to use the -D argument of cmake as follows. Note that the ending dot is mandatory (see Out of Tree Compilation).
  35
  36   cmake -DCC=clang -DCXX=clang++ .
  37
  38 Finally, you can use the ccmake graphical interface to change these settings.
  39
  40   ccmake .
  41
  42 Existing compilation options
  43 ----------------------------
  44
  45  CMAKE_INSTALL_PREFIX (path)
  46    Where to install SimGrid (/opt/simgrid, /usr/local, or elsewhere).
  47  enable_compile_optimizations (ON/OFF)
  48    Request the compiler to produce efficient code. You want to
  49    activate it, unless you plan to debug SimGrid itself. Indeed,
  50    efficient code may be appear mangled to debuggers.
  51  enable_compile_warnings (ON/OFF)
  52    Request the compiler to issue error messages whenever the source
  53    code is not perfectly clean. If you are a SimGrid developer, you
  54    have to activate this option to enforce the code quality. As a
  55    regular user, this option will bring you nothing.
  56  enable_debug (ON/OFF)
  57    Disable this option toto discard all log messages of gravity debug
  58    or below at compile time. The resulting code is faster than if you
  59    discarding these messages at runtime. However, it obviously becomes
  60    impossible to get any debug info from SimGrid if something goes
  61    wrong.
  62  enable_documentation (ON/OFF)
  63    Generate the documentation pages.
  64  enable_java (ON/OFF)
  65    To enjoy the java bindings of SimGrid.
  66  enable_jedule (ON/OFF)
  67    To get SimDag producing execution traces that can then be
  68    visualized with the Jedule external tool.
  69  enable_lua (ON/OFF)
  70    To enjoy the lua bindings to the SimGrid internals.
  71  enable_lib_in_jar (ON/OFF)
  72    Bundle the native java bindings in the jar file.
  73  enable_lto (ON/OFF)
  74    Enable the Link Time Optimization of the C compiler. This feature
  75    really speeds up the produced code, but it is fragile with some
  76    versions of GCC.
  77  enable_maintainer_mode (ON/OFF)
  78    Only needed if you plan to modify very specific parts of SimGrid
  79    (e.g., the XML parsers and other related elements). Moreover, this
  80    adds an extra dependency on flex and flexml.
  81  enable_mallocators (ON/OFF)
  82    Disabled this when tracking memory issues within SimGrid, or our
  83    internal memory caching mechanism will fool the debuggers.
  84  enable_model-checking (ON/OFF)
  85    This execution gear is very usable now, but enabling this option at
  86    compile time will hinder simulation speed even when the
  87    model-checker is not activated at run time.
  88  enable_ns3 (ON/OFF)
  89    Allow to use ns-3 as a SimGrid network model.
  90  enable_smpi (ON/OFF)
  91    Allow to run MPI code on top of SimGrid.
  92  enable_smpi_ISP_testsuite (ON/OFF)
  93    Add many extra tests for the model-checker module.
  94  enable_smpi_MPICH3_testsuite (ON/OFF)
  95    Add many extra tests for the MPI module.
  96
  97 Reset the build configuration
  98 -----------------------------
  99
 100 To empty the cmake cache (either when you add a new library or when
 101 things go seriously wrong), simply delete your CMakeCache.txt. You may
 102 also want to directly edit this file in some circumstances.
 103
 104 Out of Tree Compilation
 105 -----------------------
 106
 107 By default, the files produced during the compilation are placed in
 108 the source directory. It is however often better to put them all in a
 109 separate directory: cleaning the tree becomes as easy as removing this
 110 directory, and you can have several such directories to test several
 111 parameter sets or architectures. For that, go to the directory where
 112 the files should be produced, and invoke cmake (or ccmake) with the
 113 full path to the SimGrid source as last argument.
 114
 115   mkdir build
 116   cd build
 117   cmake [options] ..
 118   make
 119
 120 Mac OS X Builds
 121 ---------------
 122 SimGrid compiles like a charm with clang (version 3.0 or higher) on Mac OS X:
 123
 124   cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ .
 125   make
 126
 127 With the XCode version of clang 4.1, you may get the following error message:
 128 CMake Error: Parse error in cache file build_dir/CMakeCache.txt. Offending entry: /SDKs/MacOSX10.8.sdk
 129
 130 In that case, edit the CMakeCache.txt file directly, so that the
 131 CMAKE_OSX_SYSROOT is similar to the following. Don't worry about the
 132 warning that the "-pthread" argument is not used, if it appears.
 133 CMAKE_OSX_SYSROOT:PATH=/Applications/XCode.app/Contents/Developer/Platforms/MacOSX.platform/Developer
 134
 135 In the El Capitan version of Max OS X, Apple decided that users don't
 136 need no /usr/include directory anymore. If you are hit by this pure
 137 madness, just run the following command to restore that classical UNIX
 138 directory: xcode-select -install
 139
 140 Windows Builds
 141 --------------
 142
 143 Building SimGrid on Windows may be something of an adventure: We only
 144 manage to do so ourselves with MinGW-64, ActiveState Perl and msys
 145 git). Have a look at out configuration scripts in appveyor.yml, but
 146 don't expect too much from us: we are really not fluent with Windows.
 147 Actually your help is welcome.
 148
 149 The drawback of MinGW-64 is that the produced DLL are not compatible
 150 with MS Visual C. clang-cl sounds promising to fix this. If you get
 151 something working, please tell us.
 152
 153 Build the Java bindings
 154 -----------------------
 155
 156 Once you have the full JDK installed (on Debian/Ubuntu, grab the
 157 package default-jdk for that), things should be as simple as:
 158
 159     cmake -Denable_java=ON .
 160     make
 161
 162 After the compilation, the file simgrid.jar is produced in the root
 163 directory. If you only want to build the jarfile and its dependencies,
 164 type make simgrid-java_jar. It will save you the time of building
 165 every C examples and other things that you don't need for Java.
 166
 167 Sometimes, the build system fails to find the JNI headers:
 168  Error: jni could not be found.
 169
 170 In this case, you need to first locate them as follows:
 171     $ locate jni.h
 172     /usr/lib/jvm/java-7-openjdk-amd64/include/jni.h
 173     /usr/lib/jvm/java-8-openjdk-amd64/include/jni.h
 174
 175 Then, set the JAVA_INCLUDE_PATH environment variable to the right
 176 path, and relaunch cmake. If you have several version of jni installed
 177 (as above), use the right one (check the java version you use with
 178 javac -version).
 179
 180     export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-8-openjdk-amd64/include/
 181     cmake -Denable_java=ON .
 182     make
 183
 184 Note that the filename jni.h was removed from the path.
 185
 186 32 bits Builds on Multi-arch Linux
 187 ----------------------------------
 188
 189 On a multiarch x86_64 Linux, it should be possible to compile a 32 bit version of SimGrid with something like:
 190 CFLAGS=-m32 \
 191 CXXFLAGS=-m32 \
 192 PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig/ \
 193 cmake . \
 194 -DCMAKE_SYSTEM_PROCESSOR=i386 \
 195 -DCMAKE_Fortran_COMPILER=/some/path/to/i686-linux-gnu-gfortran \
 196 -DGFORTRAN_EXE=/some/path/to/i686-linux-gnu-gfortran \
 197 -DCMAKE_Fortran_FLAGS=-m32
 198 If needed, implement i686-linux-gnu-gfortran as a script:
 199 #!/usr/bin/env sh
 200 exec gfortran -m32 "$@"
 201
 202 Existing Compilation Targets
 203 ----------------------------
 204 In most cases, compiling and installing SimGrid is enough:
 205   make
 206   make install # try "sudo make install" if you don't have the permission to write
 207
 208 In addition, several compilation targets are provided in SimGrid. If
 209 your system is well configured, the full list of targets is available
 210 for completion when using the Tab key. Note that some of the existing
 211 targets are not really for public consumption so don't worry if some
 212 stuff doesn't work for you.
 213
 214 make simgrid                    Build only the SimGrid library and not any example
 215 make app-masterworker           Build only this example (works for any example)
 216 make clean                      Clean the results of a previous compilation
 217 make install                    Install the project (doc/ bin/ lib/ include/)
 218 make uninstall                  Uninstall the project (doc/ bin/ lib/ include/)
 219 make dist                       Build a distribution archive (tgz)
 220 make distcheck                  Check the dist (make + make dist + tests on the distribution)
 221 make documentation              Create SimGrid documentation
 222
 223 If you want to see what is really happening, try adding VERBOSE=1 to your compilation requests:
 224
 225   make VERBOSE=1
 226
 227 Testing your build
 228 ------------------
 229
 230 Once everything is built, you may want to test the result. SimGrid
 231 comes with an extensive set of regression tests (as described in the
 232 insider manual). The tests are run with ctest, that comes with CMake.
 233 We run them every commit and the results are on our Jenkins.
 234
 235 ctest                     # Launch all tests
 236 ctest -R msg              # Launch only the tests which name match the string "msg"
 237 ctest -j4                 # Launch all tests in parallel, at most 4 at the same time
 238 ctest --verbose           # Display all details on what's going on
 239 ctest --output-on-failure # Only get verbose for the tests that fail
 240 ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that you didn't break anything, huh?
 241                                       # That's fine, I do so all the time myself.