Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
doc: Migrate Deploying_your_Application to RST
authorMartin Quinson <martin.quinson@ens-rennes.fr>
Tue, 2 Jul 2019 21:50:21 +0000 (23:50 +0200)
committerMartin Quinson <martin.quinson@ens-rennes.fr>
Wed, 3 Jul 2019 12:59:30 +0000 (14:59 +0200)
ChangeLog
doc/doxygen/deployment.doc [deleted file]
docs/source/Deploying_your_Application.rst [new file with mode: 0644]
docs/source/XML_Reference.rst
docs/source/img/graphical-toc.svg
docs/source/index.rst
examples/s4u/README.rst
tools/cmake/DefinePackages.cmake

index 7659918..a92e66e 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -4,6 +4,7 @@ SimGrid (3.23.1) NOT RELEASED YET (v3.24 expected September 23. 7:50 UTC)
 
 Documentation:
  - Nicer introduction page.
+ - Migrate the "Deploy your application" page to the new doc.
  - Move Java as a subtree of MSG.
 
 General:
diff --git a/doc/doxygen/deployment.doc b/doc/doxygen/deployment.doc
deleted file mode 100644 (file)
index beee64f..0000000
+++ /dev/null
@@ -1,135 +0,0 @@
-/*! @page deployment Deploy the simulation
-
-@tableofcontents
-
-\htmlonly
-<div align="center">
-\endhtmlonly
-\htmlinclude graphical-toc.svg
-\htmlonly
-</div>
-<script>
-document.getElementById("Deployment").style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
-</script>
-\endhtmlonly
-
-Once you've specified your @ref platform "virtual platform" and the
-@ref application "application" you want to study, you must describe
-the mapping of the application onto the platform. This page says how
-to do that if you go for online simulation (that is, the study of a
-program), you must say which code starts on which host, with which
-parameters. You can also go for offline simulation, i.e. the study of
-a trace captured from a past applicative run, as briefly explained
-@ref XBT_replay "here".
-
-There is two ways to specify the mapping of your program onto virtual
-hosts: either directly from your program (with @ref MSG_process_create
-or as in @ref s4u_ex_actors_start "this S4U example"), or using an external
-XML file.  You should really logically separate your application from
-the deployment, as it will ease your experimental campain afterward.
-How exactly you organize your work remains up to you.
-
-@section deploy_s4u Deployment with S4U
-
-The following example shows the several ways of doing so in the S4U
-interface: @ref examples/s4u/actor-create/s4u-actor-create.cpp.
-Associated XML file: @ref examples/s4u/actor-create/s4u-actor-create_d.xml
-
-@section deploy_msg Deployment with MSG
-
-If you're stuck with the MSG interface, then you should simply use one
-of the following functions to start new actors onto your virtual
-hosts: @ref MSG_process_create, @ref MSG_process_create_with_arguments
-or @ref MSG_process_create_with_environment. These functions are used
-in many of the provided example, just grep for them.
-
-@section deploy_xml Deployment with XML
-
-Deploying actors from XML is easy. This section presents a complete
-example and the reference guide of the involved tags.
-
-The deployment file looks just like a @ref platform "platform" file,
-with only 3 tags used:
-
-  - @c &lt;actor&gt; starts a new actor on a given host;
-  - @c &lt;argument&gt; passes a given argument in the argv of an actor
-    (the list of arguments is ordered);
-  - @c &lt;prop&gt; adds a property to the actor.
-
-@subsection deploy_xml_ex Examples
-
-To make them easy to find, almost all deployment files in the archive
-are named @c ***_d_xml.
-
-@verbatim
-<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
-<platform version="4">
-  <!-- Alice, which runs on the machine named 'host1', does not take any parameter -->
-  <actor host="host1" function="alice" />
-
-  <!-- Bob, which runs on 'host2', has 2 parameters "3" and "3000" in its argv -->
-  <actor host="host2" function="bob" />
-     <argument value="3"/>
-     <argument value="3000"/>
-  </actor>
-
-  <!-- Carole runs on 'host3', has 1 parameter "42" in its argv and one property -->
-  <!-- See MSG_process_get_property_value() to retrieve this property -->
-  <actor host="host3" function="carole">
-      <argument value="42"/>
-      <prop id="SomeProp" value="SomeValue"/>
-  </actor>
-</platform>
-@endverbatim
-
-@subsection deploy_xml_actor The actor tag
-
-&lt;actor&gt; starts a new actor on a given host. It specifies which
-function (from your application) gets executed on the host. Hence, the
-@c host and @c function attributes are mandatory, but this tag accepts
-some optional attributes too.
-
-| Attribute name  | Mandatory | Values       | Description                                                                     |
-| --------------- | --------- | ------------ | -----------                                                                     |
-| host            | yes       | String       | This must match the name of an host defined in the platform file.               |
-| function        | yes       | String       | Name of the function (from your own code) that will be executed.  See @ref deploy_xml_functions. |
-| start_time      | no        | int          | The simulated time when this actor will be started (Default: ASAP).             |
-| kill_time       | no        | int          | The simulated time when this actor will be forcefully stopped (Default: never). |
-| on_failure      | no        | DIE\|RESTART | What should be done when the actor fails (Default: die).       |
-
-@subsection deploy_xml_argument The argument tag
-
-This tag (which must be enclosed in a @c &lt;actor&gt; tag) adds a
-new string to the parameter list received by your actor (either its @c
-argv array in MSG or its @c args vector in S4U).  Naturally, the
-semantic of these parameters completely depend on your program.
-
-| Attribute name  | Mandatory | Values                 | Description             |
-| --------------- | --------- | ---------------------- | -----------             |
-| value           | yes       | String                 | Value of this parameter |
-
-@subsection deploy_xml_prop The prop tag
-
-This tag (which must be enclosed in a @c &lt;actor&gt; tag) adds a new
-property to your actor. You can retrieve these properties with
-MSG_process_get_property_value() or simgrid::s4u::Actor::property().
-Naturally, the semantic of these parameters completely depend on your
-program.
-
-| Attribute name  | Mandatory | Values                 | Description                  |
-| --------------- | --------- | ---------------------- | -----------                  |
-| id              | yes       | String                 | Name of the defined property |
-| value           | yes       | String                 | Value of this property       |
-
-@subsection deploy_xml_functions Declaring startable functions
-
-You need to connect your code to the names that you use in the XML
-deployment file. Depending on the interface you use, this is done with
-MSG_process_create() or simgrid::s4u::Engine::registerFunction().
-There is nothing to do in your **Java code** since SimGrid uses
-the Java introspection abilities to retrieve the classes from their
-names. In your XML file, you must then use the full class name
-(including the package name).
-
-*/
diff --git a/docs/source/Deploying_your_Application.rst b/docs/source/Deploying_your_Application.rst
new file mode 100644 (file)
index 0000000..525d7e3
--- /dev/null
@@ -0,0 +1,115 @@
+.. _deploy:
+
+Deploying your Application
+==========================
+
+.. raw:: html
+
+   <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
+   <script>
+   window.onload=function() { // Wait for the SVG to be loaded before changing it
+     var elem=document.querySelector("#TOC").contentDocument.getElementById("DeployBox")
+     elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
+   }
+   </script>
+   <br/>
+   <br/>
+
+There is several ways to deploy the :ref:`application <application>` you want to
+study on your :ref:`simulated platform <platform>`, i.e. to specify which actor
+should be started on which host. You can do so directly in your program (as
+shown in :ref:`these examples <s4u_ex_actors>`), or using an XML deployment
+file. Unless you have a good reason, you should keep your application appart
+from the deployment as it will :ref:`ease your experimental campain afterward
+<howto_science>`.
+
+Deploying actors from XML is easy: it only involves 3 tags: :ref:`pf_tag_actor`,
+:ref:`pf_tag_argument`, and :ref:`pf_tag_prop`. They must be placed in an
+encompassing :ref:`pf_tag_platform`. Here is a first example (search in the
+archive for files named ``???_d.xml`` for more):
+
+.. code-block:: xml
+
+   <?xml version='1.0'?>
+   <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
+   <platform version="4.1">
+     <!-- The following starts an actor that runs the function `alice` on the given host.
+       -- It is not given any parameter.
+       -->
+     <actor host="host1" function="alice" />
+
+     <!-- The following starts another actor that runs `bob()` on host2.
+       -- The argv of this actor contains "3" and "3000" on creation.
+       -->
+     <actor host="host2" function="bob" />
+       <argument value="3"/>
+       <argument value="3000"/>
+     </actor>
+
+     <!-- Carole runs on 'host3', has 1 parameter "42" in its argv and one property -->
+     <actor host="host3" function="carol">
+       <argument value="42"/>
+       <prop id="SomeProp" value="SomeValue"/>
+     </actor>
+   </platform>
+
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_actor:
+
+<actor>
+--------
+
+This tag starts a new actor executing the given function on a given host. 
+
+
+**Parent tags:** :ref:`pf_tag_platform` (only in deployment files) |br|
+**Children tags:** :ref:`pf_tag_argument`, :ref:`pf_tag_prop` |br|
+**Attributes:**
+
+:``host``: Host on which this actor should be started (mandatory).
+:``function``: Code to execute.
+
+   That function must be registered beforehand
+   with :cpp:func:`simgrid::s4u::Engine::register_actor` or
+   with :cpp:func:`simgrid::s4u::Engine::register_function`.
+
+   If you are stuck with MSG, use :cpp:func:`MSG_process_create`,
+   :cpp:func:`MSG_process_create_with_arguments` or
+   :cpp:func:`MSG_process_create_with_environment`.
+
+   There is nothing to do in Java, as SimGrid uses introspection abilities to
+   retrieve the classes from their names. You must then use the full class name
+   (including the package name) in your XML file.
+
+:``start_time``: Useful to delay the start of your actor.
+
+        -1 starts the actor immediately.
+:``kill_time``:  Time at which the actor should be killed.
+
+   -1 means that the actor should not be killed automatically.
+:``on_failure``: What to do when the actor's host is turned off and back on.
+
+   Either ``DIE`` (default -- don't restart the actor) or ``RESTART``
+
+-------------------------------------------------------------------------------
+
+.. _pf_tag_argument:
+
+<argument>
+----------
+
+Add a parameter to the actor, to its args vector. Naturally, the semantic of
+these parameters completely depend on your program.
+
+
+**Parent tags:** :ref:`pf_tag_actor`  |br|
+**Children tags:** none |br|
+**Attributes:**
+
+:``value``: The string to add to the actor's args vector.
+
+.. |br| raw:: html
+
+   <br />
index 87a7181..6949319 100644 (file)
@@ -267,6 +267,7 @@ and a download link.
 
 :``id``: Name of the host. Must be unique on the whole platform.
 :``speed``: Computational power (in flop/s).
+
    If you use DVFS, provide a comma-separated list of values for each pstate (see :ref:`howto_dvfs`). 
 :``bw_in``: Bandwidth of the private downstream link, along with its
            unit. See :ref:`pf_tag_link`.
@@ -298,7 +299,8 @@ and a download link.
 **Parent tags:** none (this is the root tag of every file) |br|
 **Children tags:** :ref:`pf_tag_config` (must come first),
 :ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
-:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
+:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect`, or
+:ref:`pf_tag_actor` in :ref:`deployment <Deploying_your_Applications>` files.|br|
 **Attributes:**
 
 :``version``: Version of the DTD, describing the whole XML format.
index eead0aa..83d6fe7 100644 (file)
@@ -25,8 +25,8 @@
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
      inkscape:zoom="2.8"
-     inkscape:cx="205.77445"
-     inkscape:cy="161.83279"
+     inkscape:cx="24.34588"
+     inkscape:cy="160.40421"
      inkscape:document-units="mm"
      inkscape:current-layer="layer1"
      showgrid="true"
         <dc:format>image/svg+xml</dc:format>
         <dc:type
            rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-        <dc:title></dc:title>
+        <dc:title />
       </cc:Work>
     </rdf:RDF>
   </metadata>
            id="tspan2827" /></text>
     </a>
     <a
-       xlink:href="deployment.html"
+       xlink:href="Deploying_your_Application.html"
        inkscape:label="DeployLink"
        transform="translate(-2.8431311e-6,13.229176)"
        id="a6179">
       <text
          xml:space="preserve"
          style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;line-height:6.61458302px;font-family:'Amiri Quran Colored';-inkscape-font-specification:'Amiri Quran Colored';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-         x="66.196823"
+         x="69.626068"
          y="73.481842"
          id="ProfileText-7-62"
          inkscape:label="MPI Text"><tspan
            sodipodi:role="line"
            id="tspan1034-5-6"
-           x="66.196823"
+           x="69.626068"
            y="73.481842"
-           style="font-size:4.93888903px;stroke-width:0.26458332px">MPI Legacy Code</tspan><tspan
+           style="font-size:4.93888903px;stroke-width:0.26458332px">Real MPI Code</tspan><tspan
            sodipodi:role="line"
-           x="66.196823"
+           x="69.626068"
            y="80.096428"
            style="font-size:4.93888903px;stroke-width:0.26458332px"
            id="tspan2316-1" /></text>
index 91da4d3..023bb91 100644 (file)
@@ -79,6 +79,7 @@ of every page. Bugs in the code should be reported
          XML Reference <XML_Reference.rst>
       Describing the Experimental Setup <Experimental_Setup.rst>
          Configuring SimGrid <Configuring_SimGrid.rst>
+         Deploying your Application <Deploying_your_Application.rst>
       The SimGrid Models <models.rst>
          ns-3 as a SimGrid model <ns3.rst>
       Simulation Outcomes <outcomes.rst>
index f11fc88..e332ab6 100644 (file)
@@ -31,6 +31,7 @@ to simulate.
 Actors: the Active Entities
 ===========================
 
+.. _s4u_ex_actors:
 
 Starting and Stoping Actors
 ---------------------------
index bbffae4..903bafc 100644 (file)
@@ -836,7 +836,6 @@ set(DOC_SOURCES
   doc/Layout.xml
 
   doc/doxygen/FAQ.doc
-  doc/doxygen/deployment.doc
   doc/doxygen/inside.doc
   doc/doxygen/inside_tests.doc
   doc/doxygen/inside_cmake.doc
@@ -895,6 +894,7 @@ set(DOC_SOURCES
   docs/source/app_smpi.rst
   docs/source/community.rst
   docs/source/Configuring_SimGrid.rst
+  doc/doxygen/Deploying_your_Application.rst
   docs/source/Experimental_Setup.rst
   docs/source/index.rst
   docs/source/Introduction.rst