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