X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/d7c2ab2b9f1e062530c924f187f3fce07d1648d1..96e69d0914a643f29b18149036bbd8d33ff047d9:/doc/user_guide/doxygen/gtut-files/gtut-tour-01-bones.doc
diff --git a/doc/user_guide/doxygen/gtut-files/gtut-tour-01-bones.doc b/doc/user_guide/doxygen/gtut-files/gtut-tour-01-bones.doc
deleted file mode 100644
index 04963f3fae..0000000000
--- a/doc/user_guide/doxygen/gtut-files/gtut-tour-01-bones.doc
+++ /dev/null
@@ -1,204 +0,0 @@
-
-/**
-@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
-
-*/