doc/FAQ.doc

   1 /*! \page faq Frequently Asked Questions
   2
   3 \author Arnaud Legrand <arnaud.legrand@imag.fr>
   4
   5 \section faq_installation Installing the SimGrid library
   6
   7 Many people have been asking me questions on how to use SimGrid. Quite
   8 often, the questions were not really about SimGrid but on the
   9 installation process. This section is intended to help people that are
  10 not familiar with compiling C files under UNIX. If you follow these
  11 instructions and still have some troubles, drop me an e-mail.
  12
  13 \subsection faq_compiling Compiling SimGrid
  14
  15 Suppose you have uncompressed SimGrid in some temporary location of
  16 your home directory (say <tt>/home/joe/tmp/simgrid-2.18.2 </tt>). The
  17 simplest way to use SimGrid is to install it in your home
  18 directory. Change your directory to
  19 <tt>/home/joe/tmp/simgrid-2.18.2</tt> and type
  20
  21 \verbatim./configure --prefix=$HOME
  22 make
  23 make install
  24 \endverbatim
  25
  26 If at some point, something fails, you can report me this problem but,
  27 please, avoid sending a laconic mail like "There is a problem. Is it
  28 normal ?". Send me the config.log file which is automatically
  29 generated by configure. Try to capture both the standard output and
  30 the error output of the <tt>make</tt> command. There is no way for me
  31 to help you if you do not give me a little bit of information.
  32
  33 Now, the following directory should have been created :
  34
  35       \li <tt>/home/joe/doc/simgrid/html/</tt>
  36       \li <tt>/home/joe/lib/</tt>
  37       \li <tt>/home/joe/include/</tt>
  38
  39 SimGrid is not a binary, it is a library. Both a static and a dynamic
  40 version are available. Here is what you can find if you try a <tt>ls
  41 /home/joe/lib</tt>:
  42
  43 \verbatim libsimgrid.a  libsimgrid.la  libsimgrid.so  libsimgrid.so.0 libsimgrid.so.0.0.1
  44 \endverbatim
  45
  46 Thus, there is two ways to link your program with SimGrid:
  47       \li Either you use the static version, e.g
  48 \verbatim gcc libsimgrid.a -o MainProgram MainProgram.c
  49 \endverbatim
  50           In this case, all the SimGrid functions are directly
  51           included in <tt>MainProgram</tt> (hence a bigger binary).
  52       \li Either you use the dynamic version (the preferred method)
  53 \verbatim gcc -lsimgrid -o MainProgram MainProgram.c
  54 \endverbatim
  55           In this case, the SimGrid functions are not included in
  56           <tt>MainProgram</tt> and you need to set your environment
  57           variable in such a way that <tt>libsimgrid.so</tt> will be
  58           found at runtime. This can be done by adding the following
  59           line in your .bashrc (if you use bash and if you have
  60           installed the SimGrid libraries in your home directory):
  61 \verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
  62 \endverbatim
  63
  64 \subsection faq_setting Setting up your own code
  65
  66 Do not build your simulator by modifying the SimGrid examples.  Go
  67 outside the SimGrid source tree and create your own working directory
  68 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
  69
  70 Suppose your simulation has the following structure (remember it is
  71 just an example to illustrate a possible way to compile everything;
  72 feel free to organize it as you want).
  73
  74       \li <tt>sched.h</tt>: a description of the core of the
  75           scheduler (i.e. which functions are can be used by the
  76           agents). For example we could find the following functions
  77           (master, forwarder, slave).
  78
  79       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
  80           implementing the core of the scheduler. Most of these
  81           functions use the MSG functions defined in section \ref
  82           msg_gos_functions.
  83
  84       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
  85           the MSG initialization (MSG_global_init()), the platform
  86           creation (e.g. with MSG_create_environment()), the
  87           deployment phase (e.g. with MSG_function_register() and
  88           MSG_launch_application()) and the call to
  89           MSG_main()).
  90
  91 To compile such a program, I suggest to use the following Makefile. It
  92 is a generic Makefile that I generally use with my students when I
  93 teach the C language.
  94
  95 \verbatim
  96 all: masterslave
  97 masterslave: masterslave.o sched.o
  98
  99 INSTALL_PATH = $$HOME
 100 CC = gcc
 101 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
 102                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
 103                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
 104                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
 105                                 -Wpointer-arith -Wwrite-strings -finline-functions
 106 REASONABLY_CAREFUL_DUDE =       -Wall
 107 NO_PRAYER_FOR_THE_WICKED =      -w -O2
 108 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
 109 CFLAGS = -g $(WARNINGS)
 110
 111 INCLUDES = -I$(INSTALL_PATH)/include
 112 DEFS = -L$(INSTALL_PATH)/lib/
 113 LDADD = -lm -lsimgrid
 114 LIBS =
 115
 116 %: %.o
 117         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
 118
 119 %.o: %.c
 120         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
 121
 122 clean:
 123         rm -f $(BIN_FILES) *.o *~
 124 .SUFFIXES:
 125 .PHONY : clean
 126
 127 \endverbatim
 128
 129 The first two lines indicates what should be build when typing make
 130 (<tt>masterslave</tt>) and of which files it is to be made of
 131 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
 132 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
 133 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
 134 the static version, remove the <tt>-lsimgrid</tt> and add a
 135 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
 136 after the <tt>LIBS = </tt>.
 137
 138 More generally, if you have never written a Makefile by yourself, type
 139 in a terminal : <tt>info make</tt> and read the introduction. The
 140 previous example should be enough for a first try but you may want to
 141 perform some more complex compilations...
 142
 143 \section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start ?
 144
 145 You are at the right place... Having a look to these <a
 146 href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>
 147 may give you some insights on what SimGrid can help you to do and what
 148 are its limitations. Then you definitely should read the \ref
 149 MSG_examples.
 150
 151 \subsection faq_generic Building a generic simulator
 152
 153 Please read carefully the \ref MSG_examples.
 154
 155    \li Start by reading \ref masterslave1.c. It is the most
 156        complicated example since all the platform and all the
 157        deployment are done directly in the code.
 158
 159    \li As you may notice, building a big platform with functions like
 160        MSG_host_create() and MSG_link_create() is quite boring. That
 161        is why it is possible to import a complex platform with
 162        MSG_create_environment(). Have a look at \ref masterslave2.c
 163        and look at the differences with the previous version.
 164
 165    \li Now, deploying your application on an extern platform is not
 166        really convenient either. Having an external way of specifying
 167        which agents should be run on which machine would be much more
 168        convenient. That is why MSG_launch_application() has been
 169        designed for. Have a look at \ref masterslave3.c and look at
 170        the differences with the previous versions. Much more clean and
 171        simple, isnt'it ? In fact, all the complexity of the deployment
 172        that was in the test_all function of \ref masterslave1.c has
 173        been moved to more generic functions : unix_emitter() and
 174        unix_receiver().
 175
 176 \subsection faq_examples I want some more complex examples !
 177
 178 Many people have come to ask me a more complex example and each time,
 179 they have realized afterward that the basics were in the previous three
 180 examples.
 181
 182 Of course they have often been needing more complex functions like
 183 MSG_process_suspend(), MSG_process_resume() and
 184 MSG_process_isSuspended() (to perform synchronization), or
 185 MSG_task_Iprobe() and MSG_process_sleep() (to avoid blocking
 186 receptions), or even MSG_process_create() (to design asynchronous
 187 communications or computations). But the examples are sufficient to
 188 start.
 189
 190 I know I should add some more examples, but not some more complex
 191 ones... I should add some examples that illustrate some other
 192 functionalities (like how to simply encode asynchronous
 193 communications, RPC, process migrations, thread synchronization, ...)
 194 and I will do it when I will have a little bit more time. I have tried
 195 to document the examples so that they are understandable. I know it is
 196 not really satisfying but it is the best I have managed to do yet.
 197
 198 \subsection faq_platform Building a realistic platform
 199
 200 I can speak more than an hour on this subject and I still do not have
 201 the right answer, just some ideas. You can read the following <a
 202 href="http://graal.ens-lyon.fr/~alegrand/articles/Simgrid-Introduction.pdf">slides</a>.
 203 It may give you some hints. You can also have a look at the
 204 <tt>tools/platform_generation/</tt> directory. There is a perl-script
 205 I use to annotate a Tiers generated platform (may not be up-to-date
 206 though).
 207
 208 \subsection faq_visualization Visualizing the schedule
 209
 210 It is sometime convenient to "see" how the agents are behaving. If you
 211 like colors, you can use <tt>tools/colorize.pl</tt> as a filter to you
 212 MSG outputs. It is intended to work with the output generated by
 213 PRINT_MESSAGE() (a macro defined in
 214 <tt>example/msg/messages.h</tt>). Beware, PRINT_MESSAGE() prints on
 215 stderr. Do not forget to redirect if you want to filter (e.g. with
 216 bash):
 217 \verbatim ./masterslave3 platform.txt deployment.txt 2>&1 | ../../tools/colorize.pl \endverbatim
 218
 219 That would be great to have something more graphical. As soon as I'll
 220 have a little bit more time, I will write a piece of code that
 221 generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
 222
 223 \subsection faq_context I have tons of process and it is limiting my simulation.
 224
 225 MSG can use either pthreads or the GNU context library. On most
 226 systems, the number of pthreads is limited (especially with the
 227 current linux pthreads) and then your simulation may be limited for a
 228 stupid reason. If you enable the context option
 229 (<tt>--enable-context</tt> in the <tt>./configure</tt> phase), you
 230 will not use the pthread anymore and the context switching will be
 231 done manually, which enables us to have as much agents as your memory
 232 can hold and should be much faster... So think about it if your
 233 simulation is getting really big.
 234
 235 Nevertheless, be aware that this code does not work on some system. It
 236 is not very clean. As usual, as soon as I will have a little bit more
 237 time, I will recode it in a cleaner way.
 238
 239 \section faq_stupid Stupid Questions
 240
 241 \subsection faq_GridSim Are SimGrid and GridSim the same ?
 242
 243 Are you kidding ? SimGrid is plain C and GridSim is written in
 244 Java... I'm sarcastic but I'm pissed of all these poeple arguing that
 245 their software is well-structured and higly portable thanks to Java. A
 246 C program can also be structured in an object-oriented way and be
 247 highly portable (just try to run Java on IRIX... ;).
 248
 249 According to different published papers, both SimGrid and GridSim seem
 250 to have the same kind of goal but I have never succeeded in compiling
 251 GridSim (but I may not be very objective since I always have troubles
 252 when trying to run java programs) and its documentation has not
 253 enlightened me. If you have suceeded and can tell me more about it,
 254 please tell me.
 255
 256 \subsection faq_stupid_MSG What is MSG and why do you like it ?
 257
 258 Monosodium glutamate (MSG) is used as a flavor enhancer in a variety
 259 of foods prepared at home, in restaurants, and by food processors. Its
 260 use has become controversial in the past 30 years because of reports of
 261 adverse reactions in people who've eaten foods that contain MSG. Research
 262 on the role of glutamate--a group of chemicals that includes MSG--in the
 263 nervous system also has raised questions about the chemical's safety.
 264
 265 For more information, see http://www.truthinlabeling.org/ or
 266 http://www.msg.net/
 267
 268 It also stands for Meta-SimgGrid. It is a simulator written on top of
 269 Simgrid that can be used to easily simulate many process running on a
 270 computing platform.
 271
 272 I also like it because it gives flavor and it's addictive. ;)
 273
 274 */