X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/9104957deccc59e0e804215d5db498fabfd40d29..b1aab1883b891257e92a8b8b20a3a1b4b9b6efd4:/docs/source/Installing_SimGrid.rst diff --git a/docs/source/Installing_SimGrid.rst b/docs/source/Installing_SimGrid.rst index c5bf3044df..0b6659bfbf 100644 --- a/docs/source/Installing_SimGrid.rst +++ b/docs/source/Installing_SimGrid.rst @@ -1,4 +1,4 @@ -.. Copyright 2005-2020 +.. Copyright 2005-2021 .. _install: @@ -19,11 +19,11 @@ Binaries for Linux To get all of SimGrid on Debian or Ubuntu, simply type one of the following lines, or several lines if you need several languages. -.. code-block:: shell +.. code-block:: console - apt install libsimgrid-dev # if you want to develop in C or C++ - apt install simgrid-java # if you want to develop in Java - apt install python3-simgrid # if you want to develop in Python + $ apt install libsimgrid-dev # if you want to develop in C or C++ + $ apt install simgrid-java # if you want to develop in Java + $ apt install python3-simgrid # if you want to develop in Python If you build pre-compiled packages for other distributions, drop us an email. @@ -34,21 +34,16 @@ Stable Java Package ^^^^^^^^^^^^^^^^^^^ The jar file can be retrieved from the `Release page -`_. This file is +`_. This file is self-contained, including the native components for Linux, macOS and Windows. Copy it to your project's classpath and you're set. Nightly built Java Package ^^^^^^^^^^^^^^^^^^^^^^^^^^ -For non-Windows systems (Linux, macOS, 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 artifact -will appear at the top of the resulting page. - -For Windows, head to `AppVeyor `_. -Click on the artifact link on the right, and grab your file. If the latest build failed, there will be no artifact. Then -you will need to first click on "History" at the top and look for the last successful build. +Head to the corresponding `GitHub Action `_ +and pick the last green build. At the bottom of the build page, click on the ``jar-final`` artefact. +Open this zip file to find the jar you need. This jar can be used under Linux, Mac OSX or Windows, as you wish. Binary Java Troubleshooting ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -63,6 +58,8 @@ Library not found: boost-context You should obviously install the ``boost-context`` library on your machine, for example with ``apt``. +.. _deprecation_policy: + Version numbering and deprecation --------------------------------- @@ -72,7 +69,7 @@ per year, numbered 3.24 or 3.25. Backward compatibility is ensured for one year: Code compiling without warning on 3.24 will still compile with 3.28, but maybe with some deprecation warnings. You should update your SimGrid installation at least once a year and fix those -deprecation warnings: the compatiblity wrappers are usually removed +deprecation warnings: the compatibility wrappers are usually removed after 4 versions. Another approach is to never update your SimGrid installation, but we don't provide any support to old versions. @@ -97,7 +94,7 @@ Getting the Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^ C++ compiler (either g++, clang, or icc). - We use the C++11 standard, and older compilers tend to fail on + We use the C++14 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. @@ -130,27 +127,27 @@ Getting the Sources ^^^^^^^^^^^^^^^^^^^ Grab the last **stable release** from `FramaGit -`_, and compile it as follows: +`_, and compile it as follows: -.. code-block:: shell +.. code-block:: console - tar xf SimGrid-3-XX.tar.gz - cd SimGrid-* - cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . - make - make install + $ 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 +.. code-block:: console - git clone https://framagit.org/simgrid/simgrid.git - cd simgrid - cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . - make - make install + $ git clone https://framagit.org/simgrid/simgrid.git + $ cd simgrid + $ cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . + $ make + $ make install .. _install_src_config: @@ -199,17 +196,17 @@ prefer the ``-D`` flag of ``cmake``. For example, you can change the compilers by issuing these commands to set some environment variables before launching cmake: -.. code-block:: shell +.. code-block:: console - export CC=gcc-5.1 - export CXX=g++-5.1 + $ 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 dot at the end is mandatory (see :ref:`install_cmake_outsrc`). -.. code-block:: shell +.. code-block:: console - cmake -DCC=clang -DCXX=clang++ . + $ cmake -DCC=clang -DCXX=clang++ . SimGrid compilation options """"""""""""""""""""""""""" @@ -233,10 +230,10 @@ enable_compile_warnings (on/OFF) enable_debug (ON/off) Disabling this option discards all log messages of severity - debug or below at compile time (see @ref XBT_log). The resulting - 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. + debug or below at compile time (see :ref:`outcome_logs`). The resulting + code is marginaly faster than if you discard these messages at + runtime, but it obviously becomes impossible to get any debug + info from SimGrid when things go wrong. enable_documentation (on/OFF) Generates the documentation pages. Building the documentation is not @@ -293,6 +290,10 @@ minimal-bindings (on/OFF) Take as few optional dependencies as possible, to get minimal library bindings in Java and Python. +SMPI_C_FLAGS, SMPI_CXX_FLAGS, SMPI_Fortran_FLAGS (string) + Default compiler options to use in smpicc, smpicxx, or smpiff. + This can be useful to set options like "-m32" or "-m64". + Reset the build configuration """"""""""""""""""""""""""""" @@ -315,22 +316,22 @@ 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 +.. code-block:: console - mkdir build - cd build - cmake [options] .. - make + $ mkdir build + $ cd build + $ cmake [options] .. + $ make Existing Compilation Targets ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In most cases, compiling and installing SimGrid is enough: -.. code-block:: shell +.. code-block:: console - make - make install # try "sudo make install" if you don't have the permission to write + $ 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 @@ -341,7 +342,7 @@ if some do not work for you. - **make**: Build the core of SimGrid that gets installed, but not any example. - **make tests**: Build the tests and examples. - **make simgrid**: Build only the SimGrid library. Not any example nor the helper tools. -- **make s4u-app-pingpong**: Build only this example (works for any example) +- **make s4u-comm-pingpong**: Build only this example (works for any example) - **make java-all**: Build all Java examples and their dependencies - **make clean**: Clean the results of a previous compilation - **make install**: Install the project (doc/ bin/ lib/ include/) @@ -353,9 +354,9 @@ if some do not work for you. If you want to see what is really happening, try adding ``VERBOSE=1`` to your compilation requests: -.. code-block:: shell +.. code-block:: console - make VERBOSE=1 + $ make VERBOSE=1 .. _install_src_test: @@ -369,17 +370,18 @@ default, so you first have to build them with ``make tests``. You can then run them with ``ctest``, that comes with CMake. We run them every commit and the results are on `our Jenkins `_. -.. code-block:: shell +.. code-block:: console - make tests # Build the tests - ctest # Launch all tests - 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 + $ make tests # Build the tests + $ ctest # Launch all tests + $ 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. + $ 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: @@ -388,10 +390,10 @@ macOS-specific instructions SimGrid compiles like a charm with clang (version 3.0 or higher) on macOS: -.. code-block:: shell +.. code-block:: console - cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ . - make + $ cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ . + $ make Troubleshooting your macOS build. @@ -437,17 +439,17 @@ recent version of the `pybind11 ` module (version at least 2.4), recompiling the Python bindings from the source should be as easy as: -.. code-block:: shell +.. code-block:: console # cd simgrid-source-tree - python setup.py build install + $ python setup.py build install Starting with SimGrid 3.13, it should even be possible to install simgrid without downloading the source with pip: -.. code-block:: shell +.. code-block:: console - pip install simgrid + $ pip install simgrid Java-specific instructions ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -455,10 +457,10 @@ Java-specific instructions Once you have the `full JDK `_ installed, things should be as simple as: -.. code-block:: shell +.. code-block:: console - cmake -Denable_java=ON -Dminimal-bindings=ON . - make simgrid-java_jar # Only build the jarfile + $ cmake -Denable_java=ON -Dminimal-bindings=ON . + $ make simgrid-java_jar # Only build the jarfile After the compilation, the file ```simgrid.jar``` is produced in the root directory. @@ -467,7 +469,7 @@ root directory. Sometimes, the build system fails to find the JNI headers. First locate them as follows: -.. code-block:: shell +.. code-block:: console $ locate jni.h /usr/lib/jvm/java-8-openjdk-amd64/include/jni.h @@ -480,11 +482,11 @@ path, and relaunch cmake. If you have several versions of JNI installed (as above), pick the one corresponding to the report of ``javac -version`` -.. code-block:: shell +.. code-block:: console - export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-8-openjdk-amd64/include/ - cmake -Denable_java=ON . - make + $ 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. @@ -494,16 +496,19 @@ Linux Multi-Arch specific instructions 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 +.. code-block:: console + + $ CFLAGS=-m32 \ + CXXFLAGS=-m32 \ + FFLAGS=-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 \ + -DSMPI_C_FLAGS=-m32 \ + -DSMPI_CXX_FLAGS=-m32 \ + -DSMPI_Fortran_FLAGS=-m32 If needed, implement ``i686-linux-gnu-gfortran`` as a script: