X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/eb8ccfc173fea34bbb00377623da7fdfb4411df7..a805c48862448771e5c0b108e9a150ba0a54ccc9:/docs/source/Installing_SimGrid.rst?ds=sidebyside diff --git a/docs/source/Installing_SimGrid.rst b/docs/source/Installing_SimGrid.rst index 3c65560a8a..adfb90ee6e 100644 --- a/docs/source/Installing_SimGrid.rst +++ b/docs/source/Installing_SimGrid.rst @@ -1,4 +1,4 @@ -.. Copyright 2005-2021 +.. Copyright 2005-2023 .. _install: @@ -7,8 +7,7 @@ Installing SimGrid SimGrid should work out of the box on Linux, macOS, FreeBSD, and -Windows (under Windows, you need to install the Windows Subsystem -Linux to get more than the Java bindings). +Windows (with WSL). Pre-compiled Packages --------------------- @@ -22,46 +21,29 @@ following lines, or several lines if you need several languages. .. 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 -If you build pre-compiled packages for other distributions, drop us an -email. - -.. _install_java_precompiled: - -Stable Java Package -^^^^^^^^^^^^^^^^^^^ - -The jar file can be retrieved from the `Release page -`_. 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you use the Nix_ package manager, the latest SimGrid release is packaged as ``simgrid`` in Nixpkgs_. +Previous SimGrid versions are maintained in `NUR-Kapack`_ and are available +pre-compiled in release and debug modes on the `capack cachix binary cache`_ +— refer to `NUR-Kapack's documentation`_ for usage instructions. -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. +If you use a pacman-based system (*e.g.*, Arch Linux and derived distributions), +the latest SimGrid is available in the `simgrid AUR package`_ +— refer to `AUR official documentation`_ for installation instructions. -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. - -Binary Java Troubleshooting -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you build pre-compiled packages for other distributions, drop us an +email. -Here are some error messages that you may get when trying to use the -binary Java package. +.. _Nix: https://nixos.org/ +.. _Nixpkgs: https://github.com/NixOS/nixpkgs +.. _NUR-Kapack: https://github.com/oar-team/nur-kapack +.. _capack cachix binary cache: https://app.cachix.org/cache/capack +.. _NUR-Kapack's documentation: https://github.com/oar-team/nur-kapack +.. _simgrid AUR package: https://aur.archlinux.org/packages/simgrid/ +.. _AUR official documentation: https://wiki.archlinux.org/title/Arch_User_Repository -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``. +.. _deprecation_policy: Version numbering and deprecation --------------------------------- @@ -93,12 +75,14 @@ but that's even more so for these unreleased versions). Installing from the Source -------------------------- +.. _install_src_deps: + Getting the Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^ C++ compiler (either g++, clang, or icc). - 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 + We use the C++17 standard, and older compilers tend to fail on + us. It seems that g++ 7.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 regression test suite. @@ -106,23 +90,23 @@ cmake (v3.5). ``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`` +boost mandatory components (at least v1.48, v1.59 recommended) + - On Debian / Ubuntu: ``apt install libboost-dev`` + - On CentOS / Fedora: ``dnf install boost-devel`` - On macOS with homebrew: ``brew install boost`` -Java (optional): - - Debian / Ubuntu: ``apt install default-jdk libgcj18-dev`` (or - any version of libgcj) - - macOS 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`` +boost recommended components (optional). + - boost-context may be used instead of our own fast context switching code which only works on amd64. + - boost-stacktrace is used to get nice stacktraces on errors in SimGrid. + - On Debian / Ubuntu: ``apt install libboost-context-dev libboost-stacktrace-dev`` +python bindings (optional): + - On Debian / Ubuntu: ``apt install pybind11-dev python3-dev`` +Model-checking dependencies (optional) + - On Debian / Ubuntu: ``apt install libunwind-dev libdw-dev libelf-dev libevent-dev`` +Eigen3 (optional) + - On Debian / Ubuntu: ``apt install libeigen3-dev`` + - On CentOS / Fedora: ``dnf install eigen3-devel`` + - On macOS with homebrew: ``brew install eigen`` + - Use EIGEN3_HINT to specify where it's installed if cmake doesn't find it automatically. For platform-specific details, please see below. @@ -130,13 +114,13 @@ Getting the Sources ^^^^^^^^^^^^^^^^^^^ Grab the last **stable release** from `FramaGit -`_, and compile it as follows: +`_, and compile it as follows: .. code-block:: console $ tar xf simgrid-3-XX.tar.gz $ cd simgrid-* - $ cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . + $ cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid -GNinja . $ make $ make install @@ -153,7 +137,7 @@ dependencies. $ make install .. _install_src_config: - + Build Configuration ^^^^^^^^^^^^^^^^^^^ @@ -172,9 +156,8 @@ cmake itself. files, such as ``CMakeCache.txt``. Since Cmake also generates some files in the tree, you may need to wipe out your complete tree and start with a fresh one when you install new dependencies. - - Another (better) solution is to :ref:`build out of the source tree - `. + + A better solution is to :ref:`build out of the source tree `. Generic build-time options """""""""""""""""""""""""" @@ -243,20 +226,6 @@ enable_documentation (on/OFF) as easy as it used to be, and you should probably use the online version for now. -enable_java (on/OFF) - Generates the java bindings of SimGrid. You must also enable MSG for - this to work. - -enable_jedule (on/OFF) - Produces execution traces from SimDag simulations, which 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 code produced, but it is fragile @@ -270,20 +239,17 @@ enable_mallocators (ON/off) 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_msg (on/OFF) - Activates the :ref:`MSG ` legacy interface. + Activates the formal verification mode. This will hinder simulation speed even when the model checker is not activated at run + time, because some optimizations such as LTO must be disabled at compile time. You need to have the :ref:`required + build-dependencies ` to activate this option. enable_ns3 (on/OFF) - Activates the ns-3 bindings. See section :ref:`model_ns3`. + Activates the ns-3 bindings. See section :ref:`models_ns3`. enable_smpi (ON/off) Allows one to run MPI code on top of SimGrid. -enable_smpi_ISP_testsuite (on/OFF) +enable_smpi_MBI_testsuite (on/OFF) Adds many extra tests for the model checker module. enable_smpi_MPICH3_testsuite (on/OFF) @@ -291,7 +257,18 @@ enable_smpi_MPICH3_testsuite (on/OFF) minimal-bindings (on/OFF) Take as few optional dependencies as possible, to get minimal - library bindings in Java and Python. + library bindings in Python. + +NS3_HINT (empty by default) + Alternative path into which ns-3 should be searched for. + +EIGEN3_HINT (empty by default) + Alternative path into which Eigen3 should be searched for. + +SIMGRID_PYTHON_LIBDIR (auto-detected) + Where to install the Python module library. By default, it is set to the cmake Python3_SITEARCH variable if installing to /usr, + and a modified version of that variable if installing to another path. Just force another value if the auto-detected default + does not fit your setup. SMPI_C_FLAGS, SMPI_CXX_FLAGS, SMPI_Fortran_FLAGS (string) Default compiler options to use in smpicc, smpicxx, or smpiff. @@ -346,10 +323,9 @@ if some do not work for you. - **make tests**: Build the tests and examples. - **make simgrid**: Build only the SimGrid library. Not any example nor the helper tools. - **make s4u-comm-pingpong**: Build only this example (works for any example) -- **make java-all**: Build all Java examples and their dependencies +- **make python-bindings**: Build the Python bindings - **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 @@ -421,102 +397,25 @@ Windows-specific instructions 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. Some clang-based tools seem promising to fix this, -but this is of rather low priority for us. It it's important for you -and if you get it working, please @ref community_contact "tell us". +works in this setting. Native builds never really worked, and they are +disabled starting with SimGrid v3.33. Python-specific instructions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once you have the Python development headers installed as well as a -recent version of the `pybind11 ` +recent version of the `pybind11 `_ module (version at least 2.4), recompiling the Python bindings from -the source should be as easy as: +the source should be as easy as: .. code-block:: console # cd simgrid-source-tree $ 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:: console $ pip install simgrid - -Java-specific instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Once you have the `full JDK `_ installed, -things should be as simple as: - -.. code-block:: console - - $ 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. - -**Troubleshooting Java Builds** - -Sometimes, the build system fails to find the JNI headers. First locate them as follows: - -.. code-block:: console - - $ 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 versions of JNI installed -(as above), pick the one corresponding to the report of -``javac -version`` - -.. code-block:: console - - $ 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 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:: 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: - -.. code-block:: shell - - #!/usr/bin/env sh - exec gfortran -m32 "$@" -