- - A makefile is often needed, too, even if it's not mandatory.
-
-If we start a project called <tt>test</tt>, we have to write 3 files:
-<tt>test.c</tt>, <tt>platform.xml</tt> and <tt>test.xml</tt>
-
-\subsection GRAS_tut_tour_setup_C The C source file
-
-Let's look at the C source file first. It should contain one main function
-for each type of processes in your overlay. Let's assume that you want to
-code a simple client/server communication. For this, the source file should
-read as:
-
-\verbatim #include <gras.h>
-
-int client(int argc, char *argv[]) {
- ...
-}
-
-int server(int argc, char *argv[]) {
- ...
-}
-\endverbatim
-
-Note that each of the processes's main function have the exact same
-prototype of the classical <tt>main()</tt> function in C.
-
-This is on purpose, each of them can assume this role when running in RL.
-But you shouldn't write a main() function yourself since all processes will
-run as threads within the same regular process in simulation mode. That is
-why the real <tt>main</tt> function of GRAS programs are generated
-automatically. This will be detailled in time (section \ref
-GRAS_tut_tour_setup_glue), but for now just note the similarity between the
-"main" functions you have to write for each processes and a "real main"
-function.
-
-Then, each process must initialize the GRAS framework at the beginning (with
-\ref gras_init) and should finalize it at the end (with \ref gras_exit).
-
-You should pass to \ref gras_init the <tt>argc</tt> and <tt>argv</tt> you
-received in your "main" function so that the users of your application can
-pass some configuration flags to the framework.
-
-It is not enough to have one of the processes initializing the framework
-since in RL, each of them will run on a different host. If you use some AMOK
-modules, you have to initialize them in each process too.
-
-The source file then reads: \include 1-bones.c
-
-That's it. You have a working GRAS application with two processes. They
-don't do anything useful, but that's a beginning. Let's see how to bring
-them to life.
-
-\subsection GRAS_tut_tour_setup_plat The platform file
-
-The platform file is used by the simulator to know about the existing hosts
-and their interactions. Its exact syntax is at the same time very simple and
-a bit beyond the topic of this document. Here is a very simple example
-describin two hosts named <i>Jacquelin</i> and <i>Boivin</i> and how they
-are interconnected.
-
-\include gtut-platform.xml
-
-At this point, you should not try to write your own platform file, but use
-one of the existing ones. There is a few of them in the examples/msg
-directory of the project. The only information we need from those files are
-the names of the existing hosts. It will be mandatory to write the
-deployment file.
-
-\subsection GRAS_tut_tour_setup_deploy The deployment file
-
-This file explains which of your processes should be started on the
-different hosts. It is mainly used in simulation. In real life, you will
-have to start your processes manually (see below). We we dream of a system
-able to apply a deployment file in real life and TakTuk may be the right
-tool for this, but this is still to be done.
-
-Here is an example of such file, describing that a <tt>server</tt> process
-must be started onto the <tt>Jacquelin</tt> host and a <tt>client</tt>
-process must be started on the <tt>Boivin</tt> host.
-
-\include test.xml
-
-Actually, you should write such a file also if you only plan to use GRAS in
-RL since this file is also used to glue your code to GRAS, as explained in
-the next section.
-
-\subsection GRAS_tut_tour_setup_glue Glueing things together
-
-As explained above, you shouldn't write any real <tt>main</tt> function
-since its content depends on whether you run in RL ou in SG. Instead, you
-use a tool <tt>gras_stub_generator</tt> to get the proper glue around your
-code generated. If you installed SimGrid in a regular place, this program is
-now in your path. Its source resides in the tools/gras/ directory of the
-archive, if you wonder.
-
-Here is the calling syntax:
-\verbatim gras_stub_generator <project_name> <deployment_file.xml>\endverbatim
-
-It parses the deployment file (called <tt>test.xml</tt> in our example),
-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.
- - a <tt><project_name>.mk</tt> file.\n
- This is a makefile to regenerate any files on need. See next section.
-
-In our example, we will thus obtain <tt>_test_server.c</tt>,
-<tt>_test_client.c</tt>, <tt>_test_simulator.c</tt> and <tt>test.mk</tt>.
-
-There is a pitfall: no verification is made on your actual source code, so
-if you have a typo on the process name in the deployment file, the generated
-code will be wrong, and the linker will spit error messages at you. Also
-remember that those names are in fact C function names, so they are
-case-sensitive.
-
-\subsection GRAS_tut_tour_setup_make A typical Makefile
-
-Now, we want to compile all the source files to build the actual binaries.
-It can be done manually, but it is much more convenient to use a makefile.
-Fortunately, gras_stub_generator generates a makefile for you under the name
-<tt><project>.mk</tt>. This file is sufficient for now. To compile our test
-application, just type:
-\verbatim make -f test.mk \endverbatim
-
-You may want to rename this file to Makefile so that typing <tt>make</tt>
-without argument becomes sufficient. In any case, do not edit this file
-without renaming it, or your changes will get overwritten at the next glue
-generation.
-
-If you already have a Makefile (or a Makefile.am for automake users), you
-can also add the following chunk at the end of your file:
-\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
-
-A simpler solution in our example would be to add:
-\verbatim _test_client.c _test_server.c _test_simulator.c: test.c test.xml
- path/to/gras_stub_generator test test.xml >/dev/null
-\endverbatim
-
-
-
-\subsection GRAS_tut_tour_setup_start Actually running the processes
-
-There is nothing to know to start your processes in RL. Simply call the
-generated binaries, and that's it. To start the simulation, simply call:
-\verbatim ./<project>_simulator platform.xml deployment.xml\endverbatim
-
-Here is an example of execution: \include 1-bones.output
-
-That's it. You are done with this lesson and can now write, build and
-execute GRAS applications as long as they don't do anything ;) Simply read on
-to add some flesh on these bones.
-
-(back to the top of the \ref GRAS_tut_tour)
+ - \ref GRAS_tut_tour_timers
+ - \ref GRAS_tut_tour_timers_intro
+ - \ref GRAS_tut_tour_timers_use
+ - \ref GRAS_tut_tour_timers_recap
+
+ - \ref GRAS_tut_tour_exceptions
+ - \ref GRAS_tut_tour_exceptions_intro
+ - \ref GRAS_tut_tour_exceptions_use
+ - \ref GRAS_tut_tour_exceptions_recap
+
+ - \ref GRAS_tut_tour_simpledata
+ - \ref GRAS_tut_tour_simpledata_intro
+ - \ref GRAS_tut_tour_simpledata_intro_conv
+ - \ref GRAS_tut_tour_simpledata_intro_gras
+ - \ref GRAS_tut_tour_simpledata_use
+ - \ref GRAS_tut_tour_simpledata_example
+ - \ref GRAS_tut_tour_simpledata_recap
+
+ - \ref GRAS_tut_tour_rpc
+ - \ref GRAS_tut_tour_rpc_intro
+ - \ref GRAS_tut_tour_rpc_use
+ - \ref GRAS_tut_tour_rpc_use_declare
+ - \ref GRAS_tut_tour_rpc_use_i2a_cb
+ - \ref GRAS_tut_tour_rpc_use_a2i_cb
+ - \ref GRAS_tut_tour_rpc_use_rest
+ - \ref GRAS_tut_tour_rpc_recap
+
+ - \ref GRAS_tut_tour_explicitwait
+ - \ref GRAS_tut_tour_explicitwait_intro
+ - \ref GRAS_tut_tour_explicitwait_use
+ - \ref GRAS_tut_tour_explicitwait_algo
+ - \ref GRAS_tut_tour_explicitwait_code
+ - \ref GRAS_tut_tour_explicitwait_recap
+
+ - \ref GRAS_tut_tour_message_recaping
+ - \ref GRAS_tut_tour_message_recaping_intro
+ - \ref GRAS_tut_tour_message_recaping_rpc
+ - \ref GRAS_tut_tour_message_recaping_rpc1
+ - \ref GRAS_tut_tour_message_recaping_rpc2
+ - \ref GRAS_tut_tour_message_recaping_rpc3
+ - \ref GRAS_tut_tour_message_recaping_rpc4
+ - \ref GRAS_tut_tour_message_recaping_rpc5
+ - \ref GRAS_tut_tour_message_recaping_rpc_aside1
+ - \ref GRAS_tut_tour_message_recaping_rpc_aside2
+ - \ref GRAS_tut_tour_message_recaping_rpc_aside3
+ - \ref GRAS_tut_tour_message_recaping_sync
+
+<b>Part 3: Data description</b>
+
+ - \ref GRAS_tut_tour_staticstruct Automatic parsing of static data types
+ - \ref GRAS_tut_tour_staticstruct_intro
+ - \ref GRAS_tut_tour_staticstruct_use
+ - \ref GRAS_tut_tour_staticstruct_recap
+
+ - \ref GRAS_tut_tour_pointers Automatic parsing of datatypes containing pointers
+ - \ref GRAS_tut_tour_pointers_intro
+ - \ref GRAS_tut_tour_pointers_use
+ - \ref GRAS_tut_tour_pointers_recap
+
+ - \ref GRAS_tut_tour_dynar Exchanging dynars (and matrices)
+ - \ref GRAS_tut_tour_dynar_intro
+ - \ref GRAS_tut_tour_dynar_use
+ - \ref GRAS_tut_tour_dynar_recap
+
+ - \ref GRAS_tut_tour_manualdatadef Manual data description: the full power
+ - \ref GRAS_tut_tour_manualdatadef_intro
+ - \ref GRAS_tut_tour_manualdatadef_use
+ - \ref GRAS_tut_tour_manualdatadef_recap
+
+ - \ref GRAS_tut_tour_exchangecb Exchange callbacks: yes you can
+ - \ref GRAS_tut_tour_exchangecb_intro
+ - \ref GRAS_tut_tour_exchangecb_use
+ - \ref GRAS_tut_tour_exchangecb_recap
+
+<b>Part 4: Advanced topics</b>
+
+Unfortunately, the tour is not terminated yet, but I already know the kind
+of missi^W lessons I want to add:
+
+ - Computation virtualization
+ - Splitting in several files (logs, datadesc)
+ - Debugging GRAS programs
+ - Doing proper GRAS modules
+