X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/2e9f637ec9c59777b768b16d44048673092abaca..7231545543fa5be730a575fb278656247717e865:/doc/module-gras.doc

diff --git a/doc/module-gras.doc b/doc/module-gras.doc
index 886da4737c..c91622e8a0 100644
--- a/doc/module-gras.doc
+++ b/doc/module-gras.doc
@@ -3,8 +3,20 @@
 #####################################################################
 
 /** \addtogroup GRAS_API
-  
-    \section GRAS_funct Offered functionnalities
+
+\htmlonly
+<div class="toc">
+<div class="tocTitle">Table of content</div>
+<ol type="1">
+<li> <a href="#GRAS_funct">API documentation</a>
+<li> <a href="#GRAS_example">Examples</a>
+<li> <a href="#GRAS_tut_presentation">Tutorial</a>
+<li> <a href="#GRAS_howto_presentation">HOWTOs</a>
+</div>
+\endhtmlonly
+
+    \section GRAS_funct API documentation
+     GRAS offers the following functionnalities
      - <b>\ref GRAS_comm</b>: Exchanging messages between peers
        - \ref GRAS_dd : any data which may transit on the network must be
          described beforehand so that GRAS can handle the platform
@@ -30,19 +42,7 @@
 	 This is how to let GRAS handle your globals properly.
        - \ref GRAS_emul : Support to emulate code excution (ie, reporting
          execution time into the simulator and having code sections specific
-         to simulation or to real mode).
-     - <b>\ref GRAS_code</b>: Here are some tools which may help
-          you setting up a GRAS project.\n
-          Setting up and building a GRAS application is complicated by the
-	  library schizoid. The code to setup the environment differs
-	  depending on whether you run on the simulator on a real platform.
-          And then, you'll have to deal with the usual distributed
-          application development difficulties.
-       - \ref GRAS_main_generation : Since processes are threads in
-          simulation mode and regular processes in the real world, GRAS does
-          generate your main functions for you.
-       - \ref GRAS_compile
-     
+         to simulation or to real mode).     
 	  
     \section GRAS_example Examples
       
@@ -53,12 +53,53 @@
        - \ref GRAS_ex_mmrpc
        - \ref GRAS_ex_token
        - \ref GRAS_ex_timer
+      
+     The initiatic tour of the tutorial also contains several examples. The
+     most proeminent one is:
+      
+       - \ref GRAS_tut_tour_explicitwait_use
+       
+    \section GRAS_tut_presentation Tutorial
+    
+    We even have a tutorial for the GRAS framework. It details in a
+    hopefully pedagogic order all the points of the API, along with example
+    of use for each of them. Unfortunately, it is not finished yet (the main
+    part missing is the one on how to describe data). Here is the table of
+    content:
+    
+       - \ref GRAS_tut_intro
+         - \ref GRAS_tut_intro_what
+         - \ref GRAS_tut_intro_model
+       - \ref GRAS_tut_tour
+         - \ref GRAS_tut_tour_install
+         - \ref GRAS_tut_tour_setup
+         - \ref GRAS_tut_tour_simpleexchange
+	 - \ref GRAS_tut_tour_args
+	 - \ref GRAS_tut_tour_callbacks
+	 - \ref GRAS_tut_tour_globals
+	 - \ref GRAS_tut_tour_logs
+	 - \ref GRAS_tut_tour_timers
+	 - \ref GRAS_tut_tour_exceptions
+	 - \ref GRAS_tut_tour_rpc
+	 - \ref GRAS_tut_tour_explicitwait
+	 - \ref GRAS_tut_tour_message_recaping
+
+    \section GRAS_howto_presentation HOWTOs
+    
+    The tutorial and the API documentation present the framework little
+    piece by little piece and provide a lot of information on each of them.
+    Quite orthogonally to this, the HOWTOs try to present transversal
+    aspects of the framework to give you some broader point of view on it.
+    How infortunate it is that only one such HOWTO exist for now...
+
+       - \ref GRAS_howto
+         - \ref GRAS_howto_design
 
     @{ */
        /** @defgroup GRAS_comm    Communication facilities */
        /** @defgroup GRAS_run     Virtualization */
-       /** @defgroup GRAS_code    Project and code management */
        /** @defgroup GRAS_ex      Examples */
+       /** @defgroup GRAS_tut     GRAS Tutorial */
 /** @} */
 #####################################################################
 /** @addtogroup GRAS_comm
@@ -94,22 +135,6 @@
 
 /** @} */
 
