From fe8f0007bbd37e5e104fda886ff613276082e4f9 Mon Sep 17 00:00:00 2001 From: mquinson Date: Mon, 31 Jul 2006 12:14:42 +0000 Subject: [PATCH 1/1] Kill oldies deprecated by the tutorial git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@2658 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- doc/module-gras.doc | 236 +++++--------------------------------------- 1 file changed, 27 insertions(+), 209 deletions(-) diff --git a/doc/module-gras.doc b/doc/module-gras.doc index 9c84bb25d0..c653142c9e 100644 --- a/doc/module-gras.doc +++ b/doc/module-gras.doc @@ -30,19 +30,7 @@ This is how to let GRAS handle your globals properly. - \ref GRAS_emul : Support to emulate code excution (ie, reporting execution time into the simulator and having code sections specific - to simulation or to real mode). - - \ref GRAS_code: Here are some tools which may help - you setting up a GRAS project.\n - Setting up and building a GRAS application is complicated by the - library schizoid. The code to setup the environment differs - depending on whether you run on the simulator on a real platform. - And then, you'll have to deal with the usual distributed - application development difficulties. - - \ref GRAS_main_generation : Since processes are threads in - simulation mode and regular processes in the real world, GRAS does - generate your main functions for you. - - \ref GRAS_compile - + to simulation or to real mode). \section GRAS_example Examples @@ -53,11 +41,29 @@ - \ref GRAS_ex_mmrpc - \ref GRAS_ex_token - \ref GRAS_ex_timer + + \section GRAS_tut_presentation Tutorial + + We even have a tutorial for the GRAS framework. Here is the table of + content: + - \ref GRAS_tut_intro + - \ref GRAS_tut_intro_what + - \ref GRAS_tut_intro_model + - \ref GRAS_tut_tour + - \ref GRAS_tut_tour_install + - \ref GRAS_tut_tour_setup + - \ref GRAS_tut_tour_simpleexchange + - \ref GRAS_tut_tour_args + - \ref GRAS_tut_tour_callbacks + - \ref GRAS_tut_tour_globals + - \ref GRAS_tut_tour_logs + - \ref GRAS_tut_tour_timers + - \ref GRAS_tut_tour_exceptions + - \ref GRAS_tut_tour_rpc @{ */ /** @defgroup GRAS_comm Communication facilities */ /** @defgroup GRAS_run Virtualization */ - /** @defgroup GRAS_code Project and code management */ /** @defgroup GRAS_ex Examples */ /** @defgroup GRAS_tut GRAS Tutorial */ /** @} */ @@ -95,22 +101,6 @@ /** @} */ -##################################################################### -/** @addtogroup GRAS_code - - Here is how to setup your code when you want to use GRAS. You will also - learn how to get the most repetitive parts of your code generated - automatically. - - (use the tabs on top of the page to navigate) - - \htmlonly \endhtmlonly -*/ - ##################################################################### /** @addtogroup GRAS_ex @@ -133,178 +123,6 @@ examples/gras. */ -##################################################################### -######################### EXTRA PAGES ############################## -##################################################################### - ---------------------------------------------------------------------- ---------------------- main() generation ----------------------------- ---------------------------------------------------------------------- - -/** \page GRAS_main_generation main function - - \section GRAS_maingen_toc Table of content - - - \ref GRAS_maingen_intro - - \ref GRAS_maingen_script - - \ref GRAS_maingen_make - -
- - \section GRAS_maingen_intro What's the matter with main() functions in GRAS? - - In simulation mode, all processes are run as thread of the same process - while they are real processes in the real life. Unfortunately, the main - function of a real process must be called main while this - function must not use this name for threads. - - To deal with this, you should call the main function of your processes - with another name (usually, the process function such as client, server, - or such). Then GRAS can generate the wrapper functions adapted to the - real and simulated modes. - - \section GRAS_maingen_script Generating the main()s automatically - - This is done by the gras_stub_generator program, which gets installed on - make install (the source resides in the tools/gras/ directory). - Here is the calling syntax: - \verbatim gras_stub_generator \endverbatim - - It parses the deployment file, searching for all the kind of processes - you have in your project. It then generates the following C files: - - a __.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 __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. - - For this to work, the name of process described in your deployment file - should match the name of a function in your code, which prototype is for - example: \verbatim int client(int argc,char *argv[]);\endverbatim - - Unfortunately, all this is still partially documented. I guess I ought - to improve this situation somehow. In the meanwhile, check the generated - code and maybe also the GRAS \ref GRAS_example, sorry. - - \section GRAS_maingen_make Integration within an hand-made Makefile - - The easiest to set it up is to add the following chunk at the end of - your Makefile (or Makefile.am), putting the right values into NAME and - PROCESSES. -\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 - - Of course, your personal millage may vary. For the \ref GRAS_ex_ping, may read: -\verbatim _ping_client.c _ping_server.c _ping_simulator.c: ping.c ping_deployment.xml - $(top_srcdir)/tools/gras/gras_stub_generator ping ping_deployment.xml >/dev/null -\endverbatim - - \warning - Actually, gras_stub_generator also generates some makefiles both for - local compilation and remote code distribution and installation. See the - section \ref GRAS_compile for more details. - -*/ - ---------------------------------------------------------------------- -------------------------- Compiling --------------------------------- ---------------------------------------------------------------------- - -/** \page GRAS_compile Compiling your project - - As explained in section \ref GRAS_main_generation, the - gras_stub_generator tool can be used to generate the system - initialization code in your projet. While we were at this, this tool - also generates the makefiles you will need to compile your project - properly. - - Code source deployment and remote compilation also constitutes a - challenging area in distributed applications development. The GRASPE - (GRAS Platform Expender) tool was designed to make this less painful. - - \section GRAS_compile_toc Table of content - - - \ref GRAS_compile_local - - \ref GRAS_compile_local_install - - \ref GRAS_compile_local_helpfiles - - \ref GRAS_compile_local_makefile - - \ref GRAS_compile_remote - -
- - \section GRAS_compile_local Local compilation of GRAS projects - - \subsection GRAS_compile_local_install Installing SimGrid and GRAS - - To compile locally a GRAS project, you first need to install SimGrid on - your machine. Use the --prefix flag to the configure script to specify - where you want to install the toolkit (refere to section \ref - faq_compiling for more information) - - \subsection GRAS_compile_local_helpfiles Simulation description files - - Then, you will probably need to write a platform description file and - application deployment description file to feed the simulator with. This - part is unfortunatelly not documented enough. Files examples can be - found along with the MSG \ref MSG_ex_master_slave example. - - \note yes, both platform and application description files are portable - between MSG and GRAS. Actually, there depend on the SURF, not on the - programming environment you use. - - For the first try, you could probably reuse the provided platform file - as is while you will need to adapt the application file to fit your - needs. - - To generate new platform files, we usually use the Tiers Topology - Generator (ask google about it) and annotate the generated graph with - home-made scripts to let them fit the SURF. Those scripts live in the - tools/platform_generation/ directory of the distribution. - - \subsection GRAS_compile_local_makefile Generating a Makefile usable for your project - - From the information contained in the application description file, the - gras_stub_generator tool can create a Makefile which can be used to - seamlessly compile your project. Just go to the directory containing all - your project files, and type: - -\verbatim path/to/gras_stub_generator [project_name] [application_deployment.file] >/dev/null -\endverbatim - - The first argument is the name of your project, such as - "MyLovelyApplication" while the second one is the application deployment - file. - - Several files get generated by this command. One C file per kind of - process in your project (such as "master" and "slave") plus one C file - for simulating your project. All those files are (or should ;) described - in section \ref GRAS_main_generation. - - The most intersting file in this context is - [project_name].Makefile.local (you can safely ignore the others for - now). To use it, simply type (from your project main directory): - -\verbatim GRAS_ROOT=/path/to/simgrid/installation make -f [project_name].Makefile.local -\endverbatim - - And that's it, all the binaries are built and linked against the correct - libraries. - - \section GRAS_compile_remote Distribution and remote compilation of GRAS projects - - Actually, there is two somehow parallel ways to do so since both Arnaud - and Martin gave it a try. Merging both approaches is underway. As usual, - if you want to help, you're welcome ;) - -*/ - ##################################################################### ######################### EXAMPLES ################################# ##################################################################### @@ -328,7 +146,7 @@ This example resides in the examples/gras/ping/ping.c file. Yes, both the code of the client and of the server is placed in the same file. See - the \ref GRAS_main_generation section if wondering. + the \ref GRAS_tut_tour_setup of the tutorial if wondering. \section GRAS_ex_ping_toc Table of contents of the ping example - \ref GRAS_ex_ping_common @@ -383,7 +201,7 @@ In order to ensure the communication between the "main" and the callback of the server, we need to declare some globals. We have to put them in a struct definition so that they can be handled properly in GRAS (see the - \ref GRAS_globals for more info). + \ref GRAS_tut_tour_globals for more info). \dontinclude gras/ping/ping_server.c \skip typedef struct @@ -399,8 +217,8 @@ \subsection GRAS_ex_ping_sermain 2.c) The "main" of the server - This is the "main" of the server. As explained in the \ref - GRAS_main_generation, you must not write any main() + This is the "main" of the server. As explained in the tutorial, \ref + GRAS_tut_tour_setup, you must not write any main() function yourself. Instead, you just have to write a regular function like this one which will act as a main. @@ -512,7 +330,7 @@ the server's answer. This example resides in the examples/gras/mmrpc/mmrpc.c file. (See - the \ref GRAS_main_generation section if wondering why both the server + the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server and the client live in the same source file) \section GRAS_ex_mmrpc_toc Table of contents of the mmrpc example @@ -632,8 +450,8 @@ \subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server - This is the "main" of the server. As explained in the \ref - GRAS_main_generation, you must not write any main() + This is the "main" of the server. As explained in the tutorial, \ref + GRAS_tut_tour_setup, you must not write any main() function yourself. Instead, you just have to write a regular function like this one which will act as a main. -- 2.20.1