=====================
SimGrid was conceived as a tool to study distributed algorithms. Its
-modern S4U interface makes it easy to assess Cloud, P2P, HPC, IoT and
-similar settings.
-
-A typical SimGrid simulation is composed of several **Actors**
-|api_s4u_Actor|_ , that execute user-provided functions. The actors
-have to explicitly use the S4U interface to express their computation,
-communication, disk usage and other **Activities** |api_s4u_Activity|_
-, so that they get reflected within the simulator. These activities
-take place on **Resources** (CPUs, links, disks). SimGrid predicts the
-time taken by each activity and orchestrates accordingly the actors
-waiting for the completion of these activities.
-
-.. |api_s4u_Actor| image:: /images/extlink.png
- :align: middle
- :width: 12
-.. _api_s4u_Actor: api/classsimgrid_1_1s4u_1_1Actor.html#class-documentation
+modern :ref:`S4U interface <S4U_doc>` makes it easy to assess Cloud,
+P2P, HPC, IoT and similar settings.
-.. |api_s4u_Activity| image:: /images/extlink.png
- :align: middle
- :width: 12
-.. _api_s4u_Activity: api/classsimgrid_1_1s4u_1_1Activity.html#class-documentation
+A typical SimGrid simulation is composed of several |Actors|_, that
+execute user-provided functions. The actors have to explicitly use the
+S4U interface to express their computation, communication, disk usage
+and other |Activities|_, so that they get reflected within the
+simulator. These activities take place on **Resources** (|Hosts|_,
+|Links|_, |Storages|_). SimGrid predicts the time taken by each
+activity and orchestrates accordingly the actors waiting for the
+completion of these activities.
+Each actor executes a user-provided function on a simulated |Host|_
+with which it can interact. Communications are not directly sent to
+actors, but posted onto a |Mailbox|_ that serve as rendez-vous point
+between communicating processes.
-Each actor executes a user-provided function on a simulated **Host**
-|api_s4u_Host|_ with which it can interact. Communications are not
-directly sent to actors, but posted onto **Mailboxes**
-|api_s4u_Mailbox|_ that serve as rendez-vous points between
-communicating processes.
+.. |Actors| replace:: **Actors**
+.. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html
-.. |api_s4u_Host| image:: /images/extlink.png
- :align: middle
- :width: 12
-.. _api_s4u_Host: api/classsimgrid_1_1s4u_1_1Host.html#class-documentation
+.. |Activities| replace:: **Activities**
+.. _Activities: api/classsimgrid_1_1s4u_1_1Activity.html
+
+.. |Hosts| replace:: **Hosts**
+.. _Hosts: api/classsimgrid_1_1s4u_1_1Host.html
+
+.. |Links| replace:: **Links**
+.. _Links: api/classsimgrid_1_1s4u_1_1Link.html
+
+.. |Storages| replace:: **Storages**
+.. _Storages: api/classsimgrid_1_1s4u_1_1Storage.html
+
+.. |VirtualMachines| replace:: **VirtualMachines**
+.. _VirtualMachines: api/classsimgrid_1_1s4u_1_1VirtualMachine.html
+
+.. |Host| replace:: **Host**
+.. _Host: api/classsimgrid_1_1s4u_1_1Host.html
+
+.. |Link| replace:: **Link**
+.. _Link: api/classsimgrid_1_1s4u_1_1Link.html
+
+.. |Mailbox| replace:: **Mailbox**
+.. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html
+
+.. |Barrier| replace:: **Barrier**
+.. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html
+
+.. |ConditionVariable| replace:: **ConditionVariable**
+.. _ConditionVariable: api/classsimgrid_1_1s4u_1_1ConditionVariable.html
+
+.. |Mutex| replace:: **Mutex**
+.. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
-.. |api_s4u_Mailbox| image:: /images/extlink.png
- :align: middle
- :width: 12
-.. _api_s4u_Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation
**In the remainder of this tutorial**, you will discover a simple yet
fully functioning example of SimGrid simulation: the Master/Workers
application. We will detail each part of the code and necessary
configuration to make it working. After this tour, several exercises
are proposed to let you discover some of the SimGrid features, hands
-on the keyboard.
+on the keyboard. This practical session will be given in C++, that you
+are supposed to know beforehand.
Discover the Master/Workers
Platform files define the virtual platform on which the provided
application will take place. In contains one or several **Network
-Zone** |api_s4u_NetZone|_ that contain both **Host-** |api_s4u_Host|_
-and **Link-** |api_s4u_Link|_ Resources, as well as routing
-information.
+Zone** |api_s4u_NetZone|_ that contain both |Host|_ and |Link|_
+Resources, as well as routing information.
Such files can get rather long and boring, so the example below is
only an excerpts of the full ``examples/platforms/small_platform.xml``
traverses 6 links (named 4, 3, 2, 0, 1 and 8). There are several
examples of platforms in the archive under ``examples/platforms``.
-.. |api_s4u_NetZone| image:: /images/extlink.png
+.. |api_s4u_NetZone| image:: /img/extlink.png
:align: middle
:width: 12
.. _api_s4u_NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html#class-documentation
-.. |api_s4u_Link| image:: /images/extlink.png
+.. |api_s4u_Link| image:: /img/extlink.png
:align: middle
:width: 12
.. _api_s4u_Link: api/classsimgrid_1_1s4u_1_1Link.html#class-documentation
.. image:: /tuto_s4u/img/result.png
:align: center
-Prerequisite
+Using Docker
............
-Before your proceed, you need to :ref:`install SimGrid <install>`, a
-C++ compiler and also ``pajeng`` to visualize the traces. You may want
-to install `Vite <http://vite.gforge.inria.fr/>`_ to get a first
-glance at the traces. The provided code template requires cmake to
-compile. On Debian and Ubuntu for example, you can get them as
-follows:
+The easiest way to take the tutorial is to use the dedicated Docker
+image. Once you `installed Docker itself
+<https://docs.docker.com/install/>`_, simply do the following:
+
+.. code-block:: shell
+
+ docker pull simgrid/tuto-s4u
+ docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/src/tutorial simgrid/tuto-s4u bash
+
+This will start a new container with all you need to take this
+tutorial, and create a ``simgrid-tutorial`` directory in your home on
+your host machine that will be visible as ``/src/tutorial`` within the
+container. You can then edit the files you want with your favorite
+editor in ``~/simgrid-tutorial``, and compile them within the
+container to enjoy the provided dependencies.
+
+.. warning::
+
+ Any change to the container out of ``/src/tutorial`` will be lost
+ when you log out of the container, so don't edit the other files!
+
+All needed dependencies are already installed in this container
+(SimGrid, a C++ compiler, cmake, pajeng and R). Vite being only
+optional in this tutorial, it is not installed to reduce the image
+size.
+
+The code template is available under ``/src/simgrid-template-s4u`` in
+the image. You should copy it to your working directory when you first
+log in:
+
+.. code-block:: shell
+
+ cp -r /src/simgrid-template-s4u/* /src/tutorial
+ cd /src/tutorial
+
+Using your Computer Natively
+............................
+
+To take the tutorial on your machine, you first need to :ref:`install
+SimGrid <install>`, a C++ compiler and also ``pajeng`` to visualize
+the traces. You may want to install `Vite
+<http://vite.gforge.inria.fr/>`_ to get a first glance at the
+traces. The provided code template requires cmake to compile. On
+Debian and Ubuntu for example, you can get them as follows:
.. code-block:: shell
you can find it in <simgrid_root_directory>/bin/colorize.
For a classical Gantt-Chart vizualisation, you can use `Vite
-<http://vite.gforge.inria.fr/>`_ as follows:
+<http://vite.gforge.inria.fr/>`_ if you have it installed, as
+follows. But do not spend too much time installing Vite, because there
+is a better way to visualize SimGrid traces (see below).
.. code-block:: shell
.. image:: /tuto_s4u/img/vite-screenshot.png
:align: center
-But if you want the full power to visualize SimGrid traces, you need
+If you want the full power to visualize SimGrid traces, you need
to use R. As a start, you can download this `starter script
<https://framagit.org/simgrid/simgrid/raw/master/docs/source/tuto_s4u/draw_gantt.R>`_
and use it as follows:
the involved parties.
Please refer to the full `API of Mailboxes
-<api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation>`_
-|api_s4u_Mailbox|_ for more details.
+<api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation>`_ for
+more details.
Lab 2: Using the Whole Platform
TODO: Points to improve for the next time
- Propose equivalent exercises and skeleton in java.
- - Propose a virtualbox image with everything (simgrid, pajeng, ...) already set
- up.
- - Ease the installation on mac OS X (binary installer) and
- windows.
- - Explain that programming in C or java and having a working
- development environment is a prerequisite.
-
-
-
-
+ - Propose a virtualbox image with everything (simgrid, pajeng, ...) already set up.
+ - Ease the installation on mac OS X (binary installer) and windows.
.. LocalWords: SimGrid