-#####################################################################
-/** @addtogroup GRAS_code
-
-    Here is how to setup your code when you want to use GRAS. You will also
-    learn how to get the most repetitive parts of your code generated
-    automatically.
-
-    (use the tabs on top of the page to navigate)
-
-    \htmlonly <!-- 
-      DOXYGEN_NAVBAR_LABEL="Project management"
-      DOXYGEN_NAVBAR_CHILD "main() and GRAS"=GRAS_main_generation.html
-      DOXYGEN_NAVBAR_CHILD "Compiling your GRAS project"=GRAS_compile.html
-    --> \endhtmlonly
-*/
-
 #####################################################################
 /** @addtogroup GRAS_ex
 
@@ -121,6 +146,11 @@
        - \ref GRAS_ex_token
        - \ref GRAS_ex_timer
 
+     The initiatic tour of the tutorial also contains several examples. The
+     most proeminent one is:
+      
+       - \ref GRAS_tut_tour_explicitwait_use
+       
     \htmlonly <!-- 
       DOXYGEN_NAVBAR_CHILD "Ping-Pong"=GRAS_ex_ping.html
       DOXYGEN_NAVBAR_CHILD "RPC"=GRAS_ex_mmrpc.html
@@ -132,178 +162,6 @@
   <tt>examples/gras</tt>.
 */
 
-#####################################################################
-#########################  EXTRA PAGES ##############################
-#####################################################################
-
----------------------------------------------------------------------
---------------------- main() generation -----------------------------
----------------------------------------------------------------------
-
-/** \page GRAS_main_generation main function
-
-    \section GRAS_maingen_toc Table of content
-     
-     - \ref GRAS_maingen_intro
-     - \ref GRAS_maingen_script
-     - \ref GRAS_maingen_make
-    
-    <hr>
-
-    \section GRAS_maingen_intro What's the matter with main() functions in GRAS?
-
-    In simulation mode, all processes are run as thread of the same process
-    while they are real processes in the real life. Unfortunately, the main
-    function of a real process must be called <tt>main</tt> while this
-    function must not use this name for threads.
-    
-    To deal with this, you should call the main function of your processes
-    with another name (usually, the process function such as client, server,
-    or such). Then GRAS can generate the wrapper functions adapted to the
-    real and simulated modes.
-
-    \section GRAS_maingen_script Generating the main()s automatically
-    
-    This is done by the gras_stub_generator program, which gets installed on
-    <tt>make install</tt> (the source resides in the tools/gras/ directory).
-    Here is the calling syntax: 
-    \verbatim gras_stub_generator <project_name> <deployment_file.xml>\endverbatim
-    
-    It parses the deployment file, searching for all the kind of processes
-    you have in your project. It then generates the following C files:
-     - a <tt>_<project_name>_<process_kind>.c</tt> file for each process kind you
-       have\n
-       They are used to launch your project in real life. They
-       contain a main() in charge of initializing the GRAS infrastructure and
-       launching your code afterward.
-     - a <tt>_<project_name>_simulator.c</tt> file.\n
-       This file is suited to the simulation mode. It contains a main()
-       function initializing the simulator and launching your project within.
-    
-    For this to work, the name of process described in your deployment file
-    should match the name of a function in your code, which prototype is for
-    example: \verbatim int client(int argc,char *argv[]);\endverbatim
-    
-    Unfortunately, all this is still partially documented. I guess I ought
-    to improve this situation somehow. In the meanwhile, check the generated 
-    code and maybe also the GRAS \ref GRAS_example, sorry. 
-        
-    \section GRAS_maingen_make Integration within an hand-made Makefile 
-    
-    The easiest to set it up is to add the following chunk at the end of
-    your Makefile (or Makefile.am), putting the right values into NAME and
-    PROCESSES.
-\verbatim NAME=your_project_name
- PROCESSES=list of processes type in your project
-
- $(foreach proc, $(PROCESSES), _$(NAME)_$(proc).c) _$(NAME)_simulator.c: $(NAME).c $(NAME)_deployment.xml
-        path/to/gras_stub_generator $(NAME) $(NAME)_deployment.xml >/dev/null
-\endverbatim
-
-    Of course, your personal millage may vary. For the \ref GRAS_ex_ping, may read:
-\verbatim _ping_client.c _ping_server.c _ping_simulator.c: ping.c ping_deployment.xml 
-        $(top_srcdir)/tools/gras/gras_stub_generator ping ping_deployment.xml >/dev/null
-\endverbatim
-
-   \warning 
-   Actually, gras_stub_generator also generates some makefiles both for
-   local compilation and remote code distribution and installation. See the
-   section \ref GRAS_compile for more details.
-
-*/
-
----------------------------------------------------------------------
-------------------------- Compiling ---------------------------------
----------------------------------------------------------------------
-
-/** \page GRAS_compile Compiling your project
-
-    As explained in section \ref GRAS_main_generation, the
-    gras_stub_generator tool can be used to generate the system
-    initialization code in your projet. While we were at this, this tool
-    also generates the makefiles you will need to compile your project
-    properly.
-    
-    Code source deployment and remote compilation also constitutes a
-    challenging area in distributed applications development. The GRASPE
-    (GRAS Platform Expender) tool was designed to make this less painful.
-
-    \section GRAS_compile_toc Table of content
-    
-      - \ref GRAS_compile_local
-        - \ref GRAS_compile_local_install
-	- \ref GRAS_compile_local_helpfiles
-	- \ref GRAS_compile_local_makefile
-      - \ref GRAS_compile_remote
-      
-    <hr>
-    
-    \section GRAS_compile_local Local compilation of GRAS projects
-    
-    \subsection GRAS_compile_local_install Installing SimGrid and GRAS
-    
-    To compile locally a GRAS project, you first need to install SimGrid on
-    your machine. Use the --prefix flag to the configure script to specify
-    where you want to install the toolkit (refere to section \ref
-    faq_compiling for more information)
-    
-    \subsection GRAS_compile_local_helpfiles Simulation description files
-    
-    Then, you will probably need to write a platform description file and
-    application deployment description file to feed the simulator with. This
-    part is unfortunatelly not documented enough. Files examples can be
-    found along with the MSG \ref MSG_ex_master_slave example. 
-
-    \note yes, both platform and application description files are portable
-    between MSG and GRAS. Actually, there depend on the SURF, not on the
-    programming environment you use.
-    
-    For the first try, you could probably reuse the provided platform file
-    as is while you will need to adapt the application file to fit your
-    needs. 
-    
-    To generate new platform files, we usually use the Tiers Topology
-    Generator (ask google about it) and annotate the generated graph with
-    home-made scripts to let them fit the SURF. Those scripts live in the
-    tools/platform_generation/ directory of the distribution.
-    
-    \subsection GRAS_compile_local_makefile Generating a Makefile usable for your project
-    
-    From the information contained in the application description file, the
-    gras_stub_generator tool can create a Makefile which can be used to
-    seamlessly compile your project. Just go to the directory containing all
-    your project files, and type:
-    
-\verbatim path/to/gras_stub_generator [project_name] [application_deployment.file] >/dev/null
-\endverbatim
-
-    The first argument is the name of your project, such as
-    "MyLovelyApplication" while the second one is the application deployment
-    file. 
-    
-    Several files get generated by this command. One C file per kind of
-    process in your project (such as "master" and "slave") plus one C file
-    for simulating your project. All those files are (or should ;) described
-    in section \ref GRAS_main_generation.
-    
-    The most intersting file in this context is
-    [project_name].Makefile.local (you can safely ignore the others for
-    now). To use it, simply type (from your project main directory):
-    
-\verbatim GRAS_ROOT=/path/to/simgrid/installation make -f [project_name].Makefile.local
-\endverbatim
-    
-    And that's it, all the binaries are built and linked against the correct
-    libraries.
-    
-    \section GRAS_compile_remote Distribution and remote compilation of GRAS projects
-    
-    Actually, there is two somehow parallel ways to do so since both Arnaud
-    and Martin gave it a try. Merging both approaches is underway. As usual,
-    if you want to help, you're welcome ;)
-    
-*/
-
 #####################################################################
 #########################  EXAMPLES #################################
 #####################################################################
@@ -327,7 +185,7 @@
  
     This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
     the code of the client and of the server is placed in the same file. See
-    the \ref GRAS_main_generation section if wondering.
+    the \ref GRAS_tut_tour_setup of the tutorial if wondering.
 
     \section GRAS_ex_ping_toc Table of contents of the ping example
       - \ref GRAS_ex_ping_common
@@ -382,7 +240,7 @@
     In order to ensure the communication between the "main" and the callback
     of the server, we need to declare some globals. We have to put them in a
     struct definition so that they can be handled properly in GRAS (see the
-    \ref GRAS_globals for more info).
+    \ref GRAS_tut_tour_globals for more info).
 
     \dontinclude gras/ping/ping_server.c
     \skip typedef struct
@@ -398,8 +256,8 @@
 
     \subsection GRAS_ex_ping_sermain 2.c) The "main" of the server
     
-    This is the "main" of the server. As explained in the \ref
-    GRAS_main_generation, you must not write any main()
+    This is the "main" of the server. As explained in the tutorial, \ref
+    GRAS_tut_tour_setup, you must not write any main()
     function yourself. Instead, you just have to write a regular function
     like this one which will act as a main.
     
@@ -451,7 +309,7 @@
    \section GRAS_ex_stoken_deploy 1) Deployment file
 
    Here is the deployment file:
-   \include examples/gras/tokenS/tokenS_deployment.xml
+   \include examples/gras/mutual_exclusion/simple_token/simple_token.xml
    
    The neighbour of each node is given at startup as command line argument.
    Moreover, one of the nodes is instructed by a specific argument (the one
@@ -465,7 +323,7 @@
    message to the next node. That is why we have to store all variable in a
    global, as explained in the \ref GRAS_globals section. 
 
-   \dontinclude examples/gras/tokenS/tokenS.c
+   \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
    \skip typedef
    \until }
    
@@ -511,7 +369,7 @@
        the server's answer.
  
     This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file. (See
-    the \ref GRAS_main_generation section if wondering why both the server
+    the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server
     and the client live in the same source file)
 
     \section GRAS_ex_mmrpc_toc Table of contents of the mmrpc example
@@ -520,7 +378,6 @@
         - \ref GRAS_ex_mmrpc_dataregister
         - \ref GRAS_ex_mmrpc_logdef
         - \ref GRAS_ex_mmrpc_msgregister
-        - \ref GRAS_ex_mmrpc_matdump
       - \ref GRAS_ex_mmrpc_server
 	- \ref GRAS_ex_mmrpc_serinc
 	- \ref GRAS_ex_mmrpc_sercb
@@ -547,27 +404,9 @@
 
     \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
 
-    The messages involved in this example do use structures as payload, 
-    so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing 
-    the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this 
-    declaration into an hidden string variable, which can be automatically parsed at 
-    run time. Of course, the declaration is also copied unmodified by this macro, so that it
-    gets parsed by the compiler also. 
-
-    There is some semantic that GRAS cannot guess alone and you need to  <i>annotate</i>
-    your declaration to add some. For example, the ctn pointer can be a reference to an 
-    object or a whole array (in which case you also has to specify its size). This is done 
-    with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
-    GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an 
-    array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols 
-    being the other fields of the structure). 
-
-    Please note that this annotation mechanism is not as robust and cool as this example seems to 
-    imply. If you want to use it yourself, you'd better use the exact right syntax, which is 
-    detailed in the \ref GRAS_dd section.
-
-    \skip GRAS_DEFINE_TYPE
-    \until matrix_t
+    The messages involved in a matrix of double. This type is automatically
+    known by the GRAS mecanism, using the gras_datadesc_matrix() function of the
+    xbt/matrix module.
 
     \subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
     
@@ -585,9 +424,7 @@
     \subsection GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
     
     This function, called by both the client and the server is in charge of
-    declaring the existing messages to GRAS. Note the use of the \ref gras_datadesc_by_symbol 
-    function to parse and retrieve the structure declaration which were passed to \ref GRAS_DEFINE_TYPE 
-    above. 
+    declaring the existing messages to GRAS.
 
     The datatype description builded that way can then be used to build an array datatype or 
     to declare messages.
@@ -595,14 +432,6 @@
     \skip register_messages
     \until }
 
-    \subsection GRAS_ex_mmrpc_matdump 1.e) Helper debugging function (mmrpc_common.c)
-
-    This function dumps a matrix to screen for debugging.
-    
-    \skip mat_dump
-    \until end_of_matrix
-    \until }
-
     [Back to \ref GRAS_ex_mmrpc_toc]
 
     \section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
@@ -631,8 +460,8 @@
 
     \subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
     
-    This is the "main" of the server. As explained in the \ref
-    GRAS_main_generation, you must not write any main()
+    This is the "main" of the server. As explained in the tutorial, \ref
+    GRAS_tut_tour_setup, you must not write any main()
     function yourself. Instead, you just have to write a regular function
     like this one which will act as a main.