X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a39a45af5e19dfb8b8ed2cb084b3a6b518d179e4..5937b88aaa18de687b2de15a97ee3ae0dc480f64:/docs/source/intro_install.rst diff --git a/docs/source/intro_install.rst b/docs/source/intro_install.rst index 640ac759b1..ea1761a860 100644 --- a/docs/source/intro_install.rst +++ b/docs/source/intro_install.rst @@ -1,13 +1,14 @@ -.. Copyright 2005-2018 +.. Copyright 2005-2018 .. _install: 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). + +SimGrid should work out of the box on Linux, Mac OSX, FreeBSD, and +Windows (under Windows, you need to install the Windows Subsystem +Linux to get more than the Java bindings). Pre-compiled Packages --------------------- @@ -18,31 +19,31 @@ 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 +self-contained, including the native components for Linux, Mac OS X 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 non-Windows systems (Linux, Mac OS X, 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 at 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. +you will need to first click on "History" at the top and look for the last successful build. Binary Java Troubleshooting ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -58,14 +59,14 @@ Library not found: boost-context machine, for example with ``apt``. .. _install_src: - + Installing from the Source -------------------------- Getting the Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^ -C++ compiler (either g++, clang or icc). +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. @@ -77,10 +78,10 @@ cmake (v2.8.8). 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`` + - On Max OS X with homebrew: ``brew install boost`` Java (optional): - Debian / Ubuntu: ``apt install default-jdk libgcj18-dev`` (or - any version of libgcj) + 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. @@ -114,27 +115,29 @@ 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 +.. _install_src_config: + 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 +different from :ref:`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 +(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`` @@ -146,7 +149,7 @@ 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 +Once you know their name, there are several ways to change the values 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``. @@ -155,7 +158,7 @@ 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 @@ -169,15 +172,15 @@ Note that the ending dot is mandatory (see :ref:`install_cmake_outsrc`). SimGrid compilation options """"""""""""""""""""""""""" -Here is the list of all SimGrid-specific build-time options (the +Here is the list of all SimGrid-specific compile-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: + 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) @@ -187,9 +190,9 @@ enable_compile_warnings (on/OFF) regular user, this option is of little use. enable_debug (ON/off) - Disabling this option toto discards all log messages of gravity + Disabling this option 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 + code is faster than if you discard these messages at runtime. However, it obviously becomes impossible to get any debug info from SimGrid if something goes wrong. @@ -200,7 +203,7 @@ 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 + Produces execution traces from SimDag simulations, that can then be visualized with the Jedule external tool. enable_lua (on/OFF) @@ -215,11 +218,11 @@ enable_lto (ON/off) with older gcc versions. enable_maintainer_mode (on/OFF) - (dev only) Regenerates the XML parsers when the dtd is modified (requires flex and flexml). + (dev only) Regenerates the XML parsers whenever 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. + code, but it may fool the debuggers. enable_model-checking (on/OFF) Activates the formal verification mode. This will **hinder @@ -241,7 +244,7 @@ enable_smpi_MPICH3_testsuite (on/OFF) Reset the build configuration """"""""""""""""""""""""""""" -To empty the cmake cache (either when you add a new library or when +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. @@ -281,7 +284,7 @@ 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. +if some do not 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) @@ -314,11 +317,11 @@ on `our Jenkins `_. .. code-block:: shell ctest # Launch all tests - ctest -R s4u # Launch only the tests which name match the string "s4u" + ctest -R s4u # Launch only the tests whose names 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. @@ -330,24 +333,24 @@ 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, + This directory does not exist by default on modern Mac OS X versions, and you may need to create it with ``xcode-select -install`` .. _install_cmake_windows: @@ -382,7 +385,7 @@ things should be as simple as: make simgrid-java_jar # Only build the jarfile After the compilation, the file ```simgrid.jar``` is produced in the -root directory. +root directory. **Troubleshooting Java Builds** @@ -397,9 +400,9 @@ Sometimes, the build system fails to find the JNI headers. First locate them as Then, set the JAVA_INCLUDE_PATH environment variable to the right -path, and relaunch cmake. If you have several version of jni installed +path, and relaunch cmake. If you have several versions of JNI installed (as above), pick the one corresponding to the report of -``javac -version`` +``javac -version`` .. code-block:: shell @@ -412,7 +415,7 @@ 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 +On a multiarch x86_64 Linux, it should be possible to compile a 32-bit version of SimGrid with something like: .. code-block:: shell @@ -429,7 +432,7 @@ version of SimGrid with something like: If needed, implement ``i686-linux-gnu-gfortran`` as a script: .. code-block:: shell - + #!/usr/bin/env sh exec gfortran -m32 "$@"