Build nice python source packages

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

diff --git a/docs/source/Installing_SimGrid.rst b/docs/source/Installing_SimGrid.rst
index cb94bd1..31cb7e9 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:
 
@@ -135,6 +135,19 @@ fall into two categories. **SimGrid-specific options** define which part
 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
 """"""""""""""""""""""""""
 
@@ -198,8 +211,10 @@ enable_debug (ON/off)
   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.
@@ -243,6 +258,10 @@ enable_smpi_ISP_testsuite (on/OFF)
 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
 """""""""""""""""""""""""""""
 
@@ -329,8 +348,8 @@ on `our Jenkins <https://ci.inria.fr/simgrid/>`_.
 
 .. _install_cmake_mac:
 
-macOS Specifics
-^^^^^^^^^^^^^^^
+macOS-specific instructions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 SimGrid compiles like a charm with clang (version 3.0 or higher) on macOS:
 
@@ -357,8 +376,8 @@ CMake Error: Parse error in cache file build_dir/CMakeCache.txt. Offending entry
 
 .. _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)
@@ -371,19 +390,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
-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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Recompiling the python bindings from the source should be as easy as:
 
-Java Specifics
-^^^^^^^^^^^^^^
+.. 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
 
-   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
@@ -414,8 +450,8 @@ path, and relaunch cmake. If you have several versions of JNI installed
 
 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: