doc: fix the list of make targets

[simgrid.git] / docs / source / Installing_SimGrid.rst

diff --git a/docs/source/Installing_SimGrid.rst b/docs/source/Installing_SimGrid.rst
index e441110..160da07 100644 (file)
--- a/docs/source/Installing_SimGrid.rst
+++ b/docs/source/Installing_SimGrid.rst
@@ -1,4 +1,4 @@
-.. Copyright 2005-2018
+.. Copyright 2005-2019

 
 .. _install:
 
 
 .. _install:
 


@@ -6,7 +6,7 @@ Installing SimGrid
 ==================
 
 
 ==================
 
 

-SimGrid should work out of the box on Linux, Mac OSX, FreeBSD, and
+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 (under Windows, you need to install the Windows Subsystem
 Linux to get more than the Java bindings).
 


@@ -16,11 +16,14 @@ Pre-compiled Packages
 Binaries for Linux
 ^^^^^^^^^^^^^^^^^^
 
 Binaries for Linux
 ^^^^^^^^^^^^^^^^^^
 

-On Debian or Ubuntu, simply type:
+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:: shell
 

-   apt install simgrid
+   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.
 
 If you build pre-compiled packages for other distributions, drop us an
 email.


@@ -31,14 +34,14 @@ Stable Java Package
 ^^^^^^^^^^^^^^^^^^^
 
 The jar file can be retrieved from the `Release page
 ^^^^^^^^^^^^^^^^^^^
 
 The jar file can be retrieved from the `Release page

-<https://framagit.org/simgrid/simgrid/tags>`_. This file is
-self-contained, including the native components for Linux, Mac OS X and
+<https://framagit.org/simgrid/simgrid/releases>`_. 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Windows. Copy it to your project's classpath and you're set.
 
 Nightly built Java Package
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

-For non-Windows systems (Linux, Mac OS X, or FreeBSD), head to `Jenkins <https://ci.inria.fr/simgrid/job/SimGrid>`_.
+For non-Windows systems (Linux, macOS, or FreeBSD), head to `Jenkins <https://ci.inria.fr/simgrid/job/SimGrid>`_.

 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.
 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.


@@ -74,17 +77,17 @@ C++ compiler (either g++, clang, or icc).
   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.
   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).
+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``
   ``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``
+  - On macOS with homebrew: ``brew install boost``

 Java (optional):
   - Debian / Ubuntu: ``apt install default-jdk libgcj18-dev`` (or
     any version of libgcj)
 Java (optional):
   - Debian / Ubuntu: ``apt install default-jdk libgcj18-dev`` (or
     any version of libgcj)

-  - Mac OS X or Windows: Grab a `full JDK <http://www.oracle.com/technetwork/java/javase/downloads>`_
+  - macOS or Windows: Grab a `full JDK <http://www.oracle.com/technetwork/java/javase/downloads>`_

 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``
 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``


@@ -102,7 +105,7 @@ Getting the Sources
 ^^^^^^^^^^^^^^^^^^^
 
 Grab the last **stable release** from `FramaGit
 ^^^^^^^^^^^^^^^^^^^
 
 Grab the last **stable release** from `FramaGit

-<https://framagit.org/simgrid/simgrid/tags>`_, and compile it as follows:
+<https://framagit.org/simgrid/simgrid/releases>`_, and compile it as follows:

 
 .. code-block:: shell
 
 
 .. code-block:: shell
 


@@ -118,7 +121,7 @@ dependencies.
 
 .. code-block:: shell
 
 
 .. code-block:: shell
 

-   git clone git@framagit.org:simgrid/simgrid.git
+   git clone https://framagit.org/simgrid/simgrid.git

    cd simgrid
    cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid .
    make
    cd simgrid
    cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid .
    make


@@ -135,6 +138,19 @@ fall into two categories. **SimGrid-specific options** define which part
 of the framework to compile while **Generic options** are provided by
 cmake itself.
 
 of the framework to compile while **Generic options** are provided by
 cmake itself.
 

