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