Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
3055f2afbbaa1039dbbc6e1fc1fe1fed34589201
[simgrid.git] / buildtools / Cmake / simgrid_CMakeList / doc / FAQ.doc
1 /*! \page faq Frequently Asked Questions
2
3 \htmlinclude .FAQ.doc.toc
4
5 \section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
6
7 You are at the right place... Having a look to these
8 <a href="http://www.loria.fr/~quinson/articles/simgrid-tutorial.pdf">the tutorial slides</a> 
9 (or to these <a href="http://graal.ens-lyon.fr/~alegrand/articles/slides_g5k_simul.pdf">old slides</a>,
10 or to these
11 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">"obsolete" slides</a>)
12 may give you some insights on what SimGrid can help you to do and what
13 are its limitations. Then you definitely should read the \ref
14 MSG_examples. The \ref GRAS_tut can also help you.
15
16 If you are stuck at any point and if this FAQ cannot help you, please drop us a
17 mail to the user mailing list: <simgrid-user@lists.gforge.inria.fr>.
18
19 \subsection faq_interfaces What is the difference between MSG, SimDag, and GRAS? Do they serve the same purpose?
20
21 It depend on how you define "purpose", I guess ;)
22
23 They all allow you to build a prototype of application which you can run
24 within the simulator afterward. They all share the same simulation kernel,
25 which is the core of the SimGrid project. They differ by the way you express
26 your application.
27
28 With SimDag, you express your code as a collection of interdependent
29 parallel tasks. So, in this model, applications can be seen as a DAG of
30 tasks. This is the interface of choice for people wanting to port old
31 code designed for SimGrid v1 or v2 to the framework current version.
32
33 With both GRAS and MSG, your application is seen as a set of communicating
34 processes, exchanging data by the way of messages and performing computation
35 on their own.
36
37 The difference between both is that MSG is somehow easier to use, but GRAS
38 is not limited to the simulator. Once you're done writing your GRAS code,
39 you can run your code both in the simulator or on a real platform. For this,
40 there is two implementations of the GRAS interface, one for simulation, one
41 for real execution. So, you just have to relink your code to chose one of
42 both world. 
43
44 \subsection faq_generic First steps with SimGrid
45
46 If you decide to go for the MSG interface, please read carefully the
47 \ref MSG_examples. You'll find in \ref MSG_ex_master_slave a very
48 simple consisting of a master (that owns a bunch of tasks and
49 distributes them) , some slaves (that process tasks whenever they
50 receive one) and some forwarder agents (that simply pass the tasks
51 they receive to some slaves).
52
53 If you decide to go for the GRAS interface, you should definitively
54 read the \ref GRAS_tut. The first section constitutes an introduction
55 to the tool and presents the model we use. The second section
56 constitutes a complete step-by-step tutorial building a distributed
57 application from the beginning and exemplifying most of the GRAS
58 features in the process. The last section groups some HOWTOS
59 highlighting a given feature of the framework in a more concise way.
60
61 If you decide to go for another interface, I'm afraid your only sources
62 of information will be the source code and the mailing lists...
63
64 \subsection faq_visualization Visualizing and analyzing the results
65
66 It is sometime convenient to "see" how the agents are behaving. If you
67 like colors, you can use <tt>tools/MSG_visualization/colorize.pl </tt>
68 as a filter to your MSG outputs. It works directly with INFO. Beware,
69 INFO() prints on stderr. Do not forget to redirect if you want to
70 filter (e.g. with bash): 
71 \verbatim 
72 ./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
73 \endverbatim
74
75 We also have a more graphical output. Have a look at MSG_paje_output(). It 
76 generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
77 <center>
78 \htmlonly
79  <a href="Paje_MSG_screenshot.jpg"><img src="Paje_MSG_screenshot_thn.jpg"></a>
80 \endhtmlonly
81 </center>
82
83 Visualization with Paje can be seen as a kind of postmortem
84 analysis. However, as soon as you start playing with big simulations,
85 you'll realize that processing such output is kind of tricky. There is
86 so much generic information that it is hard to find the information
87 you are looking for.
88
89 As a matter of fact, logging really depends on simulations (e.g. what
90 kind of events is important...). That is why we do not propose a big
91 dump of your whole simulation (it would slow everything down) but give
92 you neat tools to structure you logs. Have a look at \ref XBT_log. In
93 fact, rather than a post-mortem analysis, you may want to do it on the
94 fly. The process you are running can do whatever you want. Have you
95 thought about adding a global structure where you directly compute the
96 information that are really important rather than writing everything
97 down and then processing huge files?
98
99 \subsection faq_C Argh! Do I really have to code in C?
100
101 Up until now, there is no binding for other languages. If you use C++,
102 you should be able to use the SimGrid library as a standard C library
103 and everything should work fine (simply <i>link</i> against this
104 library; recompiling SimGrid with a C++ compiler won't work and it
105 wouldn't help if you could).
106
107 In fact, we are currently working on Java bindings of MSG to allow
108 all the undergrad students of the world to use this tool. This is a
109 little more tricky than I would have expected, but the work is moving
110 fast forward [2006/05/13]. More languages are evaluated, but for now,
111 we do not feel a real demand for any other language. Please speak up!
112
113 \section faq_installation Installing the SimGrid library
114
115 Many people have been asking me questions on how to use SimGrid. Quite
116 often, the questions were not really about SimGrid but on the
117 installation process. This section is intended to help people that are
118 not familiar with compiling C files under UNIX. If you follow these
119 instructions and still have some troubles, drop an e-mail to
120 <simgrid-user@lists.gforge.inria.fr>.
121
122 \subsection faq_compiling Compiling SimGrid from a stable archive
123
124 First of all, you need to download the latest version of SimGrid from 
125 <a href="http://gforge.inria.fr/frs/?group_id=12">here</a>.
126 Suppose you have uncompressed SimGrid in some temporary location of
127 your home directory (say <tt>/home/joe/tmp/simgrid-3.0.1 </tt>). The
128 simplest way to use SimGrid is to install it in your home
129 directory. Change your directory to
130 <tt>/home/joe/tmp/simgrid-3.0.1</tt> and type
131
132 \verbatim
133 ./configure --prefix=$HOME
134 make
135 make install
136 \endverbatim
137
138 If at some point, something fails, check the section \ref faq_trouble_compil .
139 If it does not help, you can report this problem to the
140 list but, please, avoid sending a laconic mail like "There is a problem. Is it
141 okay?". Send the config.log file which is automatically generated by
142 configure. Try to capture both the standard output and the error output of the
143 <tt>make</tt> command with <tt>script</tt>. There is no way for us to help you
144 without the relevant bits of information.
145
146 Now, the following directory should have been created : 
147
148       \li <tt>/home/joe/doc/simgrid/html/</tt>
149       \li <tt>/home/joe/lib/</tt>
150       \li <tt>/home/joe/include/</tt>
151
152 SimGrid is not a binary, it is a library. Both a static and a dynamic
153 version are available. Here is what you can find if you try a <tt>ls
154 /home/joe/lib</tt>:
155
156 \verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
157 \endverbatim
158
159 Thus, there is two ways to link your program with SimGrid:
160       \li Either you use the static version, e.g 
161 \verbatim gcc libsimgrid.a -o MainProgram MainProgram.c
162 \endverbatim
163           In this case, all the SimGrid functions are directly
164           included in <tt>MainProgram</tt> (hence a bigger binary).
165       \li Either you use the dynamic version (the preferred method)
166 \verbatim gcc -lsimgrid -o MainProgram MainProgram.c
167 \endverbatim
168           In this case, the SimGrid functions are not included in
169           <tt>MainProgram</tt> and you need to set your environment
170           variable in such a way that <tt>libsimgrid.so</tt> will be
171           found at runtime. This can be done by adding the following
172           line in your .bashrc (if you use bash and if you have
173           installed the SimGrid libraries in your home directory):
174 \verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
175 \endverbatim
176
177 \subsection faq_compiling_java Java bindings don't get compiled
178
179 The configure script detects automatically whether you have the
180 softwares needed to use the Java bindings or not. At the end of the
181 configure, you can see the configuration picked by the script, which
182 should look similar to 
183 \verbatim Configuration of package simgrid' (version 3.3.4-svn) on
184 little64 (=4):
185
186          Compiler:       gcc (version: )
187          
188          CFlags:          -O3 -finline-functions -funroll-loops -fno-strict-aliasing -Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror -g3
189          CPPFlags:   
190          LDFlags:        
191                                    
192          Context backend: ucontext
193          Compile Java: no
194                                                          
195          Maintainer mode: no
196          Supernovae mode: yes
197 \endverbatim       
198
199 In this example, Java backends won't be compiled. 
200
201 On Debian-like systems (which includes ubuntu), you need the following
202 packages: sun-java6-jdk libgcj10-dev. If you cannot find the
203 libgcj10-dev, try another version, like libgcj9-dev (on Ubuntu before
204 9.10) or libgcj11-dev (not released yet, but certainly one day).
205 Please note that you need to activate the contrib and non-free
206 repositories in Debian, and the universe ones in Ubuntu. Java comes at
207 this price...
208
209 \subsection faq_compiling_snapshoot SimGrid development snapshots
210
211 We have very high standards on software quality, and we are reluctant releasing
212 a stable release as long as there is still some known bug in the code base. In
213 addition, we added quite an extensive test base, making sure that we correctly
214 test the most important parts of the tool. 
215
216 As an unfortunate conclusion, there may be some time between the stable
217 releases. If you want to benefit from the most recent features we introduced,
218 but don't want to take the risk of an untested version from the SVN, then
219 development snapshots are done for you. 
220
221 These are pre-releases of SimGrid that still fail some tests about features
222 that almost nobody use, or on platforms not being in our core target (which is
223 Linux, Mac, other Unixes and Windows, from the most important to the less
224 one). That means that using this development releases should be safe for most
225 users. 
226
227 These archives can be found on 
228 <a href="http://www.loria.fr/~quinson/simgrid.html">this web page</a>. Once you 
229 got the lastest archive, you can compile it just like any archive (see above).
230
231 \subsection faq_compiling_svn Compiling SimGrid from the SVN
232
233 The project development takes place in the SVN, where all changes are
234 committed when they happen. Then every once in a while, we make sure that the
235 code quality meets our standard and release an archive from the code in the
236 SVN. We afterward go back to the development in the SVN. So, if you need a
237 recently added feature and can afford some little problem with the stability
238 of the lastest features, you may want to use the SVN version instead of a
239 released one.
240
241 For that, you first need to get the "simgrid" module from
242 <a href="http://gforge.inria.fr/scm/?group_id=12">here</a>. 
243
244 You won't find any <tt>configure</tt> and a few other things
245 (<tt>Makefile.in</tt>'s, documentation, ...) will be missing as well. The
246 reason for that is that all these files have to be regenerated using the
247 latest versions of <tt>autoconf</tt>, <tt>libtool</tt>, <tt>automake</tt>
248 (>1.9) and <tt>doxygen</tt> (>1.4). To generate the <tt>configure</tt> and
249 the <tt>Makefile.in</tt>'s, you just have to launch the <tt>bootstrap</tt>
250 command that resides in the top of the source tree. Then just follow the
251 instructions of Section \ref faq_compiling.
252
253 We insist on the fact that you really need the latest versions of
254 autoconf, automake and libtool. Doing this step on exotic architectures/systems
255 (i.e. anything different from a recent linux distribution) may be
256 ... uncertain. If you need to compile the SVN version on a machine where all these
257 dependencies are not met, the easiest is to do <tt>make dist</tt> in the SVN
258 directory of another machine where all dependencies are met. It will create an
259 archive you may deploy on other sites just as a regular stable release.
260
261 In summary, the following commands will checkout the SVN, regenerate the
262 configure script and friends, configure SimGrid and build it.
263
264 \verbatim svn checkout svn://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk simgrid
265 cd simgrid
266 ./bootstrap
267 ./configure --enable-maintainer-mode --prefix=<where to install SimGrid>
268 make \endverbatim
269
270 Then, if you want to install SimGrid on the current box, just do:
271 \verbatim make install \endverbatim
272
273 If you want to build an snapshot of the SVN to deploy it on another box (for
274 example because the other machine don't have the autotools), do:
275 \verbatim make dist \endverbatim
276
277 Moreover, you should never call the autotools manually since you must run
278 them in a specific order with specific arguments. Most of the times, the
279 makefiles will automatically call the tools for you. When it's not possible
280 (such as the first time you checkout the SVN), use the ./bootstrap command
281 to call them explicitly.
282
283
284 \subsection faq_setting_MSG Setting up your own MSG code
285
286 Do not build your simulator by modifying the SimGrid examples.  Go
287 outside the SimGrid source tree and create your own working directory
288 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
289
290 Suppose your simulation has the following structure (remember it is
291 just an example to illustrate a possible way to compile everything;
292 feel free to organize it as you want).
293
294       \li <tt>sched.h</tt>: a description of the core of the
295           scheduler (i.e. which functions are can be used by the
296           agents). For example we could find the following functions
297           (master, forwarder, slave).
298
299       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
300           implementing the core of the scheduler. Most of these
301           functions use the MSG functions defined in section \ref
302           msg_gos_functions.
303
304       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
305           the MSG initialization (MSG_global_init()), the platform
306           creation (e.g. with MSG_create_environment()), the
307           deployment phase (e.g. with MSG_function_register() and
308           MSG_launch_application()) and the call to
309           MSG_main()).
310
311 To compile such a program, we suggest to use the following
312 Makefile. It is a generic Makefile that we have used many times with
313 our students when we teach the C language.
314
315 \verbatim
316 all: masterslave 
317 masterslave: masterslave.o sched.o
318
319 INSTALL_PATH = $$HOME
320 CC = gcc
321 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
322                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
323                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
324                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
325                                 -Wpointer-arith -Wwrite-strings -finline-functions
326 REASONABLY_CAREFUL_DUDE =       -Wall
327 NO_PRAYER_FOR_THE_WICKED =      -w -O2 
328 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
329 CFLAGS = -g $(WARNINGS)
330
331 INCLUDES = -I$(INSTALL_PATH)/include
332 DEFS = -L$(INSTALL_PATH)/lib/
333 LDADD = -lm -lsimgrid 
334 LIBS = 
335
336 %: %.o
337         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@ 
338
339 %.o: %.c
340         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
341
342 clean:
343         rm -f $(BIN_FILES) *.o *~
344 .SUFFIXES:
345 .PHONY : clean
346
347 \endverbatim
348
349 The first two lines indicates what should be build when typing make
350 (<tt>masterslave</tt>) and of which files it is to be made of
351 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
352 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
353 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
354 the static version, remove the <tt>-lsimgrid</tt> and add a
355 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
356 after the <tt>LIBS = </tt>.
357
358 More generally, if you have never written a Makefile by yourself, type
359 in a terminal : <tt>info make</tt> and read the introduction. The
360 previous example should be enough for a first try but you may want to
361 perform some more complex compilations...
362
363 \subsection faq_setting_GRAS Setting up your own GRAS code
364
365 If you use the GRAS interface instead of the MSG one, then previous section
366 is not the better source of information. Instead, you should check the GRAS
367 tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
368
369 \section faq_cmake CMAKE
370
371 \subsection faq_intro Some generalitty
372
373 1 What is Cmake?
374
375 CMake is a family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice. For more information see official web site <a href="http://www.cmake.org/">here</a>.
376
377 2 Why cmake?
378
379 CMake permits to developers to compil projects on different plateform. Then many tools are embedded like ctest for making test, a link to cdash for vizualise results but also test coverage and bug reports. 
380
381 3 What cmake need?
382
383 CMake needs some prerequists like :
384   \li make
385   \li a c, c++ and java compiler regards to developers
386   \li ccmake for graphical used of CMake
387   \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">download</a>
388
389 4 Cmake vs Autotools...
390
391
392
393 \subsection faq_cmakeoption Cmake options
394
395 1 Liste of options
396
397 \verbatim
398 "cmake -D[name]=[value] ... ./"
399  
400 [name]          disable_gtnets                  [value] ON/OFF or TRUE/FALSE or 1/0
401                 disable_java                            ON/OFF or TRUE/FALSE or 1/0
402                 disable_lua                             ON/OFF or TRUE/FALSE or 1/0
403                 disable_ruby                            ON/OFF or TRUE/FALSE or 1/0
404
405                 enable_compile_optimizations            ON/OFF or TRUE/FALSE or 1/0
406                 enable_compile_warnings                 ON/OFF or TRUE/FALSE or 1/0
407                 enable_maintainer_mode                  ON/OFF or TRUE/FALSE or 1/0
408                 
409                 supernovae                              ON/OFF or TRUE/FALSE or 1/0
410
411                 gtnets_path                             <path_to_gtnets_directory>
412                 prefix                                  <path_to_install_directory>
413                 with_context                            auto/ucontext/pthread/window
414 \endverbatim
415
416 2 Options explaination
417
418   \li disable_gtnets : set to true implie that user doesn't want to use gtnets.
419
420   \li disable_java : set to true implie that user doesn't want to add java langage into simgrid compilation.
421
422   \li disable_lua : set to true implie that user doesn't want to add lua langage into simgrid compilation.
423
424   \li disable_ruby : set to true implie that user doesn't want to add ruby langage into simgrid compilation.
425
426   \li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
427
428   \li enable_compile_warnings : add flags "-Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror"
429
430   \li enable_maintainer_mode : set to true make doc and remake files with flex flexml.
431 \verbatim
432 /doc/html
433 /src/gras/DataDesc/ddt_parse.yy.c
434 /src/surf/simgrid_dtd.c
435 /src/xbt/graphxml.c
436 /src/simdag/dax_dtd.c
437 /include/surf/simgrid_dtd.h
438 /include/xbt/graphxml.h
439 /src/simdag/dax_dtd.h
440 \endverbatim
441   \li supernovae : set to true make one file for each lib and compile with those generated files.
442 \verbatim
443 /src/supernovae_sg.c
444 /src/supernovae_gras.c                  
445 /src/supernovae_smpi.c
446 \endverbatim
447   \li gtnets_path : Path to gtnets install directory (ex /usr)
448
449   \li prefix : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
450
451   \li with context : specify which context the user wants to use.
452
453 3 Initialisation
454
455 Those options are initialized the first time you launch \"cmake ./\" whithout specified option.
456
457 \verbatim
458 with_context                    auto
459 enable_maintainer_mode          off
460 supernovae                      off
461 disable_java                    off
462 disable_lua                     off
463 enable_compile_warnings         off
464 enable_compile_optimizations    off
465 disable_gtnets                  off
466 disable_ruby                    on
467 \endverbatim
468
469 4 Option's cache and how to reset?
470
471 When options have been set they are keep into a cache file named \"CMakeCache.txt\". So if you want 
472 reset values you just delete this file located to the project directory.
473
474 \subsection faq_cmakecompilation Cmake compilation
475
476 1 With command line.
477
478 \verbatim
479 cmake -D[name]=[value] ... ./
480 make
481 \endverbatim
482
483 2 With ccmake tool.
484
485 \verbatim
486 "ccmake ./"
487 \endverbatim
488 Then follow instructions.
489
490 3 Resume of command line
491
492  \li CMake
493 \verbatim
494 cmake ./                configure the project
495 make                    build all tagets
496 make test               test all targets and summarize
497 make package            make the distrib
498 make install-simgrid    install the project (doc/ lib/ include/)
499 make clean"             clean all targets
500 \endverbatim
501
502 When the project have been succesfully compiling and build you can make tests.
503
504  \li CTest
505 \verbatim
506 ctest                   launch only tests
507 ctest -D Continuous
508 ctest -D Continuous(Start|Update|Configure|Build)
509 ctest -D Continuous(Test|Coverage|MemCheck|Submit)
510 ctest -D Experimental
511 ctest -D Experimental(Start|Update|Configure|Build)
512 ctest -D Experimental(Test|Coverage|MemCheck|Submit)
513 ctest -D Nightly
514 ctest -D Nightly(Start|Update|Configure|Build)
515 ctest -D Nightly(Test|Coverage|MemCheck|Submit)
516 ctest -D NightlyMemoryCheck
517 \endverbatim
518
519 4 Examples for different mode.
520
521 \li Mode maintainer
522
523 cmake -Denable_maintainer_mode=on ./
524 \verbatim GTnetS doesn't works : set -Ddisable_gtnets=on
525 with_context auto change to ucontext
526 (skaddr)
527 (sksize)
528 Make : src/simgrid.jar with : /usr/bin/javac
529 Make examples/java with : /usr/bin/javac
530
531 Configuration of package `simgrid' (revision 7228M) on arch (=4):
532         BUILDNAME :             UCONTEXT
533              SITE :             Linux_Ubuntu 9.10_x86_64
534
535         Compiler: c++ :         /usr/bin/c++
536                version:         c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
537                   c   :         /usr/bin/gcc
538                version:         gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
539
540         CFlags:                 -g3
541         CPPFlags:               
542         LDFlags:                
543
544         Context backend:        ucontext
545         Compile Gtnets:         0
546                   path:         
547         Compile Java:           1
548         Compile Lua:            1
549         Compile Ruby:           0
550
551         Maintainer mode:        on
552         Supernovae mode:        off
553
554         Simgrid dependencies:   dl -llua5.1
555         Gras dependencies:      pthread
556         Ruby dependencies:      
557         Smpi dependencies:      
558
559         USER_PREFIX:            /usr/local
560         INSTALL_PREFIX:         /usr/local
561
562 -- Configuring done
563 -- Generating done
564 -- Build files have been written to: /home/navarrop/Bureau/simgrid-trunk
565 \endverbatim
566
567 \li Mode supernovae
568
569 cmake -Dsupernovae=on ./
570 \verbatim GTnetS doesn't works : set -Ddisable_gtnets=on
571 with_context auto change to ucontext
572 (skaddr)
573 (sksize)
574 Make : src/simgrid.jar with : /usr/bin/javac
575 Make examples/java with : /usr/bin/javac
576
577 Configuration of package `simgrid' (revision 7228M) on arch (=4):
578         BUILDNAME :             SUPERNOVAE
579              SITE :             Linux_Ubuntu 9.10_x86_64
580
581         Compiler: c++ :         /usr/bin/c++
582                version:         c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
583                   c   :         /usr/bin/gcc
584                version:         gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
585
586         CFlags:                 -O3 -finline-functions -funroll-loops -fno-strict-aliasing -Wall -Wunused -Wmissing-prototypes -Wmissing-declarations -Wpointer-arith -Wchar-subscripts -Wcomment -Wformat -Wwrite-strings -Wno-unused-function -Wno-unused-parameter -Wno-strict-aliasing -Wno-format-nonliteral -Werror -g3
587         CPPFlags:               
588         LDFlags:                
589
590         Context backend:        ucontext
591         Compile Gtnets:         0
592                   path:         
593         Compile Java:           1
594         Compile Lua:            1
595         Compile Ruby:           0
596
597         Maintainer mode:        off
598         Supernovae mode:        on
599
600         Simgrid dependencies:   dl -llua5.1
601         Gras dependencies:      pthread
602         Ruby dependencies:      
603         Smpi dependencies:      
604
605         USER_PREFIX:            /usr/local
606         INSTALL_PREFIX:         /usr/local
607
608 -- Configuring done
609 -- Generating done
610 -- Build files have been written to: /home/navarrop/Bureau/simgrid-trunk
611 \endverbatim
612
613 \li Mode GTnetS
614
615 cmake -Dgtnets_path=/home/navarrop/Bureau/usr/ ./
616 \verbatim with_context auto change to ucontext
617 (skaddr)
618 (sksize)
619 Make : src/simgrid.jar with : /usr/bin/javac
620 Make examples/java with : /usr/bin/javac
621
622 Configuration of package `simgrid' (revision 7228M) on arch (=4):
623         BUILDNAME :             GTNETS
624              SITE :             Linux_Ubuntu 9.10_x86_64
625
626         Compiler: c++ :         /usr/bin/c++
627                version:         c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
628                   c   :         /usr/bin/gcc
629                version:         gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
630
631         CFlags:                  -L/home/navarrop/Bureau/usr/lib -I/home/navarrop/Bureau/usr/include/gtnets -g3
632         CPPFlags:                -L/home/navarrop/Bureau/usr/lib -I/home/navarrop/Bureau/usr/include/gtnets 
633         LDFlags:                
634
635         Context backend:        ucontext
636         Compile Gtnets:         1
637                   path:         /home/navarrop/Bureau/usr
638         Compile Java:           1
639         Compile Lua:            1
640         Compile Ruby:           0
641
642         Maintainer mode:        off
643         Supernovae mode:        off
644
645         Simgrid dependencies:   dl -llua5.1 -lgtnets
646         Gras dependencies:      pthread
647         Ruby dependencies:      
648         Smpi dependencies:      
649
650         USER_PREFIX:            /usr/local
651         INSTALL_PREFIX:         /usr/local
652
653 INFO -->> Take care to have export LD_LIBRARY_PATH before run make command for make examples with gtnets
654 copy and paste : export LD_LIBRARY_PATH=/home/navarrop/Bureau/usr/lib/:$LD_LIBRARY_PATH
655
656
657 -- Configuring done
658 -- Generating done
659 -- Build files have been written to: /home/navarrop/Bureau/simgrid-trunk
660 \endverbatim
661
662 \subsection faq_cmakeinstall How to install with cmake?
663
664 1 From svn. 
665
666 \verbatim
667 cmake -Denable_maintainer_mode=on -Dprefix=/home/navarrop/Bureau/install_simgrid ./
668 make 
669 make install-simgrid
670 \endverbatim
671
672 2 From a distrib
673
674 \verbatim
675 cmake -Dprefix=/home/navarrop/Bureau/install_simgrid ./
676 make
677 make install-simgrid
678 \endverbatim
679
680 \subsection faq_screenshot Screenshot and examples
681
682 1 Screenshot.
683
684 \verbatim
685 navarrop@caraja:~$ cd Bureau/simgrid-trunk/
686 navarrop@caraja:~/Bureau/simgrid-trunk$ cmake ./
687
688 GTnetS doesn't works : set -Ddisable_gtnets=on                  <-|some warnings are printed 
689 with_context auto change to ucontext                            <-|
690 (skaddr)                                                        <--info (needed)
691 (sksize)                                                        <--info (needed)
692 Make : src/simgrid.jar with : /usr/bin/javac                    <--info (if java)
693 Make examples/java with : /usr/bin/javac                        <--info (if java)
694
695 Configuration of package `simgrid' (revision 7209M) on arch (=4):
696         BUILDNAME :             UCONTEXT                                <-- name of the compilation regarding to cdash
697              SITE :             Linux_Ubuntu 9.10_x86_64                <-- distribution of the local machine regarding to cdash
698
699         Compiler: c++ :         /usr/bin/c++
700                version:         c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
701                   c   :         /usr/bin/gcc
702                version:         gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
703
704         CFlags:                 -g3
705         CPPFlags:               
706         LDFlags:                
707
708         Context backend:        ucontext
709         Compile Gtnets:         0
710                   path:         
711         Compile Java:           1
712         Compile Lua:            1
713         Compile Ruby:           0
714
715         Maintainer mode:        OFF
716         Supernovae mode:        OFF
717
718         Simgrid dependencies:   -ldl -llua5.1
719         Gras dependencies:      pthread
720         Ruby dependencies:      
721         Smpi dependencies:      
722
723         USER_PREFIX:            /usr/local
724         INSTALL_PREFIX:         /usr/local
725
726 -- Configuring done
727 -- Generating done
728 -- Build files have been written to: /home/navarrop/Bureau/simgrid-trunk
729 \endverbatim
730 Here all options are checked and printed. If it doesn't match with your configuration 
731 it is probably due to a wrong configuration.
732
733 2 Examples.
734
735 \subsection faq_cmakehowto How to modified sources files for developers
736
737 1 Add an executable or examples.
738
739 If you want make an executable you have to create a CMakeList.txt to the src directory. 
740 You must specified where to create the executable, source list, dependencies and the name of the binary.
741
742 \verbatim
743 cmake_minimum_required(VERSION 2.6)
744
745 set(EXECUTABLE_OUTPUT_PATH "./")                        
746 set(LIBRARY_OUTPUT_PATH "${PROJECT_DIRECTORY}/lib")
747
748 add_executable(get_sender get_sender.c)                                 #add_executable(<name_of_target> <src list>)
749
750 ### Add definitions for compile
751 target_link_libraries(get_sender simgrid m pthread -fprofile-arcs)      #target_link_libraries(<name_of_targe> <dependencies>)
752 \endverbatim
753
754 Then you have to modified <project/directory>/buildtools/Cmake/src/CMakeMakeExeLib.txt and add 
755 this line :
756 \verbatim
757 add_subdirectory(${PROJECT_DIRECTORY}/<path_where_is_CMakeList.txt>)
758 \endverbatim
759
760 2 Delete/add sources to lib.
761
762 If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/src/CMakeDefinePackages.txt
763
764 \verbatim
765 set(JMSG_JAVA_SRC
766         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/MsgException.java
767         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/JniException.java
768         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/NativeException.java
769         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/HostNotFoundException.java
770         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/ProcessNotFoundException.java
771         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Msg.java
772         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Process.java
773         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Host.java
774         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Task.java
775         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/MsgNative.java
776         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/ApplicationHandler.java
777         ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Sem.java
778 )
779 \endverbatim
780
781 3 Add test
782
783 If you want modified, add or delete tests you have to edit <project/directory>/buildtools/Cmake/src/CMakeTest.txt 
784 with this function : ADD_TEST(<name> <bin> <ARGS>)
785
786 \verbatim
787 add_test(test-simdag-1 ${PROJECT_DIRECTORY}/testsuite/simdag/sd_test --cfg=path:${PROJECT_DIRECTORY}/testsuite/simdag small_platform_variable.xml)
788 \endverbatim
789
790 \subsection faq_cmakeExplain Explaination of sources files for cmake
791
792 List of sources for cmake.
793
794 \section faq_howto Feature related questions
795
796 \subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?"
797
798 Here is the deal. The whole SimGrid project (MSG, SURF, GRAS, ...) is
799 meant to be kept as simple and generic as possible. We cannot add
800 functions for everybody's needs when these functions can easily be
801 built from the ones already in the API. Most of the time, it is
802 possible and when it was not possible we always have upgraded the API
803 accordingly. When somebody asks us a question like "How to do that?
804 Is there a function in the API to simply do this?", we're always glad
805 to answer and help. However if we don't need this code for our own
806 need, there is no chance we're going to write it... it's your job! :)
807 The counterpart to our answers is that once you come up with a neat
808 implementation of this feature (task duplication, RPC, thread
809 synchronization, ...), you should send it to us and we will be glad to
810 add it to the distribution. Thus, other people will take advantage of
811 it (and we don't have to answer this question again and again ;).
812
813 You'll find in this section a few "Missing In Action" features. Many
814 people have asked about it and we have given hints on how to simply do
815 it with MSG. Feel free to contribute...
816
817 \subsection faq_MIA_MSG MSG features
818
819 \subsubsection faq_MIA_examples I want some more complex MSG examples!
820
821 Many people have come to ask me a more complex example and each time,
822 they have realized afterward that the basics were in the previous three
823 examples. 
824
825 Of course they have often been needing more complex functions like
826 MSG_process_suspend(), MSG_process_resume() and
827 MSG_process_isSuspended() (to perform synchronization), or
828 MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
829 receptions), or even MSG_process_create() (to design asynchronous
830 communications or computations). But the examples are sufficient to
831 start.
832
833 We know. We should add some more examples, but not really some more
834 complex ones... We should add some examples that illustrate some other
835 functionalists (like how to simply encode asynchronous
836 communications, RPC, process migrations, thread synchronization, ...)
837 and we will do it when we will have a little bit more time. We have
838 tried to document the examples so that they are understandable. Tell
839 us if something is not clear and once again feel free to participate!
840 :)
841
842 \subsubsection faq_MIA_taskdup Missing in action: MSG Task duplication/replication
843
844 There is no task duplication in MSG. When you create a task, you can
845 process it or send it somewhere else. As soon as a process has sent
846 this task, he doesn't have this task anymore. It's gone. The receiver
847 process has got the task. However, you could decide upon receiving to
848 create a "copy" of a task but you have to handle by yourself the
849 semantic associated to this "duplication".
850
851 As we already told, we prefer keeping the API as simple as
852 possible. This kind of feature is rather easy to implement by users
853 and the semantic you associate really depends on people. Having a
854 *generic* task duplication mechanism is not that trivial (in
855 particular because of the data field). That is why I would recommand
856 that you write it by yourself even if I can give you advice on how to
857 do it.
858
859 You have the following functions to get informations about a task:
860 MSG_task_get_name(), MSG_task_get_compute_duration(),
861 MSG_task_get_remaining_computation(), MSG_task_get_data_size(),
862 and MSG_task_get_data().
863
864 You could use a dictionary (#xbt_dict_t) of dynars (#xbt_dynar_t). If
865 you still don't see how to do it, please come back to us...
866
867 \subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
868
869 Up until now, there is no asynchronous communications in MSG. However,
870 you can create as many process as you want so you should be able to do
871 whatever you want... I've written a queue module to help implementing
872 some asynchronous communications at low cost (creating thousands of
873 process only to handle communications may be problematic in term of
874 performance at some point). I'll add it in the distribution asap.
875
876 \subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
877
878 You obviously cannot use pthread_mutexes of pthread_conds. The best
879 thing would be to propose similar structures. Unfortunately, we
880 haven't found time to do it yet. However you can try to play with
881 MSG_process_suspend() and MSG_process_resume(). You can even do some
882 synchronization with fake communications (using MSG_task_get(),
883 MSG_task_put() and MSG_task_Iprobe()).
884
885 \subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
886
887 There is no such thing because its semantic wouldn't be really
888 clear. Of course, it is something about the amount of host throughput,
889 but there is as many definition of "host load" as people asking for
890 this function. First, you have to remember that resource availability
891 may vary over time, which make any load notion harder to define.
892
893 It may be instantaneous value or an average one. Moreover it may be only the
894 power of the computer, or may take the background load into account, or may
895 even take the currently running tasks into account. In some SURF models,
896 communications have an influence on computational power. Should it be taken
897 into account too?
898
899 First of all, it's near to impossible to predict the load beforehands in the
900 simulator since it depends on too much parameters (background load
901 variation, bandwidth sharing algorithmic complexity) some of them even being
902 not known beforehands (other task starting at the same time). So, getting
903 this information is really hard (just like in real life). It's not just that
904 we want MSG to be as painful as real life. But as it is in some way
905 realistic, we face some of the same problems as we would face in real life.
906
907 How would you do it for real? The most common option is to use something
908 like NWS that performs active probes. The best solution is probably to do
909 the same within MSG, as in next code snippet. It is very close from what you
910 would have to do out of the simulator, and thus gives you information that
911 you could also get in real settings to not hinder the realism of your
912 simulation. 
913
914 \verbatim
915 double get_host_load() {
916    m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
917    double date = MSG_get_clock();
918
919    MSG_task_execute(task);
920    date = MSG_get_clock() - date;
921    MSG_task_destroy(task);
922    return (0.001/date);
923 }
924 \endverbatim
925
926 Of course, it may not match your personal definition of "host load". In this
927 case, please detail what you mean on the mailing list, and we will extend
928 this FAQ section to fit your taste if possible.
929
930 \subsubsection faq_MIA_communication_time How can I get the *real* communication time?  
931
932 Communications are synchronous and thus if you simply get the time
933 before and after a communication, you'll only get the transmission
934 time and the time spent to really communicate (it will also take into
935 account the time spent waiting for the other party to be
936 ready). However, getting the *real* communication time is not really
937 hard either. The following solution is a good starting point.
938
939 \verbatim
940 int sender()
941 {
942   m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size, 
943                                   calloc(1,sizeof(double)));
944   *((double*) task->data) = MSG_get_clock();
945   MSG_task_put(task, slaves[i % slaves_count], PORT_22);
946   INFO0("Send completed");
947   return 0;
948 }
949 int receiver()
950 {
951   m_task_t task = NULL;
952   double time1,time2;
953
954   time1 = MSG_get_clock();
955   a = MSG_task_get(&(task), PORT_22);
956   time2 = MSG_get_clock();
957   if(time1<*((double *)task->data))
958      time1 = *((double *) task->data);
959   INFO1("Communication time :  \"%f\" ", time2-time1);
960   free(task->data);
961   MSG_task_destroy(task);
962   return 0;
963 }
964 \endverbatim
965
966 \subsection faq_MIA_SimDag SimDag related questions
967
968 \subsubsection faq_SG_comm Implementing communication delays between tasks.
969
970 A classic question of SimDag newcomers is about how to express a
971 communication delay between tasks. The thing is that in SimDag, both
972 computation and communication are seen as tasks.  So, if you want to
973 model a data dependency between two DAG tasks t1 and t2, you have to
974 create 3 SD_tasks: t1, t2 and c and add dependencies in the following
975 way:
976
977 \verbatim
978 SD_task_dependency_add(NULL, NULL, t1, c);
979 SD_task_dependency_add(NULL, NULL, c, t2);
980 \endverbatim
981
982 This way task t2 cannot start before the termination of communication c
983 which in turn cannot start before t1 ends.
984
985 When creating task c, you have to associate an amount of data (in bytes)
986 corresponding to what has to be sent by t1 to t2.
987
988 Finally to schedule the communication task c, you have to build a list
989 comprising the workstations on which t1 and t2 are scheduled (w1 and w2
990 for example) and build a communication matrix that should look like
991 [0;amount ; 0; 0].
992
993 \subsubsection faq_SG_DAG How to implement a distributed dynamic scheduler of DAGs.
994
995 Distributed is somehow "contagious". If you start making distributed
996 decisions, there is no way to handle DAGs directly anymore (unless I
997 am missing something). You have to encode your DAGs in term of
998 communicating process to make the whole scheduling process
999 distributed. Here is an example of how you could do that. Assume T1
1000 has to be done before T2.
1001
1002 \verbatim
1003  int your_agent(int argc, char *argv[] {
1004    ...
1005    T1 = MSG_task_create(...);
1006    T2 = MSG_task_create(...);
1007    ...
1008    while(1) {
1009      ...
1010      if(cond) MSG_task_execute(T1);
1011      ...
1012      if((MSG_task_get_remaining_computation(T1)=0.0) && (you_re_in_a_good_mood))
1013         MSG_task_execute(T2)
1014      else {
1015         /* do something else */
1016      }
1017    }
1018  }
1019 \endverbatim
1020  
1021 If you decide that the distributed part is not that much important and that
1022 DAG is really the level of abstraction you want to work with, then you should
1023 give a try to \ref SD_API.
1024
1025 \subsection faq_MIA_generic Generic features
1026
1027 \subsubsection faq_more_processes Increasing the amount of simulated processes
1028
1029 Here are a few tricks you can apply if you want to increase the amount
1030 of processes in your simulations.
1031
1032  - <b>A few thousands of simulated processes</b> (soft tricks)\n
1033    SimGrid can use either pthreads library or the UNIX98 contextes. On
1034    most systems, the number of pthreads is limited and then your
1035    simulation may be limited for a stupid reason. This is especially
1036    true with the current linux pthreads, and I cannot get more than
1037    2000 simulated processes with pthreads on my box. The UNIX98
1038    contexts allow me to raise the limit to 25,000 simulated processes
1039    on my laptop.\n\n
1040    The <tt>--with-context</tt> option of the <tt>./configure</tt>
1041    script allows you to choose between UNIX98 contextes
1042    (<tt>--with-context=ucontext</tt>) and the pthread version
1043    (<tt>--with-context=pthread</tt>). The default value is ucontext
1044    when the script detect a working UNIX98 context implementation. On
1045    Windows boxes, the provided value is discarded and an adapted
1046    version is picked up.\n\n
1047    We experienced some issues with contextes on some rare systems
1048    (solaris 8 and lower or old alpha linuxes comes to mind). The main
1049    problem is that the configure script detect the contextes as being
1050    functional when it's not true. If you happen to use such a system,
1051    switch manually to the pthread version, and provide us with a good
1052    patch for the configure script so that it is done automatically ;)
1053
1054  - <b>Hundred thousands of simulated processes</b> (hard-core tricks)\n 
1055    As explained above, SimGrid can use UNIX98 contextes to represent
1056    and handle the simulated processes. Thanks to this, the main
1057    limitation to the number of simulated processes becomes the
1058    available memory.\n\n
1059    Here are some tricks I had to use in order to run a token ring
1060    between 25,000 processes on my laptop (1Gb memory, 1.5Gb swap).\n
1061    - First of all, make sure your code runs for a few hundreds
1062      processes before trying to push the limit. Make sure it's
1063      valgrind-clean, ie that valgrind does not report neither memory
1064      error nor memory leaks. Indeed, numerous simulated processes
1065      result in *fat* simulation hindering debugging.
1066    - It was really boring to write 25,000 entries in the deployment
1067      file, so I wrote a little script
1068      <tt>examples/gras/mutual_exclusion/simple_token/make_deployment.pl</tt>, which you may
1069      want to adapt to your case. You could also think about hijacking
1070      the SURFXML parser (have look at \ref faq_flexml_bypassing).
1071    - The deployment file became quite big, so I had to do what is in
1072      the FAQ entry \ref faq_flexml_limit
1073    - Each UNIX98 context has its own stack entry. As debugging this is
1074      quite hairly, the default value is a bit overestimated so that
1075      user don't get into trouble about this. You want to tune this
1076      size to increse the number of processes. This is the
1077      <tt>STACK_SIZE</tt> define in 
1078      <tt>src/xbt/xbt_context_sysv.c</tt>, which is 128kb by default.
1079      Reduce this as much as you can, but be warned that if this value
1080      is too low, you'll get a segfault. The token ring example, which
1081      is quite simple, runs with 40kb stacks.     
1082    - You may tweak the logs to reduce the stack size further.  When
1083      logging something, we try to build the string to display in a
1084      char array on the stack. The size of this array is constant (and
1085      equal to XBT_LOG_BUFF_SIZE, defined in include/xbt/log/h). If the
1086      string is too large to fit this buffer, we move to a dynamically
1087      sized buffer. In which case, we have to traverse one time the log
1088      event arguments to compute the size we need for the buffer,
1089      malloc it, and traverse the argument list again to do the actual
1090      job.\n     
1091      The idea here is to move XBT_LOG_BUFF_SIZE to 1, forcing the logs
1092      to use a dynamic array each time. This allows us to lower further
1093      the stack size at the price of some performance loss...\n
1094      This allowed me to run the reduce the stack size to ... 4k. Ie,
1095      on my 1Gb laptop, I can run more than 250,000 processes!
1096
1097 \subsubsection faq_MIA_batch_scheduler Is there a native support for batch schedulers in SimGrid?
1098
1099 No, there is no native support for batch schedulers and none is
1100 planned because this is a very specific need (and doing it in a
1101 generic way is thus very hard). However some people have implemented
1102 their own batch schedulers. Vincent Garonne wrote one during his PhD
1103 and put his code in the contrib directory of our SVN so that other can
1104 keep working on it. You may find inspiring ideas in it.
1105
1106 \subsubsection faq_MIA_checkpointing I need a checkpointing thing
1107
1108 Actually, it depends on whether you want to checkpoint the simulation, or to
1109 simulate checkpoints. 
1110
1111 The first one could help if your simulation is a long standing process you
1112 want to keep running even on hardware issues. It could also help to
1113 <i>rewind</i> the simulation by jumping sometimes on an old checkpoint to
1114 cancel recent calculations.\n 
1115 Unfortunately, such thing will probably never exist in SG. One would have to
1116 duplicate all data structures because doing a rewind at the simulator level
1117 is very very hard (not talking about the malloc free operations that might
1118 have been done in between). Instead, you may be interested in the Libckpt
1119 library (http://www.cs.utk.edu/~plank/plank/www/libckpt.html). This is the
1120 checkpointing solution used in the condor project, for example. It makes it
1121 easy to create checkpoints (at the OS level, creating something like core
1122 files), and rerunning them on need.
1123
1124 If you want to simulate checkpoints instead, it means that you want the
1125 state of an executing task (in particular, the progress made towards
1126 completion) to be saved somewhere.  So if a host (and the task executing on
1127 it) fails (cf. #MSG_HOST_FAILURE), then the task can be restarted
1128 from the last checkpoint.\n
1129
1130 Actually, such a thing does not exists in SimGrid either, but it's just
1131 because we don't think it is fundamental and it may be done in the user code
1132 at relatively low cost. You could for example use a watcher that
1133 periodically get the remaining amount of things to do (using
1134 MSG_task_get_remaining_computation()), or fragment the task in smaller
1135 subtasks.
1136
1137 \subsection faq_platform Platform building and Dynamic resources
1138
1139 \subsubsection faq_platform_example Where can I find SimGrid platform files?
1140
1141 There is several little examples in the archive, in the examples/msg
1142 directory. From time to time, we are asked for other files, but we
1143 don't have much at hand right now. 
1144
1145 You should refer to the Platform Description Archive
1146 (http://pda.gforge.inria.fr) project to see the other platform file we
1147 have available, as well as the Simulacrum simulator, meant to generate
1148 SimGrid platforms using all classical generation algorithms.
1149
1150 \subsubsection faq_platform_alnem How can I automatically map an existing platform?
1151
1152 We are working on a project called ALNeM (Application-Level Network
1153 Mapper) which goal is to automatically discover the topology of an
1154 existing network. Its output will be a platform description file
1155 following the SimGrid syntax, so everybody will get the ability to map
1156 their own lab network (and contribute them to the catalog project).
1157 This tool is not ready yet, but it move quite fast forward. Just stay
1158 tuned.
1159
1160 \subsubsection faq_platform_synthetic Generating synthetic but realistic platforms
1161
1162 The third possibility to get a platform file (after manual or
1163 automatic mapping of real platforms) is to generate synthetic
1164 platforms. Getting a realistic result is not a trivial task, and
1165 moreover, nobody is really able to define what "realistic" means when
1166 speaking of topology files. You can find some more thoughts on this
1167 topic in these
1168 <a href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
1169
1170 If you are looking for an actual tool, there we have a little tool to
1171 annotate Tiers-generated topologies. This perl-script is in
1172 <tt>tools/platform_generation/</tt> directory of the SVN. Dinda et Al.
1173 released a very comparable tool, and called it GridG.
1174
1175 \subsubsection faq_SURF_dynamic Expressing dynamic resource availability in platform files
1176
1177 A nice feature of SimGrid is that it enables you to seamlessly have
1178 resources whose availability change over time. When you build a
1179 platform, you generally declare hosts like that:
1180
1181 \verbatim
1182   <host id="host A" power="100.00"/>
1183 \endverbatim 
1184
1185 If you want the availability of "host A" to change over time, the only
1186 thing you have to do is change this definition like that:
1187
1188 \verbatim
1189   <host id="host A" power="100.00" availability_file="trace_A.txt" state_file="trace_A_failure.txt"/>
1190 \endverbatim
1191
1192 For hosts, availability files are expressed in fraction of available
1193 power. Let's have a look at what "trace_A.txt" may look like:
1194
1195 \verbatim
1196 PERIODICITY 1.0
1197 0.0 1.0
1198 11.0 0.5
1199 20.0 0.9
1200 \endverbatim
1201
1202 At time 0, our host will deliver 100 flop/s. At time 11.0, it will
1203 deliver only 50 flop/s until time 20.0 where it will will start
1204 delivering 90 flop/s. Last at time 21.0 (20.0 plus the periodicity
1205 1.0), we'll be back to the beginning and it will deliver 100 flop/s.
1206
1207 Now let's look at the state file:
1208 \verbatim
1209 PERIODICITY 10.0
1210 1.0 -1.0
1211 2.0 1.0
1212 \endverbatim
1213
1214 A negative value means "off" while a positive one means "on". At time
1215 1.0, the host is on. At time 1.0, it is turned off and at time 2.0, it
1216 is turned on again until time 12 (2.0 plus the periodicity 10.0). It
1217 will be turned on again at time 13.0 until time 23.0, and so on.
1218
1219 Now, let's look how the same kind of thing can be done for network
1220 links. A usual declaration looks like:
1221
1222 \verbatim
1223   <link id="LinkA" bandwidth="10.0" latency="0.2"/>
1224 \endverbatim
1225
1226 You have at your disposal the following options: bandwidth_file,
1227 latency_file and state_file. The only difference with hosts is that
1228 bandwidth_file and latency_file do not express fraction of available
1229 power but are expressed directly in bytes per seconds and seconds.
1230
1231 \subsubsection faq_platform_multipath How to express multipath routing in platform files?
1232
1233 It is unfortunately impossible to express the fact that there is more
1234 than one routing path between two given hosts. Let's consider the
1235 following platform file:
1236
1237 \verbatim
1238 <route src="A" dst="B">
1239    <link:ctn id="1"/>
1240 </route>
1241 <route src="B" dst="C">
1242   <link:ctn id="2"/>
1243 </route>
1244 <route src="A" dst="C">
1245   <link:ctn id="3"/>
1246 </route>
1247 \endverbatim
1248
1249 Although it is perfectly valid, it does not mean that data traveling
1250 from A to C can either go directly (using link 3) or through B (using
1251 links 1 and 2). It simply means that the routing on the graph is not
1252 trivial, and that data do not following the shortest path in number of
1253 hops on this graph. Another way to say it is that there is no implicit
1254 in these routing descriptions. The system will only use the routes you
1255 declare (such as &lt;route src="A" dst="C"&gt;&lt;link:ctn
1256 id="3"/&gt;&lt;/route&gt;), without trying to build new routes by aggregating
1257 the provided ones.
1258   
1259 You are also free to declare platform where the routing is not
1260 symmetric. For example, add the following to the previous file:
1261
1262 \verbatim
1263 <route src="C" dst="A">
1264   <link:ctn id="2"/>
1265   <link:ctn id="1"/>
1266 </route>
1267 \endverbatim
1268
1269 This makes sure that data from C to A go through B where data from A
1270 to C go directly. Don't worry about realism of such settings since
1271 we've seen ways more weird situation in real settings (in fact, that's
1272 the realism of very regular platforms which is questionable, but
1273 that's another story).
1274
1275 \subsubsection faq_flexml_bypassing Bypassing the XML parser with your own C functions
1276
1277 So you want to bypass the XML files parser, uh? Maybe doing some parameter
1278 sweep experiments on your simulations or so? This is possible, and
1279 it's not even really difficult (well. Such a brutal idea could be
1280 harder to implement). Here is how it goes.
1281
1282 For this, you have to first remember that the XML parsing in SimGrid is done
1283 using a tool called FleXML. Given a DTD, this gives a flex-based parser. If
1284 you want to bypass the parser, you need to provide some code mimicking what
1285 it does and replacing it in its interactions with the SURF code. So, let's
1286 have a look at these interactions.
1287
1288 FleXML parser are close to classical SAX parsers. It means that a
1289 well-formed SimGrid platform XML file might result in the following
1290 "events":
1291
1292   - start "platform_description" with attribute version="2"
1293   - start "host" with attributes id="host1" power="1.0"
1294   - end "host"
1295   - start "host" with attributes id="host2" power="2.0"
1296   - end "host"
1297   - start "link" with ...
1298   - end "link"
1299   - start "route" with ...
1300   - start "link:ctn" with ...
1301   - end "link:ctn"
1302   - end "route"
1303   - end "platform_description"
1304
1305 The communication from the parser to the SURF code uses two means:
1306 Attributes get copied into some global variables, and a surf-provided
1307 function gets called by the parser for each event. For example, the event
1308   - start "host" with attributes id="host1" power="1.0"
1309
1310 let the parser do something roughly equivalent to:
1311 \verbatim
1312   strcpy(A_host_id,"host1");
1313   A_host_power = 1.0;
1314   STag_host();
1315 \endverbatim
1316
1317 In SURF, we attach callbacks to the different events by initializing the
1318 pointer functions to some the right surf functions. Since there can be
1319 more than one callback attached to the same event (if more than one
1320 model is in use, for example), they are stored in a dynar. Example in
1321 workstation_ptask_L07.c:
1322 \verbatim
1323   /* Adding callback functions */
1324   surf_parse_reset_parser();
1325   surfxml_add_callback(STag_surfxml_host_cb_list, &parse_cpu_init);
1326   surfxml_add_callback(STag_surfxml_prop_cb_list, &parse_properties);
1327   surfxml_add_callback(STag_surfxml_link_cb_list, &parse_link_init);
1328   surfxml_add_callback(STag_surfxml_route_cb_list, &parse_route_set_endpoints);
1329   surfxml_add_callback(ETag_surfxml_link_c_ctn_cb_list, &parse_route_elem);
1330   surfxml_add_callback(ETag_surfxml_route_cb_list, &parse_route_set_route);
1331                 
1332   /* Parse the file */
1333   surf_parse_open(file);
1334   xbt_assert1((!surf_parse()), "Parse error in %s", file);
1335   surf_parse_close();
1336 \endverbatim
1337     
1338 So, to bypass the FleXML parser, you need to write your own version of the
1339 surf_parse function, which should do the following:
1340    - Fill the A_<tag>_<attribute> variables with the wanted values
1341    - Call the corresponding STag_<tag>_fun function to simulate tag start
1342    - Call the corresponding ETag_<tag>_fun function to simulate tag end
1343    - (do the same for the next set of values, and loop)
1344
1345 Then, tell SimGrid that you want to use your own "parser" instead of the stock one:
1346 \verbatim
1347   surf_parse = surf_parse_bypass_environment;
1348   MSG_create_environment(NULL);
1349   surf_parse = surf_parse_bypass_application;
1350   MSG_launch_application(NULL);
1351 \endverbatim
1352
1353 A set of macros are provided at the end of
1354 include/surf/surfxml_parse.h to ease the writing of the bypass
1355 functions. An example of this trick is distributed in the file
1356 examples/msg/masterslave/masterslave_bypass.c
1357
1358 \subsection faq_simgrid_configuration Changing SimGrid's behavior
1359
1360 A number of options can be given at runtime to change the default
1361 SimGrid behavior. In particular, you can change the default cpu and
1362 network models...
1363
1364 \subsubsection faq_simgrid_configuration_gtnets Using GTNetS
1365
1366 It is possible to use a packet-level network simulator
1367 instead of the default flow-based simulation. You may want to use such
1368 an approach if you have doubts about the validity of the default model
1369 or if you want to perform some validation experiments. At the moment,
1370 we support the GTNetS simulator (it is still rather experimental
1371 though, so leave us a message if you play with it). 
1372
1373
1374 <i>
1375 To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code 
1376 and build/install it from scratch
1377 </i>
1378
1379  - <b>Download and enter the recent downloaded GTNetS directory</b>
1380
1381  \verbatim
1382  svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
1383  cd GTNetS
1384  \endverbatim
1385
1386
1387  - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
1388
1389  \verbatim
1390  unzip gtnets-current.zip
1391  tar zxvf gtnets-current-patch.tgz 
1392  cd gtnets-current
1393  cat ../00*.patch | patch -p1
1394  \endverbatim
1395
1396   - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
1397
1398   \verbatim
1399   cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
1400   \endverbatim
1401
1402  - <b>Compile GTNetS</b>
1403
1404    Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS. 
1405
1406
1407  \verbatim
1408  ln -sf Makefile.linux Makefile
1409  make depend
1410  make debug
1411  \endverbatim
1412
1413
1414  - <b>NOTE</b> A lot of warnings are expected but the application should compile
1415  just fine. If the makefile insists in compiling some QT libraries
1416  please try a make clean before asking for help.
1417
1418
1419  - <b>To compile optimized version</b>
1420
1421  \verbatim
1422  make opt
1423  \endverbatim
1424
1425
1426  - <b>Installing GTNetS</b>
1427
1428  It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
1429
1430  \verbatim
1431  ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
1432  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<userhome>/usr/lib/libgtnets.so
1433  mkdir /<userhome>/usr/include/gtnets
1434  cp -fr SRC/*.h /<userhome>/usr/include/gtnets
1435  \endverbatim
1436
1437
1438  - <b>Enable GTNetS support in SimGrid</b>
1439
1440    \verbatim
1441    ./configure --with-gtnets=/<userhome>/usr
1442    \endverbatim
1443
1444  - <b>Once you have followed all the instructions for compiling and
1445    installing successfully you can activate this feature at 
1446    runntime with the following options:</b>
1447
1448    \verbatim
1449    cd simgrid/example/msg/
1450    make
1451    make check
1452    \endverbatim
1453
1454
1455  - <b>Or try the GTNetS model dogbone example with</b>
1456
1457  \verbatim
1458  gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
1459  \endverbatim
1460
1461  
1462  A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a>  it is available 
1463
1464
1465  More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
1466
1467
1468  - <b>DISCLAIMER</b>
1469  The patches provided by us worked successfully with GTNetS found 
1470  <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>, 
1471  dated from 12th June 2008. Due to the discontinuing development of
1472  GTNetS it is impossible to precise a version number. We STRONGLY recommend you
1473  to download and install the GTNetS version found in SimGrid repository as explained above.
1474  
1475
1476
1477
1478 \subsubsection faq_simgrid_configuration_alternate_network Using alternative flow models
1479
1480 The default simgrid network model uses a max-min based approach as
1481 explained in the research report
1482 <a href="ftp://ftp.ens-lyon.fr/pub/LIP/Rapports/RR/RR2002/RR2002-40.ps.gz">A Network Model for Simulation of Grid Application</a>.
1483 Other models have been proposed and implemented since then (see for example 
1484 <a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>)
1485 and can be activated at runtime. For example:
1486 \verbatim
1487 ./mycode platform.xml deployment.xml --cfg=workstation_model:compound --cfg=network_model:LV08 -cfg=cpu_model:Cas01
1488 \endverbatim
1489
1490 Possible models for the network are currently "Constant", "CM02",
1491 "LegrandVelho", "GTNets", Reno", "Reno2", "Vegas". Others will
1492 probably be added in the future and many of the previous ones are
1493 experimental and are likely to disappear without notice...
1494
1495 \section faq_troubleshooting Troubleshooting
1496
1497 \subsection faq_trouble_lib_compil SimGrid compilation and installation problems
1498
1499 \subsubsection faq_trouble_lib_config ./configure fails!
1500
1501 We know only one reason for the configure to fail:
1502
1503  - <b>You are using a broken build environment</b>\n
1504    If symptom is that configure complains about gcc not being able to build
1505    executables, you are probably missing the libc6-dev package. Damn Ubuntu.
1506
1507 If you experience other kind of issue, please get in touch with us. We are
1508 always interested in improving our portability to new systems.
1509
1510 \subsubsection faq_trouble_distcheck Dude! "make check" fails on my machine!
1511
1512 Don't assume we never run this target, because we do. Check
1513 http://bob.loria.fr:8010 if you don't believe us.
1514
1515 There is several reasons which may cause the make check to fail on your
1516 machine:
1517
1518  - <b>You are using a broken libc (probably concerning the contextes)</b>.\n
1519    The symptom is that the "make check" fails within the examples/msg directory.\n
1520    By default, SimGrid uses something called ucontexts. This is part of the
1521    libc, but it's quite undertested. For example, some (old) versions of the
1522    glibc on alpha do not implement these functions, but provide the stubs
1523    (which return ENOSYS: not implemented). It may fool our detection mechanism
1524    and leads to segfaults. There is not much we can do to fix the bug.
1525    A workaround is to compile with --with-context=pthread to avoid
1526    ucontext completely. You'll be a bit more limited in the number
1527    of simulated processes you can start concurrently, but 5000
1528    processes is still enough for most purposes, isn't it?\n
1529    This limitation is the reason why we insist on using this piece of ...
1530    software even if it's so troublesome.\n
1531    <b>=> use --with-pthread on AMD64 architecture that do not have an 
1532    ultra-recent libc.</b>
1533    
1534  - <b>There is a bug in SimGrid we aren't aware of</b>.\n
1535    If none of the above apply, please drop us a mail on the mailing list so
1536    that we can check it out. Make sure to read \ref faq_bugrepport
1537    before you do so.
1538
1539 \subsection faq_trouble_compil User code compilation problems
1540
1541 \subsubsection faq_trouble_err_logcat "gcc: _simgrid_this_log_category_does_not_exist__??? undeclared (first use in this function)"
1542
1543 This is because you are using the log mecanism, but you didn't created
1544 any default category in this file. You should refer to \ref XBT_log
1545 for all the details, but you simply forgot to call one of
1546 XBT_LOG_NEW_DEFAULT_CATEGORY() or XBT_LOG_NEW_DEFAULT_SUBCATEGORY().
1547
1548 \subsubsection faq_trouble_pthreadstatic "gcc: undefined reference to pthread_key_create"
1549
1550 This indicates that one of the library SimGrid depends on (libpthread
1551 here) was missing on the linking command line. Dependencies of
1552 libsimgrid are expressed directly in the dynamic library, so it's
1553 quite impossible that you see this message when doing dynamic linking. 
1554
1555 If you compile your code statically (and if you use a pthread version
1556 of SimGrid -- see \ref faq_more_processes), you must absolutely
1557 specify <tt>-lpthread</tt> on the linker command line. As usual, this should
1558 come after <tt>-lsimgrid</tt> on this command line.
1559
1560 \subsection faq_trouble_errors Runtime error messages
1561
1562 \subsubsection faq_flexml_limit "surf_parse_lex: Assertion `next limit' failed."
1563
1564 This is because your platform file is too big for the parser. 
1565
1566 Actually, the message comes directly from FleXML, the technology on top of
1567 which the parser is built. FleXML has the bad idea of fetching the whole
1568 document in memory before parsing it. And moreover, the memory buffer size
1569 must be determined at compilation time.
1570
1571 We use a value which seems big enough for our need without bloating the
1572 simulators footprints. But of course your mileage may vary. In this case,
1573 just edit src/surf/surfxml.l modify the definition of
1574 FLEXML_BUFFERSTACKSIZE. E.g.
1575
1576 \verbatim
1577 #define FLEXML_BUFFERSTACKSIZE 1000000000
1578 \endverbatim
1579
1580 Then recompile and everything should be fine, provided that your version of
1581 Flex is recent enough (>= 2.5.31). If not the compilation process should
1582 warn you.
1583
1584 A while ago, we worked on FleXML to reduce a bit its memory consumption, but
1585 these issues remain. There is two things we should do:
1586
1587   - use a dynamic buffer instead of a static one so that the only limit
1588     becomes your memory, not a stupid constant fixed at compilation time
1589     (maybe not so difficult).
1590   - change the parser so that it does not need to get the whole file in
1591     memory before parsing
1592     (seems quite difficult, but I'm a complete newbe wrt flex stuff).
1593
1594 These are changes to FleXML itself, not SimGrid. But since we kinda hijacked
1595 the development of FleXML, I can grant you that any patches would be really
1596 welcome and quickly integrated.
1597
1598 <b>Update:</b> A new version of FleXML (1.7) was released. Most of the work
1599 was done by William Dowling, who use it in his own work. The good point is
1600 that it now use a dynamic buffer, and that the memory usage was greatly
1601 improved. The downside is that William also changed some things internally,
1602 and it breaks the hack we devised to bypass the parser, as explained in 
1603 \ref faq_flexml_bypassing. Indeed, this is not a classical usage of the
1604 parser, and Will didn't imagine that we may have used (and even documented)
1605 such a crude usage of FleXML. So, we now have to repair the bypassing
1606 functionality to use the lastest FleXML version and fix the memory usage in
1607 SimGrid.
1608
1609 \subsubsection faq_trouble_gras_transport GRAS spits networking error messages
1610
1611 Gras, on real platforms, naturally use regular sockets to communicate. They
1612 are deeply hidden in the gras abstraction, but when things go wrong, you may
1613 get some weird error messages. Here are some example, with the probable
1614 reason:
1615
1616  - <b>Transport endpoint is not connected</b>: several processes try to open
1617    a server socket on the same port number of the same machine. This is
1618    naturally bad and each process should pick its own port number for this.\n
1619    Maybe, you just have some processes remaining from a previous experiment 
1620    on your machine.\n
1621    Killing them may help, but again if you kill -KILL them, you'll have to
1622    wait for a while: they didn't close there sockets properly and the system
1623    needs a while to notice that this port is free again.
1624
1625  - <b>Socket closed by remote side</b>: if the remote process is not
1626    supposed to close the socket at this point, it may be dead.
1627    
1628  - <b>Connection reset by peer</b>: I found this on Internet about this
1629    error. I think it's what's happening here, too:\n   
1630    <i>This basically means that a network error occurred while the client was
1631    receiving data from the server. But what is really happening is that the
1632    server actually accepts the connection, processes the request, and sends
1633    a reply to the client. However, when the server closes the socket, the
1634    client believes that the connection has been terminated abnormally
1635    because the socket implementation sends a TCP reset segment telling the
1636    client to throw away the data and report an error.\n
1637    Sometimes, this problem is caused by not properly closing the
1638    input/output streams and the socket connection. Make sure you close the
1639    input/output streams and socket connection properly. If everything is
1640    closed properly, however, and the problem persists, you can work around
1641    it by adding a one-second sleep before closing the streams and the
1642    socket. This technique, however, is not reliable and may not work on all
1643    systems.</i>\n
1644    Since GRAS sockets are closed properly (repeat after me: there is no bug
1645    in GRAS), it is either that you are closing your sockets on server side
1646    before the client get a chance to read them (use gras_os_sleep() to delay
1647    the server), or the server died awfully before the client got the data.
1648
1649 \subsubsection faq_trouble_errors_big_fat_warning I'm told that my XML files are too old.
1650
1651 The format of the XML platform description files is sometimes
1652 improved. For example, we decided to change the units used in SimGrid
1653 from MBytes, MFlops and seconds to Bytes, Flops and seconds to ease
1654 people exchanging small messages. We also reworked the route
1655 descriptions to allow more compact descriptions.
1656
1657 That is why the XML files are versionned using the 'version' attribute
1658 of the root tag. Currently, it should read:
1659 \verbatim
1660   <platform version="2">
1661 \endverbatim
1662
1663 If your files are too old, you can use the simgrid_update_xml.pl
1664 script which can be found in the tools directory of the archive.
1665
1666 \subsection faq_trouble_valgrind Valgrind-related and other debugger issues
1667
1668 If you don't, you really should use valgrind to debug your code, it's
1669 almost magic.
1670
1671 \subsubsection faq_trouble_vg_longjmp longjmp madness in valgrind
1672
1673 This is when valgrind starts complaining about longjmp things, just like:
1674
1675 \verbatim ==21434== Conditional jump or move depends on uninitialised value(s)
1676 ==21434==    at 0x420DBE5: longjmp (longjmp.c:33)
1677 ==21434==
1678 ==21434== Use of uninitialised value of size 4
1679 ==21434==    at 0x420DC3A: __longjmp (__longjmp.S:48)
1680 \endverbatim
1681
1682 This is the sign that you didn't used the exception mecanism well. Most
1683 probably, you have a <tt>return;</tt> somewhere within a <tt>TRY{}</tt>
1684 block. This is <b>evil</b>, and you must not do this. Did you read the section
1685 about \ref XBT_ex??
1686
1687 \subsubsection faq_trouble_vg_libc Valgrind spits tons of errors about backtraces!
1688
1689 It may happen that valgrind, the memory debugger beloved by any decent C
1690 programmer, spits tons of warnings like the following :
1691 \verbatim ==8414== Conditional jump or move depends on uninitialised value(s)
1692 ==8414==    at 0x400882D: (within /lib/ld-2.3.6.so)
1693 ==8414==    by 0x414EDE9: (within /lib/tls/i686/cmov/libc-2.3.6.so)
1694 ==8414==    by 0x400B105: (within /lib/ld-2.3.6.so)
1695 ==8414==    by 0x414F937: _dl_open (in /lib/tls/i686/cmov/libc-2.3.6.so)
1696 ==8414==    by 0x4150F4C: (within /lib/tls/i686/cmov/libc-2.3.6.so)
1697 ==8414==    by 0x400B105: (within /lib/ld-2.3.6.so)
1698 ==8414==    by 0x415102D: __libc_dlopen_mode (in /lib/tls/i686/cmov/libc-2.3.6.so)
1699 ==8414==    by 0x412D6B9: backtrace (in /lib/tls/i686/cmov/libc-2.3.6.so)
1700 ==8414==    by 0x8076446: xbt_dictelm_get_ext (dict_elm.c:714)
1701 ==8414==    by 0x80764C1: xbt_dictelm_get (dict_elm.c:732)
1702 ==8414==    by 0x8079010: xbt_cfg_register (config.c:208)
1703 ==8414==    by 0x806821B: MSG_config (msg_config.c:42)
1704 \endverbatim
1705
1706 This problem is somewhere in the libc when using the backtraces and there is
1707 very few things we can do ourselves to fix it. Instead, here is how to tell
1708 valgrind to ignore the error. Add the following to your ~/.valgrind.supp (or
1709 create this file on need). Make sure to change the obj line according to
1710 your personnal mileage (change 2.3.6 to the actual version you are using,
1711 which you can retrieve with a simple "ls /lib/ld*.so").
1712
1713 \verbatim {
1714    name: Backtrace madness
1715    Memcheck:Cond
1716    obj:/lib/ld-2.3.6.so
1717    fun:dl_open_worker
1718    fun:_dl_open
1719    fun:do_dlopen
1720    fun:dlerror_run
1721    fun:__libc_dlopen_mode
1722 }\endverbatim
1723
1724 Then, you have to specify valgrind to use this suppression file by passing
1725 the <tt>--suppressions=$HOME/.valgrind.supp</tt> option on the command line.
1726 You can also add the following to your ~/.bashrc so that it gets passed
1727 automatically. Actually, it passes a bit more options to valgrind, and this
1728 happen to be my personnal settings. Check the valgrind documentation for
1729 more information.
1730
1731 \verbatim export VALGRIND_OPTS="--leak-check=yes --leak-resolution=high --num-callers=40 --tool=memcheck --suppressions=$HOME/.valgrind.supp" \endverbatim
1732
1733 \subsubsection faq_trouble_backtraces Truncated backtraces
1734
1735 When debugging SimGrid, it's easier to pass the
1736 --disable-compiler-optimization flag to the configure if valgrind or
1737 gdb get fooled by the optimization done by the compiler. But you
1738 should remove these flag when everything works before going in
1739 production (before launching your 1252135 experiments), or everything
1740 will run only one half of the true SimGrid potential.
1741
1742 \subsection faq_deadlock There is a deadlock in my code!!!
1743
1744 Unfortunately, we cannot debug every code written in SimGrid.  We
1745 furthermore believe that the framework provides ways enough
1746 information to debug such informations yourself. If the textual output
1747 is not enough, Make sure to check the \ref faq_visualization FAQ entry to see
1748 how to get a graphical one.
1749
1750 Now, if you come up with a really simple example that deadlocks and
1751 you're absolutely convinced that it should not, you can ask on the
1752 list. Just be aware that you'll be severely punished if the mistake is
1753 on your side... We have plenty of FAQ entries to redact and new
1754 features to implement for the impenitents! ;)
1755
1756 \subsection faq_surf_network_latency I get weird timings when I play with the latencies.
1757
1758 OK, first of all, remember that units should be Bytes, Flops and
1759 Seconds. If you don't use such units, some SimGrid constants (e.g. the
1760 SG_TCP_CTE_GAMMA constant used in most network models) won't have the
1761 right unit and you'll end up with weird results.
1762
1763 Here is what happens with a single transfer of size L on a link
1764 (bw,lat) when nothing else happens.
1765
1766 \verbatim
1767 0-----lat--------------------------------------------------t
1768 |-----|**** real_bw =min(bw,SG_TCP_CTE_GAMMA/(2*lat)) *****|
1769 \endverbatim
1770
1771 In more complex situations, this min is the solution of a complex
1772 max-min linear system.  Have a look 
1773 <a href="http://lists.gforge.inria.fr/pipermail/simgrid-devel/2006-April/thread.html">here</a>
1774 and read the two threads "Bug in SURF?" and "Surf bug not
1775 fixed?". You'll have a few other examples of such computations. You
1776 can also read "A Network Model for Simulation of Grid Application" by
1777 Henri Casanova and Loris Marchal to have all the details. The fact
1778 that the real_bw is smaller than bw is easy to understand. The fact
1779 that real_bw is smaller than SG_TCP_CTE_GAMMA/(2*lat) is due to the
1780 window-based congestion mechanism of TCP. With TCP, you can't exploit
1781 your huge network capacity if you don't have a good round-trip-time
1782 because of the acks...
1783
1784 Anyway, what you get is t=lat + L/min(bw,SG_TCP_CTE_GAMMA/(2*lat)).
1785
1786   * if I you set (bw,lat)=(100 000 000, 0.00001), you get t =  1.00001 (you fully
1787 use your link)
1788   * if I you set (bw,lat)=(100 000 000, 0.0001),  you get t =  1.0001 (you're on the
1789 limit)
1790   * if I you set (bw,lat)=(100 000 000, 0.001),   you get t = 10.001  (ouch!)
1791
1792 This bound on the effective bandwidth of a flow is not the only thing
1793 that may make your result be unexpected. For example, two flows
1794 competing on a saturated link receive an amount of bandwidth inversely
1795 proportional to their round trip time.
1796
1797 \subsection faq_bugrepport So I've found a bug in SimGrid. How to report it?
1798
1799 We do our best to make sure to hammer away any bugs of SimGrid, but this is
1800 still an academic project so please be patient if/when you find bugs in it.
1801 If you do, the best solution is to drop an email either on the simgrid-user
1802 or the simgrid-devel mailing list and explain us about the issue.  You can
1803 also decide to open a formal bug report using the
1804 <a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">relevant
1805 interface</a>. You need to login on the server to get the ability to submit
1806 bugs. 
1807
1808 We will do our best to solve any problem repported, but you need to help us
1809 finding the issue. Just telling "it segfault" isn't enough. Telling "It
1810 segfaults when running the attached simulator" doesn't really help either.
1811 You may find the following article interesting to see how to repport
1812 informative bug repports:
1813 http://www.chiark.greenend.org.uk/~sgtatham/bugs.html (it is not SimGrid
1814 specific at all, but it's full of good advices).
1815
1816 \author Arnaud Legrand (arnaud.legrand::imag.fr)
1817 \author Martin Quinson (martin.quinson::loria.fr)
1818
1819
1820 */
1821
1822 ******************************************************************
1823 *              OLD CRUFT NOT USED ANYMORE                        *
1824 ******************************************************************
1825
1826
1827 \subsection faq_crosscompile Cross-compiling a Windows DLL of SimGrid from linux
1828
1829 At the moment, we do not distribute Windows pre-compiled version of SimGrid
1830 because the support for this platform is still experimental. We know that
1831 some parts of the GRAS environment do not work, and we think that the others
1832 environments (MSG and SD) have good chances to work, but we didn't test
1833 ourselves. This section explains how we generate the SimGrid DLL so that you
1834 can build it for yourself. First of all, you need to have a version more
1835 recent than 3.1 (ie, a SVN version as time of writting).
1836
1837 In order to cross-compile the package to windows from linux, you need to
1838 install mingw32 (minimalist gnu win32). On Debian, you can do so by
1839 installing the packages mingw32 (compiler), mingw32-binutils (linker and
1840 so), mingw32-runtime.
1841
1842 You can use the VPATH support of configure to compile at the same time for
1843 linux and windows without dupplicating the source nor cleaning the tree
1844 between each. Just run bootstrap (if you use the SVN) to run the autotools.
1845 Then, create a linux and a win directories. Then, type:
1846 \verbatim  cd linux; ../configure --srcdir=.. <usual configure flags>; make; cd ..
1847 cd win;  ../configure --srcdir=.. --host=i586-mingw32msvc <flags>; make; cd ..
1848 \endverbatim
1849 The trick to VPATH builds is to call configure from another directory,
1850 passing it an extra --srcdir argument to tell it where all the sources are.
1851 It will understand you want to use VPATH. Then, the trick to cross-compile
1852 is simply to add a --host argument specifying the target you want to build
1853 for. The i586-mingw32msvc string is what you have to pass to use the mingw32
1854 environment as distributed in Debian.
1855
1856 After that, you can run all make targets from both directories, and test
1857 easily that what you change for one arch does not break the other one. 
1858
1859 It is possible that this VPATH build thing breaks from time to time in the
1860 SVN since it's quite fragile, but it's granted to work in any released
1861 version. If you experience problems, drop us a mail. 
1862
1863 Another possible source of issue is that at the moment, building the
1864 examples request to use the gras_stub_generator tool, which is a compiled
1865 program, not a script. In cross-compilation, you need to cross-execute with
1866 wine for example, which is not really pleasant. We are working on this, but
1867 in the meanwhile, simply don't build the examples in cross-compilation
1868 (<tt>cd src</tt> before running make).
1869     
1870 Program (cross-)compiled with mingw32 do request an extra DLL at run-time to be
1871 usable. For example, if you want to test your build with wine, you should do
1872 the following to put this library where wine looks for DLLs.
1873 \verbatim 
1874 cp /usr/share/doc/mingw32-runtime/mingwm10.dll.gz ~/.wine/c/windows/system/
1875 gunzip ~/.wine/c/windows/system/mingwm10.dll.gz
1876 \endverbatim
1877
1878 The DLL is built in src/.libs, and installed in the <i>prefix</i>/bin directory
1879 when you run make install. 
1880
1881 If you want to use it in a native project on windows, you need to use 
1882 simgrid.dll and mingwm10.dll. For each DLL, you need to build .def file
1883 under linux (listing the defined symbols), and convert it into a .lib file
1884 under windows (specifying this in a way that windows compilers like). To
1885 generate the def files, run (under linux):
1886 \verbatim echo "LIBRARY libsimgrid-0.dll" > simgrid.def
1887 echo EXPORTS >> simgrid.def
1888 nm libsimgrid-0.dll | grep ' T _' | sed 's/.* T _//' >> simgrid.def
1889 nm libsimgrid-0.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> simgrid.def
1890
1891 echo "LIBRARY mingwm10.dll" > mingwm10.def
1892 echo EXPORTS >> mingwm10.def
1893 nm mingwm10.dll | grep ' T _' | sed 's/.* T _//' >> mingwm10.def
1894 nm mingwm10.dll | grep ' D _' | sed 's/.* D _//' | sed 's/$/ DATA/' >> mingwm10.def
1895 \endverbatim
1896
1897 To create the import .lib files, use the <tt>lib</tt> windows tool (from
1898 MSVC) the following way to produce simgrid.lib and mingwm10.lib
1899 \verbatim lib /def:simgrid.def
1900 lib /def:mingwm10.def
1901 \endverbatim
1902
1903 If you happen to use Borland C Builder, the right command line is the
1904 following (note that you don't need any file.def to get this working).
1905 \verbatim implib simgrid.lib libsimgrid-0.dll
1906 implib mingwm10.lib mingwm10.dll
1907 \endverbatim
1908
1909 Then, set the following parameters in Visual C++ 2005:
1910 Linker -> Input -> Additional dependencies = simgrid.lib mingwm10.lib
1911
1912 Just in case you wonder how to generate a DLL from libtool in another
1913 project, we added -no-undefined to any lib*_la_LDFLAGS variables so that
1914 libtool accepts to generate a dynamic library under windows. Then, to make
1915 it true, we pass any dependencies (such as -lws2 under windows or -lpthread
1916 on need) on the linking line. Passing such deps is a good idea anyway so
1917 that they get noted in the library itself, avoiding the users to know about
1918 our dependencies and put them manually on their compilation line. Then we
1919 added the AC_LIBTOOL_WIN32_DLL macro just before AC_PROG_LIBTOOL in the
1920 configure.ac. It means that we exported any symbols which need to be.
1921 Nowadays, functions get automatically exported, so we don't need to load our
1922 header files with tons of __declspec(dllexport) cruft. We only need to do so
1923 for data, but there is no public data in SimGrid so we are good.
1924