doc/gtut-tour-1-bones.doc

   1
   2 /**
   3 @page GRAS_tut_tour_setup Lesson 1: Setting up your own project
   4
   5 Any GRAS project should be constituted of at least 3 files, and possibly
   6 much more.
   7
   8   - <tt>&lt;project&gt;.c</tt>: A source file providing the source code of your
   9     processes.
  10
  11   - <tt>&lt;platform&gt;.xml</tt>: A platform description file. It describes
  12     the virtual platform you want to run your application onto following the
  13     SurfXML formatting so that the simulator can parse it. This file is only
  14     needed in SG, and you don't need any to run on real platforms (of
  15     course). The simplest is to use one of the pre-existing one.
  16
  17   - <tt>&lt;project&gt;.xml</tt>: A deployment file. It describes which of
  18     your processes to start, on which machine and with which arguments.
  19
  20   - A makefile is often needed, too, even if it's not mandatory.
  21
  22 If we start a project called <tt>test</tt>, we have to write 3 files:
  23 <tt>test.c</tt>, <tt>platform.xml</tt> and <tt>test.xml</tt>
  24
  25 \section GRAS_tut_tour_setup_C The C source file
  26
  27 Let's look at the C source file first. It should contain one main function
  28 for each type of processes in your overlay. Let's assume that you want to
  29 code a simple client/server communication. For this, the source file should
  30 read as:
  31
  32 \verbatim #include <gras.h>
  33
  34 int client(int argc, char *argv[]) {
  35   ...
  36 }
  37
  38 int server(int argc, char *argv[]) {
  39   ...
  40 }
  41 \endverbatim
  42
  43 Note that each of the processes's main function have the exact same
  44 prototype of the classical <tt>main()</tt> function in C.
  45
  46 This is on purpose, each of them can assume this role when running in RL.
  47 But you shouldn't write a main() function yourself since all processes will
  48 run as threads within the same regular process in simulation mode. That is
  49 why the real <tt>main</tt> function of GRAS programs are generated
  50 automatically. This will be detailled in time (section \ref
  51 GRAS_tut_tour_setup_glue), but for now just note the similarity between the
  52 "main" functions you have to write for each processes and a "real main"
  53 function.
  54
  55 Then, each process must initialize the GRAS framework at the beginning (with
  56 \ref gras_init) and should finalize it at the end (with \ref gras_exit).
  57
  58 You should pass to \ref gras_init the <tt>argc</tt> and <tt>argv</tt> you
  59 received in your "main" function so that the users of your application can
  60 pass some configuration flags to the framework.
  61
  62 It is not enough to have one of the processes initializing the framework
  63 since in RL, each of them will run on a different host. If you use some AMOK
  64 modules, you have to initialize them in each process too.
  65
  66 The source file then reads: \include 1-bones.c
  67
  68 That's it. You have a working GRAS application with two processes. They
  69 don't do anything useful, but that's a beginning. Let's see how to bring
  70 them to life.
  71
  72 \section GRAS_tut_tour_setup_plat The platform file
  73
  74 The platform file is used by the simulator to know about the existing hosts
  75 and their interactions. Its exact syntax is at the same time very simple and
  76 a bit beyond the topic of this document. Here is a very simple example
  77 describin two hosts named <i>Jacquelin</i> and <i>Boivin</i> and how they
  78 are interconnected.
  79
  80 \include gtut-platform.xml
  81
  82 At this point, you should not try to write your own platform file, but use
  83 one of the existing ones. There is a few of them in the examples/msg
  84 directory of the project. The only information we need from those files are
  85 the names of the existing hosts. It will be mandatory to write the
  86 deployment file.
  87
  88 \section GRAS_tut_tour_setup_deploy The deployment file
  89
  90 This file explains which of your processes should be started on the
  91 different hosts. It is mainly used in simulation. In real life, you will
  92 have to start your processes manually (see below). We we dream of a system
  93 able to apply a deployment file in real life and TakTuk may be the right
  94 tool for this, but this is still to be done.
  95
  96 Here is an example of such file, describing that a <tt>server</tt> process
  97 must be started onto the <tt>Jacquelin</tt> host and a <tt>client</tt>
  98 process must be started on the <tt>Boivin</tt> host.
  99
 100 \include test.xml
 101
 102 Actually, you should write such a file also if you only plan to use GRAS in
 103 RL since this file is also used to glue your code to GRAS, as explained in
 104 the next section.
 105
 106 \section GRAS_tut_tour_setup_glue Glueing things together
 107
 108 As explained above, you shouldn't write any real <tt>main</tt> function
 109 since its content depends on whether you run in RL ou in SG. Instead, you
 110 use a tool <tt>gras_stub_generator</tt> to get the proper glue around your
 111 code generated. If you installed SimGrid in a regular place, this program is
 112 now in your path. Its source resides in the tools/gras/ directory of the
 113 archive, if you wonder.
 114
 115 Here is the calling syntax:
 116 \verbatim gras_stub_generator <project_name> <deployment_file.xml>\endverbatim
 117
 118 It parses the deployment file (called <tt>test.xml</tt> in our example),
 119 searching for all the kind of processes you have in your project. It
 120 then generates the following C files:
 121
 122  - a <tt>_&lt;project_name&gt;_&lt;process_kind&gt;.c</tt> file for each process kind you
 123    have.\n
 124    They are used to launch your project in real life. They
 125    contain a main() in charge of initializing the GRAS infrastructure and
 126    launching your code afterward.
 127  - a <tt>_&lt;project_name&gt;_simulator.c</tt> file.\n
 128    This file is suited to the simulation mode. It contains a main()
 129    function initializing the simulator and launching your project within.
 130  - a <tt>&lt;project_name&gt;.mk</tt> file.\n
 131    This is a makefile to regenerate any files on need. See next section.
 132
 133 In our example, we will thus obtain <tt>_test_server.c</tt>,
 134 <tt>_test_client.c</tt>, <tt>_test_simulator.c</tt> and <tt>test.mk</tt>.
 135
 136 There is a pitfall: no verification is made on your actual source code, so
 137 if you have a typo on the process name in the deployment file, the generated
 138 code will be wrong, and the linker will spit error messages at you. Also
 139 remember that those names are in fact C function names, so they are
 140 case-sensitive.
 141
 142 \section GRAS_tut_tour_setup_make A typical Makefile
 143
 144 Now, we want to compile all the source files to build the actual binaries.
 145 It can be done manually, but it is much more convenient to use a makefile.
 146 Fortunately, gras_stub_generator generates a makefile for you under the name
 147 <tt>&lt;project&gt;.mk</tt>. This file is sufficient for now. To compile our test
 148 application, just type:
 149 \verbatim make -f test.mk \endverbatim
 150
 151 You may want to rename this file to Makefile so that typing <tt>make</tt>
 152 without argument becomes sufficient. In any case, do not edit this file
 153 without renaming it, or your changes will get overwritten at the next glue
 154 generation.
 155
 156 If you already have a Makefile (or a Makefile.am for automake users), you
 157 can also add the following chunk at the end of your file:
 158 \verbatim NAME=your_project_name
 159  PROCESSES=list of processes type in your project
 160
 161  $(foreach proc, $(PROCESSES), _$(NAME)_$(proc).c) _$(NAME)_simulator.c: $(NAME).c $(NAME)_deployment.xml
 162         path/to/gras_stub_generator $(NAME) $(NAME)_deployment.xml >/dev/null
 163 \endverbatim
 164
 165 A simpler solution in our example would be to add:
 166 \verbatim _test_client.c _test_server.c _test_simulator.c: test.c test.xml
 167         path/to/gras_stub_generator test test.xml >/dev/null
 168 \endverbatim
 169
 170 \section GRAS_tut_tour_setup_start Actually running the processes
 171
 172 There is nothing to know to start your processes in RL. Simply call the
 173 generated binaries, and that's it. To start the simulation, simply call:
 174 \verbatim ./<project>_simulator platform.xml deployment.xml\endverbatim
 175
 176 Here is an example of execution: \include 1-bones.output
 177
 178 That's it. You are done with this lesson and can now write, build and
 179 execute GRAS applications as long as they don't do anything ;) Move
 180 to the next lessons to add some flesh on these bones.
 181
 182 \ref GRAS_tut_tour_simpleexchange
 183
 184 */