doc/gtut-tour-01-bones.doc

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