--- /dev/null
+
+/**
+@page GRAS_tut_tour_setup Lesson 1: Setting up your own project
+
+\section GRAS_tut_tour_setup_toc Table of Contents
+ - \ref GRAS_tut_tour_setup_C
+ - \ref GRAS_tut_tour_setup_plat
+ - \ref GRAS_tut_tour_setup_deploy
+ - \ref GRAS_tut_tour_setup_glue
+ - \ref GRAS_tut_tour_setup_make
+ - \ref GRAS_tut_tour_setup_start
+
+<hr>
+
+Any GRAS project should be constituted of at least 3 files, and possibly
+much more.
+
+ - <tt><project>.c</tt>: A source file providing the source code of your
+ processes.
+
+ - <tt><platform>.xml</tt>: A platform description file. It describes
+ the virtual platform you want to run your application onto following the
+ SurfXML formatting so that the simulator can parse it. This file is only
+ needed in SG, and you don't need any to run on real platforms (of
+ course). The simplest is to use one of the pre-existing one.
+
+ - <tt><project>.xml</tt>: A deployment file. It describes which of
+ your processes to start, on which machine and with which arguments.
+
+ - 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>
+
+\section 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 01-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.
+
+\section 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.
+
+\section 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.
+
+\section 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.
+
+\section 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
+
+\section 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
+
+If you have an error message similar to
+\verbatim
+./<project>_simulator: error while loading shared libraries: libsimgrid.so.2: cannot open shared object file: No such file or directory
+\endverbatim
+it simply means that the dynamic linker of you system fails to find
+the simgrid library. The easiest way to solve this is to declare a
+LD_LIBRARY_PATH shell variable pointing to the directory where your
+library lives (that's /opt/simgrid/lib on my machine because I passed
+--prefix=/opt/simgrid to the configure script).
+
+Here is an example of execution: \include 01-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 ;) Move
+to the next lessons to add some flesh on these bones.
+
+Go to \ref GRAS_tut_tour_simpleexchange
+
+*/
