+++ /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
-
-*/
