/**
@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
Any GRAS project should be constituted of at least 3 files, and possibly
much more.
- <project>.c: A source file providing the source code of your
processes.
- <platform>.xml: 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.
- <project>.xml: 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 test, we have to write 3 files:
test.c, platform.xml and test.xml
\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
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 main() 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 main 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 argc and argv 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 Jacquelin and Boivin 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 server process
must be started onto the Jacquelin host and a client
process must be started on the Boivin 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 main function
since its content depends on whether you run in RL ou in SG. Instead, you
use a tool gras_stub_generator 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 \endverbatim
It parses the deployment file (called test.xml in our example),
searching for all the kind of processes you have in your project. It
then generates the following C files:
- a _<project_name>_<process_kind>.c 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 _<project_name>_simulator.c file.\n
This file is suited to the simulation mode. It contains a main()
function initializing the simulator and launching your project within.
- a <project_name>.mk file.\n
This is a makefile to regenerate any files on need. See next section.
In our example, we will thus obtain _test_server.c,
_test_client.c, _test_simulator.c and test.mk.
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
<project>.mk. 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 make
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 ./_simulator platform.xml deployment.xml\endverbatim
If you have an error message similar to
\verbatim
./_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
*/