Merge branch 'dev/s4u_tuto_fixes' into 'master'

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

diff --git a/docs/source/Tutorial_Algorithms.rst b/docs/source/Tutorial_Algorithms.rst
index af93ee5..8adaa60 100644 (file)
--- a/docs/source/Tutorial_Algorithms.rst
+++ b/docs/source/Tutorial_Algorithms.rst
@@ -390,16 +390,32 @@ All needed dependencies are already installed in this container
 optional in this tutorial, it is not installed to reduce the image
 size.
 
+The docker does not run as root, so that the files can easily be exchanged between within the container and the outer world.
+If you need to run a command as root within the container, simply type the following in another terminal to join the same container as root:
+
+.. code-block:: console
+
+   $ docker container ls
+   # This lists all containers running on your machine. For example:
+   #    CONTAINER ID   IMAGE            COMMAND   CREATED         STATUS         PORTS     NAMES
+   #    7e921b1b18a7   simgrid/stable   "bash"    7 minutes ago   Up 7 minutes             simgrid
+
+   $ docker exec --user root -it simgrid bash
+
 The code template is available under ``/source/simgrid-template-s4u.git``
 in the image. You should copy it to your working directory and
 recompile it when you first log in:
 
 .. code-block:: console
 
-   $ cp -r /source/simgrid-template-s4u.git/* /source/tutorial
-   $ cd /source/tutorial
-   $ cmake .
-   $ make
+   $ # Make sure the simgrid-tutorial directory can be read and written by the non-root user
+   $ sudo chown $UID:$GID ~/simgrid-tutorial
+   $ # Connect to the running container if needed
+   $ docker exec --user $UID:$GID -ti simgrid bash
+   $container) cp -r /source/simgrid-template-s4u.git/* /source/tutorial
+   $container) cd /source/tutorial
+   $container) cmake .
+   $container) make
 
 Using your Computer Natively
 ............................
@@ -465,6 +481,15 @@ Using your Computer Natively
       your :ref:`SimGrid installation <install>`.  On need, please refer to
       the :ref:`Troubleshooting your Project Setup <install_yours_troubleshooting>` section.
 
+.. warning::
+
+   If you use the stable version of Debian 11, Ubuntu 21.04 or Ubuntu 21.10, then you need the right version of this tutorial 
+   (add ``--branch simgrid-v3.25`` as below). These distributions only contain SimGrid v3.25 while the latest version of this
+   tutorial needs at least SimGrid v3.27.
+
+   .. code-block:: console
+
+      $ git clone --branch simgrid-v3.25 https://framagit.org/simgrid/simgrid-template-s4u.git
 
 For R analysis of the produced traces, you may want to install R
 and the `pajengr <https://github.com/schnorr/pajengr#installation/>`_ package.
@@ -493,6 +518,9 @@ Discovering the Provided Code
          $ make master-workers
          $ ./master-workers small_platform.xml master-workers_d.xml
 
+      If you get an error message complaining that ``simgrid::s4u::Mailbox::get()`` does not exist, 
+      then your version of SimGrid is too old for the version of the tutorial that you got. Check again previous section.
+
    .. group-tab:: Python
 
       Please execute the provided simulator as follows:
@@ -501,6 +529,9 @@ Discovering the Provided Code
 
          $ python master-workers.py small_platform.xml master-workers_d.xml
 
+      If you get an error stating that the simgrid module does not exist, you need to get a newer version of SimGrid. 
+      You may want to take the tutorial from the docker to get the newest version.
+
 For a more "fancy" output, you can use simgrid-colorizer.
 
 .. code-block:: console