+.. warning::
+
+   Our build system often gets mixed up if you change something on
+   your machine after the build configuration.  For example, if
+   SimGrid fails to detect your fortran compiler, it is not enough to
+   install a fortran compiler. You also need to clean every Cmake
+   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
+   <install_cmake_outsrc>`.
+

 Generic build-time options
 """"""""""""""""""""""""""
 
 Generic build-time options
 """"""""""""""""""""""""""
 


@@ -198,8 +214,10 @@ enable_debug (ON/off)
   runtime. However, it obviously becomes impossible to get any debug
   info from SimGrid if something goes wrong.
 
   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_documentation (on/OFF)
+  Generates the documentation pages. Building the documentation is not
+  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.
 
 enable_java (on/OFF)
   Generates the java bindings of SimGrid.


@@ -232,7 +250,7 @@ enable_model-checking (on/OFF)
   run time.
 
 enable_ns3 (on/OFF)
   run time.
 
 enable_ns3 (on/OFF)

-  Activates the ns-3 bindings. See section @ref pls_ns3.
+  Activates the ns-3 bindings. See section :ref:`model_ns3`.

 
 enable_smpi (ON/off)
   Allows to run MPI code on top of SimGrid.
 
 enable_smpi (ON/off)
   Allows to run MPI code on top of SimGrid.


@@ -243,6 +261,10 @@ enable_smpi_ISP_testsuite (on/OFF)
 enable_smpi_MPICH3_testsuite (on/OFF)
   Adds many extra tests for the MPI module.
 
 enable_smpi_MPICH3_testsuite (on/OFF)
   Adds many extra tests for the MPI module.
 

+minimal-bindings (on/OFF)
+  Take as few optional dependencies as possible, to get minimal
+  library bindings in Java and Python.
+

 Reset the build configuration
 """""""""""""""""""""""""""""
 
 Reset the build configuration
 """""""""""""""""""""""""""""
 


@@ -288,7 +310,9 @@ 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 do not work for you.
 
 existing targets are not really for public consumption so don't worry
 if some do not work for you.
 

-- **make simgrid**: Build only the SimGrid library and not any example
+- **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 java-all**: Build all Java examples and their dependencies
 - **make clean**: Clean the results of a previous compilation
 - **make s4u-app-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


@@ -329,10 +353,10 @@ on `our Jenkins <https://ci.inria.fr/simgrid/>`_.
 
 .. _install_cmake_mac:
 
 
 .. _install_cmake_mac:
 

-Mac OS X Specifics
-^^^^^^^^^^^^^^^^^^
+macOS-specific instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^

 
 

-SimGrid compiles like a charm with clang (version 3.0 or higher) on Mac OS X:
+SimGrid compiles like a charm with clang (version 3.0 or higher) on macOS:

 
 .. code-block:: shell
 
 
 .. code-block:: shell
 


@@ -340,7 +364,7 @@ SimGrid compiles like a charm with clang (version 3.0 or higher) on Mac OS X:
   make
 
 
   make
 
 

-Troubleshooting your Mac OS X build.
+Troubleshooting your macOS 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
 
 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


@@ -352,13 +376,13 @@ CMake Error: Parse error in cache file build_dir/CMakeCache.txt. Offending entry
   You can safely ignore the warning about "-pthread" not being used, if it appears.
 
 /usr/include does not seem to exist
   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 OS X versions,
+  This directory does not exist by default on modern macOS versions,

   and you may need to create it with ``xcode-select -install``
 
 .. _install_cmake_windows:
 
   and you may need to create it with ``xcode-select -install``
 
 .. _install_cmake_windows:
 

-Windows Specifics
-^^^^^^^^^^^^^^^^^
+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)
 
 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)


@@ -371,19 +395,36 @@ 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
 needs.
 
 The drawback of MinGW-64 is that the produced DLL are not compatible

-with MS Visual C. `clang-cl <http://clang.llvm.org/docs/MSVCCompatibility.html">`_
-sounds promising to fix this. If you get something working or if you
-have any other improvement, please @ref community_contact "tell us".
+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".
+
+Python-specific instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 
 

-Java Specifics
-^^^^^^^^^^^^^^
+Recompiling the python bindings from the source should be as easy as:
+
+.. code-block:: shell
+
+  # 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:: shell
+
+  pip install simgrid
+
+Java-specific instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^

 
 Once you have the `full JDK <http://www.oracle.com/technetwork/java/javase/downloads>`_ installed,
 things should be as simple as:
 
 .. code-block:: shell
 
 
 Once you have the `full JDK <http://www.oracle.com/technetwork/java/javase/downloads>`_ installed,
 things should be as simple as:
 
 .. code-block:: shell
 

-   cmake -Denable_java=ON .
+   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
    make  simgrid-java_jar # Only build the jarfile
 
 After the compilation, the file ```simgrid.jar``` is produced in the


@@ -414,8 +455,8 @@ path, and relaunch cmake. If you have several versions of JNI installed
 
 Note that the filename ```jni.h``` was removed from the path.
 
 
 Note that the filename ```jni.h``` was removed from the path.
 

-Linux Multi-Arch Specifics
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+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:
 
 On a multiarch x86_64 Linux, it should be possible to compile a 32-bit
 version of SimGrid with something like: