From eb8ccfc173fea34bbb00377623da7fdfb4411df7 Mon Sep 17 00:00:00 2001 From: Arnaud Giersch Date: Fri, 9 Jul 2021 13:33:15 +0200 Subject: [PATCH] Use 'console' syntax highlighting for shell typescripts. --- docs/source/Configuring_SimGrid.rst | 50 ++++---- docs/source/Installing_SimGrid.rst | 137 +++++++++++----------- docs/source/Models.rst | 12 +- docs/source/Start_your_own_project.rst | 10 +- docs/source/Tutorial_Algorithms.rst | 66 +++++------ docs/source/Tutorial_MPI_Applications.rst | 58 ++++----- docs/source/Tutorial_Model-checking.rst | 34 +++--- docs/source/app_msg.rst | 4 +- docs/source/app_smpi.rst | 32 ++--- 9 files changed, 203 insertions(+), 200 deletions(-) diff --git a/docs/source/Configuring_SimGrid.rst b/docs/source/Configuring_SimGrid.rst index 7b895d4478..71d9361554 100644 --- a/docs/source/Configuring_SimGrid.rst +++ b/docs/source/Configuring_SimGrid.rst @@ -32,9 +32,9 @@ The most common way is to use the ``--cfg`` command line argument. For example, to set the item ``Item`` to the value ``Value``, simply type the following on the command-line: -.. code-block:: shell +.. code-block:: console - my_simulator --cfg=Item:Value (other arguments) + $ my_simulator --cfg=Item:Value (other arguments) Several ``--cfg`` command line arguments can naturally be used. If you need to include spaces in the argument, don't forget to quote the @@ -345,10 +345,10 @@ the TCP congestion mechanism into account. On Linux, this value can be retrieved using the following commands. Both give a set of values, and you should use the last one, which is the maximal size. -.. code-block:: shell +.. code-block:: console - cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window - cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window + $ cat /proc/sys/net/ipv4/tcp_rmem # gives the sender window + $ cat /proc/sys/net/ipv4/tcp_wmem # gives the receiver window .. _cfg=network/bandwidth-factor: .. _cfg=network/latency-factor: @@ -562,9 +562,9 @@ Configuring the Model-Checking To enable SimGrid's model-checking support, the program should be executed using the simgrid-mc wrapper: -.. code-block:: shell +.. code-block:: console - simgrid-mc ./my_program + $ simgrid-mc ./my_program Safety properties are expressed as assertions using the function :cpp:func:`void MC_assert(int prop)`. @@ -607,9 +607,9 @@ the command line, specifying the name of the file containing the property, as formatted by the `ltl2ba `_ program. Note that ltl2ba is not part of SimGrid and must be installed separately. -.. code-block:: shell +.. code-block:: console - simgrid-mc ./my_program --cfg=model-check/property: + $ simgrid-mc ./my_program --cfg=model-check/property: .. _cfg=model-check/checkpoint: @@ -769,7 +769,7 @@ When the model checker finds an interesting path in the application execution graph (where a safety or liveness property is violated), it generates an identifier for this path. Here is an example of the output: -.. code-block:: shell +.. code-block:: console [ 0.000000] (0:@) Check a safety property [ 0.000000] (0:@) ************************** @@ -955,7 +955,7 @@ you never used the tracing API. - Any SimGrid-based simulator (MSG, SimDag, SMPI, ...) and raw traces: - .. code-block:: shell + .. code-block:: none --cfg=tracing:yes --cfg=tracing/uncategorized:yes @@ -966,7 +966,7 @@ you never used the tracing API. - MSG or SimDag-based simulator and categorized traces (you need to declare categories and classify your tasks according to them) - .. code-block:: shell + .. code-block:: none --cfg=tracing:yes --cfg=tracing/categorized:yes @@ -975,9 +975,9 @@ you never used the tracing API. - SMPI simulator and traces for a space/time view: - .. code-block:: shell + .. code-block:: console - smpirun -trace ... + $ smpirun -trace ... The `-trace` parameter for the smpirun script runs the simulation with ``--cfg=tracing:yes --cfg=tracing/smpi:yes``. Check the @@ -989,13 +989,13 @@ reproduce an experiment. You have two ways to do that: - Add a string on top of the trace file as comment: - .. code-block:: shell + .. code-block:: none --cfg=tracing/comment:my_simulation_identifier - Add the contents of a textual file on top of the trace file as comment: - .. code-block:: shell + .. code-block:: none --cfg=tracing/comment-file:my_file_with_additional_information.txt @@ -1102,7 +1102,7 @@ This option allows you to pass a file that contains two columns: The first column defines the section that will be subject to a speedup; the second column is the speedup. For instance: -.. code-block:: shell +.. code-block:: none "start:stop","ratio" "exchange_1.f:30:exchange_1.f:130",1.18244559422142 @@ -1227,7 +1227,7 @@ It is planned to make this feature available on a per-process (or per-thread?) b The first draft, however, just implements a "global" (i.e., for all processes) set of counters, the "default" set. -.. code-block:: shell +.. code-block:: none --cfg=smpi/papi-events:"default:PAPI_L3_LDM:PAPI_L2_LDM" @@ -1278,9 +1278,9 @@ This configuration option can only use either full paths to libraries, or full names. Check with ldd the name of the library you want to use. For example: -.. code-block:: shell +.. code-block:: console - ldd allpairf90 + $ ldd allpairf90 ... libgfortran.so.3 => /usr/lib/x86_64-linux-gnu/libgfortran.so.3 (0x00007fbb4d91b000) ... @@ -1553,11 +1553,11 @@ entry per MB of malloced data instead of one entry per 4 kB. To activate this, you must mount a hugetlbfs on your system and allocate at least one huge page: -.. code-block:: shell +.. code-block:: console - mkdir /home/huge - sudo mount none /home/huge -t hugetlbfs -o rw,mode=0777 - sudo sh -c 'echo 1 > /proc/sys/vm/nr_hugepages' # echo more if you need more + $ mkdir /home/huge + $ sudo mount none /home/huge -t hugetlbfs -o rw,mode=0777 + $ sudo sh -c 'echo 1 > /proc/sys/vm/nr_hugepages' # echo more if you need more Then, you can pass the option ``--cfg=smpi/shared-malloc-hugepage:/home/huge`` to smpirun to @@ -1664,7 +1664,7 @@ It is also possible to set the breakpoint from inside the debugger, by writing in global variable simgrid::simix::breakpoint. For example, with gdb: -.. code-block:: shell +.. code-block:: none set variable simgrid::simix::breakpoint = 3.1416 diff --git a/docs/source/Installing_SimGrid.rst b/docs/source/Installing_SimGrid.rst index 0db6065d55..3c65560a8a 100644 --- a/docs/source/Installing_SimGrid.rst +++ b/docs/source/Installing_SimGrid.rst @@ -19,11 +19,11 @@ Binaries for Linux 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:: 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 + $ 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. @@ -132,25 +132,25 @@ Getting the Sources Grab the last **stable release** from `FramaGit `_, and compile it as follows: -.. code-block:: shell +.. code-block:: console - tar xf simgrid-3-XX.tar.gz - cd simgrid-* - cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . - make - make install + $ tar xf simgrid-3-XX.tar.gz + $ cd simgrid-* + $ cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . + $ make + $ make install If you want to stay on the **bleeding edge**, get the current git version, and recompile it as with stable archives. You may need some extra dependencies. -.. code-block:: shell +.. code-block:: console - git clone https://framagit.org/simgrid/simgrid.git - cd simgrid - cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . - make - make install + $ git clone https://framagit.org/simgrid/simgrid.git + $ cd simgrid + $ cmake -DCMAKE_INSTALL_PREFIX=/opt/simgrid . + $ make + $ make install .. _install_src_config: @@ -199,17 +199,17 @@ prefer the ``-D`` flag of ``cmake``. For example, you can change the compilers by issuing these commands to set some environment variables before launching cmake: -.. code-block:: shell +.. code-block:: console - export CC=gcc-5.1 - export CXX=g++-5.1 + $ export CC=gcc-5.1 + $ export CXX=g++-5.1 The same can be done by passing ``-D`` parameters to cmake, as follows. Note that the dot at the end is mandatory (see :ref:`install_cmake_outsrc`). -.. code-block:: shell +.. code-block:: console - cmake -DCC=clang -DCXX=clang++ . + $ cmake -DCC=clang -DCXX=clang++ . SimGrid compilation options """"""""""""""""""""""""""" @@ -319,22 +319,22 @@ For that, go to the directory where the files should be produced, and invoke cmake (or ccmake) with the full path to the SimGrid source as last argument. -.. code-block:: shell +.. code-block:: console - mkdir build - cd build - cmake [options] .. - make + $ mkdir build + $ cd build + $ cmake [options] .. + $ make Existing Compilation Targets ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In most cases, compiling and installing SimGrid is enough: -.. code-block:: shell +.. code-block:: console - make - make install # try "sudo make install" if you don't have the permission to write + $ make + $ make install # try "sudo make install" if you don't have the permission to write In addition, several compilation targets are provided in SimGrid. If your system is well configured, the full list of targets is available @@ -357,9 +357,9 @@ if some do not work for you. If you want to see what is really happening, try adding ``VERBOSE=1`` to your compilation requests: -.. code-block:: shell +.. code-block:: console - make VERBOSE=1 + $ make VERBOSE=1 .. _install_src_test: @@ -373,17 +373,18 @@ default, so you first have to build them with ``make tests``. You can then run them with ``ctest``, that comes with CMake. We run them every commit and the results are on `our Jenkins `_. -.. code-block:: shell +.. code-block:: console - make tests # Build the tests - ctest # Launch all tests - ctest -R s4u # Launch only the tests whose names match the string "s4u" - ctest -j4 # Launch all tests in parallel, at most 4 concurrent jobs - ctest --verbose # Display all details on what's going on - ctest --output-on-failure # Only get verbose for the tests that fail + $ make tests # Build the tests + $ ctest # Launch all tests + $ ctest -R s4u # Launch only the tests whose names match the string "s4u" + $ ctest -j4 # Launch all tests in parallel, at most 4 concurrent jobs + $ ctest --verbose # Display all details on what's going on + $ ctest --output-on-failure # Only get verbose for the tests that fail - ctest -R s4u -j4 --output-on-failure # You changed S4U and want to check that you didn't break anything, huh? - # That's fine, I do so all the time myself. + $ ctest -R s4u -j4 --output-on-failure # You changed S4U and want to check that you \ + # didn't break anything, huh? \ + # That's fine, I do so all the time myself. .. _install_cmake_mac: @@ -392,10 +393,10 @@ macOS-specific instructions SimGrid compiles like a charm with clang (version 3.0 or higher) on macOS: -.. code-block:: shell +.. code-block:: console - cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ . - make + $ cmake -DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++ . + $ make Troubleshooting your macOS build. @@ -441,17 +442,17 @@ recent version of the `pybind11 ` module (version at least 2.4), recompiling the Python bindings from the source should be as easy as: -.. code-block:: shell +.. code-block:: console # cd simgrid-source-tree - python setup.py build install + $ 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 +.. code-block:: console - pip install simgrid + $ pip install simgrid Java-specific instructions ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -459,10 +460,10 @@ Java-specific instructions Once you have the `full JDK `_ installed, things should be as simple as: -.. code-block:: shell +.. code-block:: console - cmake -Denable_java=ON -Dminimal-bindings=ON . - make simgrid-java_jar # Only build the jarfile + $ 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. @@ -471,7 +472,7 @@ root directory. Sometimes, the build system fails to find the JNI headers. First locate them as follows: -.. code-block:: shell +.. code-block:: console $ locate jni.h /usr/lib/jvm/java-8-openjdk-amd64/include/jni.h @@ -484,11 +485,11 @@ 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:: shell +.. code-block:: console - export JAVA_INCLUDE_PATH=/usr/lib/jvm/java-8-openjdk-amd64/include/ - cmake -Denable_java=ON . - make + $ 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. @@ -498,19 +499,19 @@ 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:: shell - - 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 +.. 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: diff --git a/docs/source/Models.rst b/docs/source/Models.rst index 4a8bf70cf6..c003ea66f5 100644 --- a/docs/source/Models.rst +++ b/docs/source/Models.rst @@ -107,9 +107,9 @@ SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake. Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on your disk. -.. code-block:: shell +.. code-block:: console - cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed + $ cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed By the end of the configuration, cmake reports whether ns-3 was found, and this information is also available in ``include/simgrid/config.h`` @@ -121,9 +121,9 @@ Test that ns-3 was successfully integrated with the following (from your SimGrid build directory). It will run all SimGrid tests that are related to the ns-3 integration. If no test is run at all, you probably forgot to enable ns-3 in cmake. -.. code-block:: shell +.. code-block:: console - ctest -R ns3 + $ ctest -R ns3 Troubleshooting --------------- @@ -198,9 +198,9 @@ Once your platform is OK, just change the :ref:`network/model ` configuration option to `ns-3` as follows. The other options can be used as usual. -.. code-block:: shell +.. code-block:: console - ./network-ns3 --cfg=network/model:ns-3 (other parameters) + $ ./network-ns3 --cfg=network/model:ns-3 (other parameters) Many other files from the ``examples/platform`` directory are usable with the ns-3 model, such as `examples/platforms/dogbone.xml `_. diff --git a/docs/source/Start_your_own_project.rst b/docs/source/Start_your_own_project.rst index 308d03936e..cb70ef0c0b 100644 --- a/docs/source/Start_your_own_project.rst +++ b/docs/source/Start_your_own_project.rst @@ -61,9 +61,9 @@ MPI projects should include ``find_package (MPI)`` in CMakeLists.txt. Then, the variables ``MPI_C_COMPILER``, ``MPI_CXX_COMPILER``, and ``MPI_Fortran_COMPILER`` should point to the full path of smpicc, smpicxx, and smpiff respectively. Example: -.. code-block:: shell +.. code-block:: console - cmake -DMPI_C_COMPILER=/opt/simgrid/bin/smpicc -DMPI_CXX_COMPILER=/opt/simgrid/bin/smpicxx -DMPI_Fortran_COMPILER=/opt/simgrid/bin/smpiff . + $ cmake -DMPI_C_COMPILER=/opt/simgrid/bin/smpicc -DMPI_CXX_COMPILER=/opt/simgrid/bin/smpicxx -DMPI_Fortran_COMPILER=/opt/simgrid/bin/smpiff . Building your project with Makefile @@ -158,9 +158,9 @@ Library not found When the library cannot be found, you will get such an error message similar to: -.. code-block:: shell +.. code-block:: console - ./masterworker1: error while loading shared libraries: libsimgrid.so: cannot open shared object file: No such file or directory + $ ./masterworker1: error while loading shared libraries: libsimgrid.so: cannot open shared object file: No such file or directory To fix this, add the path to where you installed the library to the ``LD_LIBRARY_PATH`` variable. You can add the following line to your @@ -175,7 +175,7 @@ computer. Many undefined references ^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: shell +.. code-block:: console masterworker.c:209: undefined reference to `sg_version_check' masterworker.c:209: undefined reference to `MSG_init_nocheck' diff --git a/docs/source/Tutorial_Algorithms.rst b/docs/source/Tutorial_Algorithms.rst index 424d2117e1..2f4b2023b6 100644 --- a/docs/source/Tutorial_Algorithms.rst +++ b/docs/source/Tutorial_Algorithms.rst @@ -308,10 +308,10 @@ The easiest way to take the tutorial is to use the dedicated Docker image. Once you `installed Docker itself `_, simply do the following: -.. code-block:: shell +.. code-block:: console - docker pull simgrid/tuto-s4u - docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/tutorial simgrid/tuto-s4u bash + $ docker pull simgrid/tuto-s4u + $ docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/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 @@ -334,12 +334,12 @@ 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:: shell +.. code-block:: console - cp -r /source/simgrid-template-s4u.git/* /source/tutorial - cd /source/tutorial - cmake . - make + $ cp -r /source/simgrid-template-s4u.git/* /source/tutorial + $ cd /source/tutorial + $ cmake . + $ make Using your Computer Natively ............................ @@ -351,21 +351,21 @@ a recent version of SimGrid `, a C++ compiler, and also The provided code template requires CMake to compile. On Debian and Ubuntu for example, you can get them as follows: -.. code-block:: shell +.. code-block:: console - sudo apt install simgrid pajeng cmake g++ vite + $ sudo apt install simgrid pajeng cmake g++ vite For R analysis of the produced traces, you may want to install R and the `pajengr `_ package. -.. code-block:: shell +.. code-block:: console # install R and necessary packages - sudo apt install r-base r-cran-devtools r-cran-tidyverse + $ sudo apt install r-base r-cran-devtools r-cran-tidyverse # install pajengr dependencies - sudo apt install git cmake flex bison + $ sudo apt install git cmake flex bison # install the pajengr R package - Rscript -e "library(devtools); install_github('schnorr/pajengr');" + $ Rscript -e "library(devtools); install_github('schnorr/pajengr');" An initial version of the source code is provided on framagit. This template compiles with CMake. If SimGrid is correctly installed, you @@ -373,15 +373,15 @@ should be able to clone the `repository `_ and recompile everything as follows: -.. code-block:: shell +.. code-block:: console # (exporting SimGrid_PATH is only needed if SimGrid is installed in a non-standard path) - export SimGrid_PATH=/where/to/simgrid + $ export SimGrid_PATH=/where/to/simgrid - git clone https://framagit.org/simgrid/simgrid-template-s4u.git - cd simgrid-template-s4u/ - cmake . - make + $ git clone https://framagit.org/simgrid/simgrid-template-s4u.git + $ cd simgrid-template-s4u/ + $ cmake . + $ make If you struggle with the compilation, then you should double-check your :ref:`SimGrid installation `. On need, please refer to @@ -393,16 +393,16 @@ Discovering the Provided Code Please compile and execute the provided simulator as follows: -.. code-block:: shell +.. code-block:: console - make master-workers - ./master-workers small_platform.xml master-workers_d.xml + $ make master-workers + $ ./master-workers small_platform.xml master-workers_d.xml For a more "fancy" output, you can use simgrid-colorizer. -.. code-block:: shell +.. code-block:: console - ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer + $ ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer If you installed SimGrid to a non-standard path, you may have to specify the full path to simgrid-colorizer on the above line, such as @@ -414,10 +414,10 @@ For a classical Gantt-Chart visualization, you can use `Vite 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 +.. code-block:: console - ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes - vite simgrid.trace + $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes + $ vite simgrid.trace .. image:: /tuto_s4u/img/vite-screenshot.png :align: center @@ -432,10 +432,10 @@ to use R. As a start, you can download this `starter script `_ and use it as follows: -.. code-block:: shell +.. code-block:: console - ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes - Rscript draw_gantt.R simgrid.trace + $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes + $ Rscript draw_gantt.R simgrid.trace It produces a ``Rplots.pdf`` with the following content: @@ -623,9 +623,9 @@ every 100 tasks and ``XBT_DEBUG`` when sending all the other tasks. Or you could show only the total number of tasks processed by default. You can still see the debug messages as follows: -.. code-block:: shell +.. code-block:: console - ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug + $ ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug Lab 4: Competing Applications diff --git a/docs/source/Tutorial_MPI_Applications.rst b/docs/source/Tutorial_MPI_Applications.rst index 04fe43a2e1..310389d561 100644 --- a/docs/source/Tutorial_MPI_Applications.rst +++ b/docs/source/Tutorial_MPI_Applications.rst @@ -265,10 +265,10 @@ The easiest way to take the tutorial is to use the dedicated Docker image. Once you `installed Docker itself `_, simply do the following: -.. code-block:: shell +.. code-block:: console - docker pull simgrid/tuto-smpi - docker run -it --rm --name simgrid --volume ~/smpi-tutorial:/source/tutorial simgrid/tuto-smpi bash + $ docker pull simgrid/tuto-smpi + $ docker run -it --rm --name simgrid --volume ~/smpi-tutorial:/source/tutorial simgrid/tuto-smpi bash This will start a new container with all you need to take this tutorial, and create a ``smpi-tutorial`` directory in your home on @@ -293,10 +293,10 @@ Benchmarks. These files are available under ``/source/simgrid-template-smpi`` in the image. You should copy it to your working directory when you first log in: -.. code-block:: shell +.. code-block:: console - cp -r /source/simgrid-template-smpi/* /source/tutorial - cd /source/tutorial + $ cp -r /source/simgrid-template-smpi/* /source/tutorial + $ cd /source/tutorial Using your Computer Natively ............................ @@ -308,31 +308,31 @@ visualize the traces. You may want to install `Vite traces. The provided code template requires ``make`` to compile. On Debian and Ubuntu, you can get them as follows: -.. code-block:: shell +.. code-block:: console - sudo apt install simgrid pajeng make gcc g++ gfortran python3 vite + $ sudo apt install simgrid pajeng make gcc g++ gfortran python3 vite For R analysis of the produced traces, you may want to install R and the `pajengr `_ package. -.. code-block:: shell +.. code-block:: console # install R and necessary packages - sudo apt install r-base r-cran-devtools r-cran-tidyverse + $ sudo apt install r-base r-cran-devtools r-cran-tidyverse # install pajengr dependencies - sudo apt install git cmake flex bison + $ sudo apt install git cmake flex bison # install the pajengr R package - Rscript -e "library(devtools); install_github('schnorr/pajengr');" + $ Rscript -e "library(devtools); install_github('schnorr/pajengr');" To take this tutorial, you will also need the platform files from the previous section as well as the source code of the NAS Parallel Benchmarks. Just clone `this repository `_ to get them all: -.. code-block:: shell +.. code-block:: console - git clone https://framagit.org/simgrid/simgrid-template-smpi.git - cd simgrid-template-smpi/ + $ git clone https://framagit.org/simgrid/simgrid-template-smpi.git + $ cd simgrid-template-smpi/ If you struggle with the compilation, then you should double-check your :ref:`SimGrid installation `. On need, please refer to @@ -357,7 +357,7 @@ Compiling the program is straightforward (double-check your :ref:`SimGrid installation ` if you get an error message): -.. code-block:: shell +.. code-block:: console $ smpicc -O3 roundtrip.c -o roundtrip @@ -365,7 +365,7 @@ Compiling the program is straightforward (double-check your Once compiled, you can simulate the execution of this program on 16 nodes from the ``cluster_crossbar.xml`` platform as follows: -.. code-block:: shell +.. code-block:: console $ smpirun -np 16 -platform cluster_crossbar.xml -hostfile cluster_hostfile ./roundtrip @@ -404,7 +404,7 @@ data size `_) with 4 nodes. -.. code-block:: shell +.. code-block:: console $ make lu NPROCS=4 CLASS=S (compilation logs) @@ -415,9 +415,9 @@ To get a better understanding of what is going on, activate the visualization tracing, and convert the produced trace for later use: -.. code-block:: shell +.. code-block:: console - smpirun -np 4 -platform ../cluster_backbone.xml -trace --cfg=tracing/filename:lu.S.4.trace bin/lu.S.4 + $ smpirun -np 4 -platform ../cluster_backbone.xml -trace --cfg=tracing/filename:lu.S.4.trace bin/lu.S.4 You can then produce a Gantt Chart with the following R chunk. You can either copy/paste it in an R session, or `turn it into a Rscript executable @@ -481,7 +481,7 @@ Lab 2: Tracing and Replay of LU Now compile and execute the LU benchmark, class A, with 32 nodes. -.. code-block:: shell +.. code-block:: console $ make lu NPROCS=32 CLASS=A @@ -496,7 +496,7 @@ skipped (the application must be network-dependent for this to work). You can even generate the trace during the live simulation as follows: -.. code-block:: shell +.. code-block:: console $ smpirun -trace-ti --cfg=tracing/filename:LU.A.32 -np 32 -platform ../cluster_backbone.xml bin/lu.A.32 @@ -504,7 +504,7 @@ The produced trace is composed of a file ``LU.A.32`` and a folder ``LU.A.32_files``. You can replay this trace with SMPI thanks to ``smpirun``. For example, the following command replays the trace on a different platform: -.. code-block:: shell +.. code-block:: console $ smpirun -np 32 -platform ../cluster_crossbar.xml -hostfile ../cluster_hostfile -replay LU.A.32 @@ -541,7 +541,7 @@ The computing part of this example is the matrix multiplication routine :language: cpp :lines: 9-24 -.. code-block:: shell +.. code-block:: console $ smpicxx -O3 gemm_mpi.cpp -o gemm $ time smpirun -np 16 -platform cluster_crossbar.xml -hostfile cluster_hostfile --cfg=smpi/display-timing:yes --cfg=smpi/running-power:1000000000 ./gemm @@ -560,7 +560,7 @@ running the simulation. Here we say that its speed is the same as one of the processors we are simulating (1Gf), so that 1 second of computation is injected as 1 second in the simulation. -.. code-block:: shell +.. code-block:: console [5.568556] [smpi_kernel/INFO] Simulated time: 5.56856 seconds. @@ -604,7 +604,7 @@ earlier if the expected stability is reached after fewer samples. Now run the code again with various sizes and parameters and check the time taken for the simulation, as well as the resulting simulated time. -.. code-block:: shell +.. code-block:: console [5.575691] [smpi_kernel/INFO] Simulated time: 5.57569 seconds. The simulation took 1.23698 seconds (after parsing and platform setup) @@ -638,7 +638,7 @@ Find it and replace the two other ones with ``SMPI_SHARED_MALLOC`` (there is onl Once done, you can now run -.. code-block:: shell +.. code-block:: console $ make dt NPROCS=85 CLASS=C (compilation logs) @@ -664,14 +664,14 @@ It will display at the end of a (successful) run the largest allocations and the targets for sharing, or setting the threshold for automatic ones. For DT, the process would be to run a smaller class of problems, -.. code-block:: shell +.. code-block:: console $ make dt NPROCS=21 CLASS=A $ smpirun --cfg=smpi/display-allocs:yes -np 21 -platform ../cluster_backbone.xml bin/dt.A.x BH Which should output: -.. code-block:: shell +.. code-block:: console [smpi_utils/INFO] Memory Usage: Simulated application allocated 198533192 bytes during its lifetime through malloc/calloc calls. Largest allocation at once from a single process was 3553184 bytes, at dt.c:388. It was called 3 times during the whole simulation. diff --git a/docs/source/Tutorial_Model-checking.rst b/docs/source/Tutorial_Model-checking.rst index 6899c5e47c..8bfbb3e525 100644 --- a/docs/source/Tutorial_Model-checking.rst +++ b/docs/source/Tutorial_Model-checking.rst @@ -48,11 +48,11 @@ your machine: it works out of the box on Linux, Windows (with WSL2) and FreeBSD. -Denable_model-checking .``) and then compile SimGrid :ref:`as usual `. Unfortunately, Mc SimGrid does not work natively on Mac OS X yet, so mac users should stick to the docker method for now. -.. code-block:: shell +.. code-block:: console - docker image pull simgrid/tuto-mc - mkdir ~/tuto-mcsimgrid # or chose another directory to share between your computer and the docker container - docker run -it --rm --name mcsimgrid --volume ~/tuto-mcsimgrid:/source/tutorial simgrid/tuto-mc bash + $ docker image pull simgrid/tuto-mc + $ mkdir ~/tuto-mcsimgrid # or chose another directory to share between your computer and the docker container + $ docker run -it --rm --name mcsimgrid --volume ~/tuto-mcsimgrid:/source/tutorial simgrid/tuto-mc bash In the container, you have access to the following directories of interest: @@ -72,7 +72,7 @@ Motivational example Let's go with a first example of a bugged program. Once in the container, copy all files from the tutorial into the directory shared between your host computer and the container. -.. code-block:: shell +.. code-block:: console # From within the container $ cp -r /source/tuto-mc.git/* /source/tutorial/ @@ -95,7 +95,7 @@ The provided code is rather simple: Three ``client`` are launched with an intege send their parameter to a given mailbox. A ``server`` receives 3 messages and assumes that the last received message is the number ``3``. If you compile and run it, it simply works: -.. code-block:: shell +.. code-block:: console $ cmake . && make (output omitted) @@ -116,7 +116,7 @@ the message ``3`` to arrive last. Depending on the link speed, any order should source code and/or the platform file, but this is not a method. Time to start Mc SimGrid, the SimGrid model checker, to exhaustively test all message orders. For that, you simply launch your simulation as a parameter to the ``simgrid-mc`` binary as you would do with ``valgrind``: -.. code-block:: shell +.. code-block:: console $ simgrid-mc ./ndet-receive-s4u small_platform.xml (some output ignored) @@ -135,7 +135,7 @@ now read it together. It can be split in several parts: all possible outcome of the code, the execution is sometimes rewind to explore another possible branch (here: another possible message ordering). Note also that all times are always 0 in the model checker, since the time is abstracted away in this mode. - .. code-block:: shell + .. code-block:: console [0.000000] [mc_safety/INFO] Check a safety property. Reduction is: dpor. [Jupiter:client:(2) 0.000000] [example/INFO] Sending 1 @@ -158,7 +158,7 @@ now read it together. It can be split in several parts: - Then you have the error message, along with a backtrace of the application at the point where the assertion fails. Not all the frames of the backtrace are useful, and some are omitted here. - .. code-block:: shell + .. code-block:: console [Tremblay:server:(1) 0.000000] /source/tutorial/ndet-receive-s4u.cpp:27: [root/CRITICAL] Assertion value_got == 3 failed Backtrace (displayed in actor server): @@ -170,7 +170,7 @@ now read it together. It can be split in several parts: - First, the error message itself. The ``xbt_assert`` in the code result in an ``abort()`` in the application, that is interpreted as an application crash by the model-checker. - .. code-block:: shell + .. code-block:: console [0.000000] [mc_ModelChecker/INFO] ************************** [0.000000] [mc_ModelChecker/INFO] ** CRASH IN THE PROGRAM ** @@ -182,7 +182,7 @@ now read it together. It can be split in several parts: calls we made (put/get) are split in atomic calls (iSend+Wait/iRecv+Wait), and all executions are interleaved. Also, Mc SimGrid reports the first faulty execution it finds: it may not be the shorter possible one. - .. code-block:: shell + .. code-block:: console [0.000000] [mc_ModelChecker/INFO] Counter-example execution trace: [0.000000] [mc_ModelChecker/INFO] [(1)Tremblay (server)] iRecv(dst=(1)Tremblay (server), buff=(verbose only), size=(verbose only)) @@ -198,7 +198,7 @@ now read it together. It can be split in several parts: - Then, the execution path is given. - .. code-block:: shell + .. code-block:: console [0.000000] [mc_record/INFO] Path = 1;2;1;1;2;4;1;1;3;1 @@ -206,7 +206,7 @@ now read it together. It can be split in several parts: without ``simgrid-mc``. This is because ``simgrid-mc`` forbids to use a debugger such as gdb or valgrind on the code during the model-checking. For example, you can trigger the same execution in valgrind as follows: - .. code-block:: shell + .. code-block:: console $ valgrind ./ndet-receive-s4u small_platform.xml --cfg=model-check/replay:'1;2;1;1;2;4;1;1;3;1' ==402== Memcheck, a memory error detector @@ -233,7 +233,7 @@ now read it together. It can be split in several parts: point of the exploration), the visited states (the amount of times we visited another state -- the same state may have been visited several times) and the amount of transitions. - .. code-block:: shell + .. code-block:: console [0.000000] [mc_safety/INFO] Expanded states = 22 [0.000000] [mc_safety/INFO] Visited states = 56 @@ -257,7 +257,7 @@ translation of ``ndet-receive-s4u.cpp`` to MPI. |br| You can compile and run it on top of SimGrid as follows. -.. code-block:: shell +.. code-block:: console $ smpicc ndet-receive-mpi.c -o ndet-receive-mpi $ smpirun -np 4 -platform small_platform.xml ndet-receive-mpi @@ -266,14 +266,14 @@ Interestingly enough, the bug is triggered on my machine even without Mc SimGrid leading to it. It may not be the case on your machine, as this depends on the iteration order of an unsorted collection. Instead, we should use Mc SimGrid to exhaustively explore the state space and trigger the bug in all cases. -.. code-block:: shell +.. code-block:: console $ smpirun -wrapper simgrid-mc -np 4 -platform small_platform.xml ndet-receive-mpi The produced output is then very similar to the one you get with S4U, even if the exact execution path leading to the bug may differs. You can also trigger a given execution path out of the model-checker, for example to explore it with valgrind. -.. code-block:: shell +.. code-block:: console $ smpirun -wrapper valgrind -np 4 -platform small_platform.xml --cfg=model-check/replay:'1;2;1;1;4;1;1;3;1' ndet-receive-mpi diff --git a/docs/source/app_msg.rst b/docs/source/app_msg.rst index 973bb16dbd..e3b0160552 100644 --- a/docs/source/app_msg.rst +++ b/docs/source/app_msg.rst @@ -280,14 +280,14 @@ Using the Java bindings In most cases, you can use the SimGrid bindings as if it was a Java library: -.. code-block:: shell +.. code-block:: console $ javac -classpath .:path/to/simgrid.jar your/java/Code.java $ java -classpath .:path/to/simgrid.jar your.java.Code the/parameter/to/your/code For example: -.. code-block:: shell +.. code-block:: console $ cd examples/deprecated/java $ java -classpath ../../simgrid.jar:. .:../../simgrid.jar app.pingpong.Main ../platforms/platform.xml diff --git a/docs/source/app_smpi.rst b/docs/source/app_smpi.rst index 513bfa1be7..a62509fd42 100644 --- a/docs/source/app_smpi.rst +++ b/docs/source/app_smpi.rst @@ -74,9 +74,9 @@ If you use cmake, set the variables ``MPI_C_COMPILER``, ``MPI_CXX_COMPILER`` and ``MPI_Fortran_COMPILER`` to the full path of smpicc, smpicxx and smpiff (or smpif90), respectively. Example: -.. code-block:: shell +.. code-block:: console - cmake -DMPI_C_COMPILER=/opt/simgrid/bin/smpicc -DMPI_CXX_COMPILER=/opt/simgrid/bin/smpicxx -DMPI_Fortran_COMPILER=/opt/simgrid/bin/smpiff . + $ cmake -DMPI_C_COMPILER=/opt/simgrid/bin/smpicc -DMPI_CXX_COMPILER=/opt/simgrid/bin/smpicxx -DMPI_Fortran_COMPILER=/opt/simgrid/bin/smpiff . .................... Simulating your Code @@ -84,9 +84,9 @@ Simulating your Code Use the ``smpirun`` script as follows: -.. code-block:: shell +.. code-block:: console - smpirun -hostfile my_hostfile.txt -platform my_platform.xml ./program -blah + $ smpirun -hostfile my_hostfile.txt -platform my_platform.xml ./program -blah - ``my_hostfile.txt`` is a classical MPI hostfile (that is, this file lists the machines on which the processes must be dispatched, one @@ -120,10 +120,10 @@ following commands. Once in GDB, each MPI ranks will be represented as a regular thread, and you can explore the state of each of them as usual. -.. code-block:: shell +.. code-block:: console - smpirun -wrapper valgrind ...other args... - smpirun -wrapper "gdb --args" --cfg=contexts/factory:thread ...other args... + $ smpirun -wrapper valgrind ...other args... + $ smpirun -wrapper "gdb --args" --cfg=contexts/factory:thread ...other args... Some shortcuts are available: @@ -783,10 +783,10 @@ functional or that you are cross-compiling, try to define the ``SMPI_PRETEND_CC`` environment variable before running the configuration. -.. code-block:: shell +.. code-block:: console - SMPI_PRETEND_CC=1 ./configure # here come the configure parameters - make + $ SMPI_PRETEND_CC=1 ./configure # here come the configure parameters + $ make Indeed, the programs compiled with ``smpicc`` cannot be executed without ``smpirun`` (they are shared libraries and do weird things on @@ -808,10 +808,10 @@ fail without ``smpirun``. In addition to the previous answers, some projects also need to be explicitly told what compiler to use, as follows: -.. code-block:: shell +.. code-block:: console - SMPI_PRETEND_CC=1 ./configure CC=smpicc # here come the other configure parameters - make + $ SMPI_PRETEND_CC=1 ./configure CC=smpicc # here come the other configure parameters + $ make Maybe your configure is using another variable, such as ``cc`` (in lower case) or similar. Just check the logs. @@ -847,7 +847,7 @@ SimGrid uses time-independent traces, in which each actor is given a script of the actions to do sequentially. These trace files can actually be captured with the online version of SMPI, as follows: -.. code-block:: shell +.. code-block:: console $ smpirun -trace-ti --cfg=tracing/filename:LU.A.32 -np 32 -platform ../cluster_backbone.xml bin/lu.A.32 @@ -860,12 +860,14 @@ To replay this with SMPI, you need to first compile the provided `simgrid/examples/smpi/replay `_. -.. code-block:: shell +.. code-block:: console $ smpicxx ../replay.cpp -O3 -o ../smpi_replay Afterward, you can replay your trace in SMPI as follows: +.. code-block:: console + $ smpirun -np 32 -platform ../cluster_torus.xml -ext smpi_replay ../smpi_replay LU.A.32 All the outputs are gone, as the application is not really simulated -- 2.20.1