From 327ef30dfd1b8ab1c2c5c0e248feacdd04371d23 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 30 Jul 2018 19:46:55 +0200 Subject: [PATCH] doc: 'installation' converted to RST --- docs/source/installation.rst | 440 +++++++++++++++++++++++++++++++++++ 1 file changed, 440 insertions(+) create mode 100644 docs/source/installation.rst diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000000..60af9b9359 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,440 @@ +.. Copyright 2005-2018 + +Installing SimGrid +================== + + +SimGrid should work out of the box on Linux, Mac OSX, FreeBSD, and Windows (under windows, only the Java interfaces are +available at the moment). + +Pre-compiled Packages +--------------------- + +Binaries for Linux +^^^^^^^^^^^^^^^^^^ + +On Debian or Ubuntu, simply type: + +.. code-block:: shell + + apt install simgrid + +If you build pre-compiled packages for other distributions, drop us an +email. + +Stable Java Package +^^^^^^^^^^^^^^^^^^^ + +The jar file can be retrieved from the `Release page +`_. This file is +self-contained, including the native components for Linux, Mac OSX and +Windows. Copy it to your project's classpath and you're set. + +Nightly built Java Package +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For non-Windows systems (Linux, Mac or FreeBSD), head to `Jenkins `_. +In the build history, pick the last green (or at least yellow) build that is not blinking (i.e., not currently under +build). In the list, pick a system that is close to yours, and click on the ball in the Debug row. The build artefact +will appear on the top of the resulting page. + +For Windows, head to `AppVeyor `_. +Click on the artefact link on the right, and grab your file. If the latest build failed, there will be no artefact. Then +you will need to first click on "History" on the top and search for the last successful build. + +Binary Java Troubleshooting +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here are some error messages that you may get when trying to use the +binary Java package. + +Your architecture is not supported by this jarfile + If your system is not supported, you should compile your + own jarfile :ref:`by compiling SimGrid ` from the source. +Library not found: boost-context + You should obviously install the ``boost-context`` library on your + machine, for example with ``apt``. + +.. _install_src: + +Installing from the Source +-------------------------- + +Getting the Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^ + +C++ compiler (either g++, clang or icc). + We use the C++11 standard, and older compilers tend to fail on + us. It seems that g++ 5.0 or higher is required nowadays (because of + boost). SimGrid compiles well with `clang` or `icc` too. +Python 3. + SimGrid should build without Python, that is only needed by our regresion test suite. +cmake (v2.8.8). + ``ccmake`` provides a nicer graphical interface compared to ``cmake``. + Press ``t`` in ``ccmake`` if you need to see absolutely all + configuration options (e.g., if your python installation is not standard). +boost (at least v1.48, v1.59 recommended) + - On Debian / Ubuntu: ``apt install libboost-dev libboost-context-dev`` + - On Max OS X with homebrew: ``brew install boost`` +Java (optional): + - Debian / Ubuntu: ``apt install default-jdk libgcj18-dev`` (or + any version of libgcj) + - Mac OS X or Windows: Grab a `full JDK `_ +Lua (optional -- must be v5.3) + - SimGrid won't work with any other version of Lua. + - Debian / Ubuntu: ``apt install liblua5.3-dev lua5.3`` + - Windows: ``choco install lua53`` + - From the source + - You need to patch the sources to build dynamic libraries. First `download lua 5.3 `_ + - Open the archive: ``tar xvfz lua-5.3.*.tar.gz`` + - Enter the directory: ``cd lua-5.3*`` + - Patch the sources: ``patch -p1 < /path/to/simgrid/...../tools/lualib.patch`` + - Build and install lua: ``make linux && sudo make install`` + +For platform-specific details, please see below. + +Getting the Sources +^^^^^^^^^^^^^^^^^^^ + +Grab the last **stable release** from `FramaGit +`_, and compile it as follows: + +.. code-block:: shell + + tar xf SimGrid-3-XX.tar.gz + cd SimGrid-* + cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . + make + make install + +If you want to stay on the **bleeding edge**, get the current git version, +and recompile it as with stable archives. You may need some extra +dependencies. + +.. code-block:: shell + + git clone git@framagit.org:simgrid/simgrid.git + cd simgrid + cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . + make + make install + +Build Configuration +^^^^^^^^^^^^^^^^^^^ + +This section is about **compile-time options**, that are very +different from @ref options "run-time options". Compile-time options +fall into two categories. *SimGrid-specific options* define which part +of the framework to compile while *Generic options* are provided by +cmake itself. + +Generic build-time options +"""""""""""""""""""""""""" + +These options specify for example the path to various system elements +(Python path, compiler to use, etc). In most case, cmake automatically +discovers the right value for these ones, but you can set them +manually on need. Notable such variables include ``CC`` and ``CXX``, +defining respectively the paths to the C and C++ compilers, ``CFLAGS`` +and ``CXXFLAGS`` respectively specifying extra options to pass to the C +and C++ compilers, or ``PYTHON_EXECUTABLE`` specifying the path to the +python executable. + +The best way to discover the exact name of the option that you need to +change is to press ``t`` in the ``ccmake`` graphical interface, as all +options are shown (and documented) in the advanced mode. + +Once you know their name, there is several ways to change the value of +build-time options. You can naturally use the ccmake graphical +interface for that, or you can use environment variables, or you can +prefer the ``-D`` flag of ``cmake``. + +For example, you can change the compilers with environment variables +by issuing these commands before launching cmake: + +.. code-block:: shell + + export CC=gcc-5.1 + export CXX=g++-5.1 + +The same can be done by passing ``-D`` parameters to cmake, as follows. +Note that the ending dot is mandatory (see :ref:`install_cmake_outsrc`). + +.. code-block:: shell + + cmake -DCC=clang -DCXX=clang++ . + +SimGrid compilation options +""""""""""""""""""""""""""" + +Here is the list of all SimGrid-specific build-time options (the +default choice is in uppercase). + +CMAKE_INSTALL_PREFIX (path) + Where to install SimGrid (/opt/simgrid, /usr/local, or elsewhere). + +enable_compile_optimizations (ON/off) + Request the compiler to produce efficient code. You probably want to + activate this option, unless you plan modify SimGrid itself: + efficient code takes more time to compile, and appears mangled to debuggers. + +enable_compile_warnings (on/OFF) + Request the compiler to issue error messages whenever the source + code is not perfectly clean. If you are a SimGrid developer, you + have to activate this option to enforce the code quality. As a + regular user, this option is of little use. + +enable_debug (ON/off) + Disabling this option toto discards all log messages of gravity + debug or below at compile time (see @ref XBT_log). The resulting + code is faster than if you discarding these messages at + runtime. However, it obviously becomes impossible to get any debug + info from SimGrid if something goes wrong. + +enable_documentation (ON/off) + Generates the documentation pages. + +enable_java (on/OFF) + Generates the java bindings of SimGrid. + +enable_jedule (on/OFF) + Produces execution traces from SimDag simulations, that can then be visualized with the + Jedule external tool. + +enable_lua (on/OFF) + Generate the lua bindings to the SimGrid internals (requires lua-5.3). + +enable_lib_in_jar (ON/off) + Embeds the native java bindings into the produced jar file. + +enable_lto (ON/off) + Enables the *Link Time Optimization* in the C++ compiler. + This feature really speeds up the produced code, but it is fragile + with older gcc versions. + +enable_maintainer_mode (on/OFF) + (dev only) Regenerates the XML parsers when the dtd is modified (requires flex and flexml). + +enable_mallocators (ON/off) + Activates our internal memory caching mechanism. This produces faster + code, but it may fool the debuggers. + +enable_model-checking (on/OFF) + Activates the formal verification mode. This will **hinder + simulation speed** even when the model-checker is not activated at + run time. + +enable_ns3 (on/OFF) + Activates the ns-3 bindings. See section @ref pls_ns3. + +enable_smpi (ON/off) + Allows to run MPI code on top of SimGrid. + +enable_smpi_ISP_testsuite (on/OFF) + Adds many extra tests for the model-checker module. + +enable_smpi_MPICH3_testsuite (on/OFF) + Adds many extra tests for the MPI module. + +Reset the build configuration +""""""""""""""""""""""""""""" + +To empty the cmake cache (either when you add a new library or when +things go seriously wrong), simply delete your ``CMakeCache.txt``. You +may also want to directly edit this file in some circumstances. + +.. _install_cmake_outsrc: + +Out of Tree Compilation +^^^^^^^^^^^^^^^^^^^^^^^ + +By default, the files produced during the compilation are placed in +the source directory. It is however often better to put them all in a +separate directory: cleaning the tree becomes as easy as removing this +directory, and you can have several such directories to test several +parameter sets or architectures. + +For that, go to the directory where the files should be produced, and +invoke cmake (or ccmake) with the full path to the SimGrid source as +last argument. + +.. code-block:: shell + + mkdir build + cd build + cmake [options] .. + make + +Existing Compilation Targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In most cases, compiling and installing SimGrid is enough: + +.. code-block:: shell + + make + make install # try "sudo make install" if you don't have the permission to write + +In addition, several compilation targets are provided in SimGrid. If +your system is well configured, the full list of targets is available +for completion when using the ``Tab`` key. Note that some of the +existing targets are not really for public consumption so don't worry +if some stuff doesn't work for you. + +make simgrid + Build only the SimGrid library and not any example +make s4u-app-pingpong + Build only this example (works for any example) +make clean + Clean the results of a previous compilation +make install + Install the project (doc/ bin/ lib/ include/) +make uninstall + Uninstall the project (doc/ bin/ lib/ include/) +make dist + Build a distribution archive (tar.gz) +make distcheck + Check the dist (make + make dist + tests on the distribution) +make documentation + Create SimGrid documentation + +If you want to see what is really happening, try adding ``VERBOSE=1`` to +your compilation requests: + +.. code-block:: shell + + make VERBOSE=1 + +.. _install_src_test: + +Testing your build +^^^^^^^^^^^^^^^^^^ + +Once everything is built, you may want to test the result. SimGrid +comes with an extensive set of regression tests (as described in the +@ref inside_tests "insider manual"). The tests are run with ``ctest``, +that comes with CMake. We run them every commit and the results are +on `our Jenkins `_. + +.. code-block:: shell + + ctest # Launch all tests + ctest -R s4u # Launch only the tests which name match the string "s4u" + ctest -j4 # Launch all tests in parallel, at most 4 concurrent jobs + ctest --verbose # Display all details on what's going on + ctest --output-on-failure # Only get verbose for the tests that fail + + ctest -R s4u -j4 --output-on-failure # You changed S4U and want to check that you didn't break anything, huh? + # That's fine, I do so all the time myself. + +.. _install_cmake_mac: + +Mac OS X Specifics +^^^^^^^^^^^^^^^^^^ + +SimGrid compiles like a charm with clang (version 3.0 or higher) on Mac OS X: + +.. code-block:: shell + + cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ . + make + + +Troubleshooting your Mac OS X build. + +CMake Error: Parse error in cache file build_dir/CMakeCache.txt. Offending entry: /SDKs/MacOSX10.8.sdk + This was reported with the XCode version of clang 4.1. The work + around is to edit the ``CMakeCache.txt`` file directly, to change + the following entry: + + ``CMAKE_OSX_SYSROOT:PATH=/Applications/XCode.app/Contents/Developer/Platforms/MacOSX.platform/Developer`` + + You can safely ignore the warning about "-pthread" not being used, if it appears. + +/usr/include does not seem to exist + This directory does not exist by default on modern Mac OSX versions, + and you may need to create it with ``xcode-select -install`` + +.. _install_cmake_windows: + +Windows Specifics +^^^^^^^^^^^^^^^^^ + +The best solution to get SimGrid working on windows is to install the +Ubuntu subsystem of Windows 10. All of SimGrid (but the model-checker) +works in this setting. + +Native builds not very well supported. Have a look to our `appveypor +configuration file +`_ to +see how we manage to use mingw-64 to build the DLL that the Java file +needs. + +The drawback of MinGW-64 is that the produced DLL are not compatible +with MS Visual C. `clang-cl `_ +sounds promising to fix this. If you get something working or if you +have any other improvement, please @ref community_contact "tell us". + +Java Specifics +^^^^^^^^^^^^^^ + +Once you have the `full JDK `_ installed, +things should be as simple as: + +.. code-block:: shell + + cmake -Denable_java=ON . + make simgrid-java_jar # Only build the jarfile + +After the compilation, the file ```simgrid.jar``` is produced in the +root directory. + +**Troubleshooting Java Builds** + +Sometimes, the build system fails to find the JNI headers. First locate them as follows: + +.. code-block:: shell + + $ locate jni.h + /usr/lib/jvm/java-8-openjdk-amd64/include/jni.h + /usr/lib/jvm/java-9-openjdk-amd64/include/jni.h + /usr/lib/jvm/java-10-openjdk-amd64/include/jni.h + + +Then, set the JAVA_INCLUDE_PATH environment variable to the right +path, and relaunch cmake. If you have several version of jni installed +(as above), pick the one corresponding to the report of +``javac -version`` + +.. code-block:: shell + + export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-8-openjdk-amd64/include/ + cmake -Denable_java=ON . + make + +Note that the filename ```jni.h``` was removed from the path. + +Linux Multi-Arch Specifics +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On a multiarch x86_64 Linux, it should be possible to compile a 32 bit +version of SimGrid with something like: + +.. code-block:: shell + + CFLAGS=-m32 \ + CXXFLAGS=-m32 \ + PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu/pkgconfig/ \ + cmake . \ + -DCMAKE_SYSTEM_PROCESSOR=i386 \ + -DCMAKE_Fortran_COMPILER=/some/path/to/i686-linux-gnu-gfortran \ + -DGFORTRAN_EXE=/some/path/to/i686-linux-gnu-gfortran \ + -DCMAKE_Fortran_FLAGS=-m32 + +If needed, implement ``i686-linux-gnu-gfortran`` as a script: + +.. code-block:: shell + + #!/usr/bin/env sh + exec gfortran -m32 "$@" + -- 2.20.1