Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
bf1f621e3634f7ff55eb673576d21ab4ef923578
[simgrid.git] / doc / installSimgrid.doc
1 /*! \page installSimgrid Install Simgrid
2
3 \htmlinclude .installSimgrid.doc.toc
4
5 \section installSimgrid_cmake Installing the SimGrid library with Cmake (since V3.4)
6
7 \subsection installSimgrid_intro Some generalitty
8
9 \subsubsection installSimgrid_intro1 What is Cmake?
10
11 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>.
12
13 \subsubsection installSimgrid_intro2 Why cmake?
14
15 CMake permits to developers to compil projects on different plateforms. Then many tools are embedded like ctest for making test, a link to cdash for vizualise results but also test coverage and bug reports. 
16
17 \subsubsection installSimgrid_intro3 What cmake need?
18
19 CMake needs some prerequists like :
20
21 For Unix and MacOS:
22   \li make
23   \li perl and libpcre
24   \li c and c++ compiler
25   \li ccmake for graphical used of CMake
26   \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
27
28 For Windows :
29   \li cmake 2.8 <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
30   \li perl strawberry <a href="http://www.strawberryperl.com/download/5.12.2.0/strawberry-perl-5.12.2.0.msi">(download page)</a>
31   \li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
32   \li SimGrid Installer <a href="https://gforge.inria.fr/frs/?group_id=12">(download page)</a>
33   
34 \subsubsection installSimgrid_cmakeoption1 Liste of options
35
36 \verbatim
37 "cmake -D[name]=[value] ... ./"
38
39 [name]  enable_gtnets           [value] ON/OFF or TRUE/FALSE or 1/0
40         enable_lua                      ON/OFF or TRUE/FALSE or 1/0
41         enable_compile_optimizations    ON/OFF or TRUE/FALSE or 1/0
42         enable_compile_warnings         ON/OFF or TRUE/FALSE or 1/0
43         enable_smpi                     ON/OFF or TRUE/FALSE or 1/0
44         enable_maintainer_mode          ON/OFF or TRUE/FALSE or 1/0
45         enable_supernovae               ON/OFF or TRUE/FALSE or 1/0
46         enable_tracing                  ON/OFF or TRUE/FALSE or 1/0
47         enable_coverage                 ON/OFF or TRUE/FALSE or 1/0
48         enable_memcheck                 ON/OFF or TRUE/FALSE or 1/0
49         enable_model-checking           ON/OFF or TRUE/FALSE or 1/0
50         enable_debug                    ON/OFF or TRUE/FALSE or 1/0
51         enable_jedule                   ON/OFF or TRUE/FALSE or 1/0
52         enable_latency_bound_tracking   ON/OFF or TRUE/FALSE or 1/0
53         enable_lib_static               ON/OFF or TRUE/FALSE or 1/0
54         enable_pcre                     ON/OFF or TRUE/FALSE or 1/0
55         custom_flags                    <flags>
56         gtnets_path                     <path_to_gtnets_directory>
57         CMAKE_INSTALL_PREFIX            <path_to_install_directory>
58         pipol_user                      <pipol_username>
59 \endverbatim
60                                                                                                                                                           
61 \subsubsection installSimgrid_cmakeoption2 Options explaination
62
63   \li enable_gtnets : set to true implie that user wants to use gtnets.
64
65   \li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
66
67   \li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
68
69   \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"
70
71   \li enable_smpi : Set to true if you want to use smpi lib. Actually on simgrid v3.4.1 Mac doesn't support lib smpi.
72
73   \li enable_maintainer_mode : set to true it remakes some files. 
74
75   \li enable_supernovae : set to true make one file for each lib and compile with those generated files.
76
77   \li enable_tracing : To enable the generation of simulation traces for visualization.
78
79   \li enable_coverage : When set to true this option enable code coverage by setting -fprofile-arcs -ftest-coverage flags.
80
81   \li enable_memcheck : When set to true this option enable tests for memcheck.
82
83   \li enable_model-checking : Enable the model checking when set to true.
84
85   \li enable_debug : If enable_debug is set to 'off' Simgrid compil flag has '-DNDEBUG' option.
86   
87   \li enable_jedule : To enable jedule mode, which creates visualizations of task schedules with Simdag. 
88   
89   \li enable_latency_bound_tracking : Set to on if you want to be warned when communications are limited by round trip time.
90   
91   \li enable_lib_static : Enable generated Simgrid and smpi static libraries.
92   
93   \li enable_pcre : Use or not the pcre lib for memory optimization.    
94   
95   \li custom_flags : If user wants to use a specific flag during compilation, give here.
96
97   \li gtnets_path : Path to gtnets install directory (ex /usr)
98
99   \li CMAKE_INSTALL_PREFIX : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
100   
101   \li pipol_user : specify your pipol username if you want to use the pipol-remote command.
102
103 \subsubsection installSimgrid_cmakeoption3 Initialisation
104
105 Those options are initialized the first time you launch "cmake ." whithout specified option.
106
107 \verbatim
108 enable_gtnets                   on
109 enable_lua                      on
110 enable_smpi                     on
111 enable_supernovae               on
112 enable_tracing                  on
113 enable_compile_optimizations    on
114 enable_debug                    on
115 enable_pcre                     on
116 enable_compile_warnings         off
117 enable_maintainer_mode          off
118 enable_coverage                 off
119 enable_memcheck                 off
120 enable_model-checking           off
121 enable_jedule                   off
122 enable_latency_bound_tracking   off 
123 enable_lib_static               off
124 CMAKE_INSTALL_PREFIX            /usr/local
125 custom_flags                    null
126 gtnets_path                     null
127 pipol_user                      null
128 \endverbatim
129
130 \subsubsection installSimgrid_cmakeoption4 Option's cache and how to reset?
131
132 When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want 
133 reset values you just delete this file located to the project directory.
134
135 \subsection installSimgrid_cmakecompilation Cmake compilation
136
137 \subsubsection installSimgrid_cmakecompilation1 With command line.
138
139 On Unix or Mac platform:
140
141 \verbatim
142 cmake -D[name]=[value] ... ./
143 make
144 \endverbatim
145
146 On Windows platform:
147
148 \verbatim
149 cmake -G"Unix Makefiles" -D[name]=[value] ... ./
150 gmake
151 \endverbatim
152
153 \subsubsection installSimgrid_cmakecompilation2 With ccmake tool.
154
155 \verbatim
156 "ccmake ./"
157 \endverbatim
158 Then follow instructions.
159
160 \subsubsection installSimgrid_cmakecompilation2bis Build out of source.
161
162 As cmake generate many files used for compilation, we recommand to make a build directory.
163 For examples you can make :
164
165 \verbatim
166 "navarrop@caraja:~/Developments$ cd simgrid/"
167 "navarrop@caraja:~/Developments/simgrid$ mkdir build_directory"
168 "navarrop@caraja:~/Developments/simgrid$ cd build_directory/"
169 "navarrop@caraja:~/Developments/simgrid/build_directory$ cmake ../"
170 "navarrop@caraja:~/Developments/simgrid/build_directory$ make"
171 \endverbatim
172
173 Or complety out of sources :
174
175 \verbatim
176 "navarrop@caraja:~/Developments$ mkdir build_dir"
177 "navarrop@caraja:~/Developments$ cd build_dir/"
178 "navarrop@caraja:~/Developments/build_dir$ cmake ../simgrid/"
179 "navarrop@caraja:~/Developments/build_dir$ make"
180 \endverbatim
181
182 Those two kind of compilation permit to delete files created by compilation easier.
183
184 \subsubsection installSimgrid_cmakecompilation3 Resume of command line
185
186  \li CMake
187 \verbatim
188 cmake <path>                    configure the project for Unix and Mac
189 cmake -G"Unix Makefiles" <path> configure the project for Windows
190 make                            build all targets for Unix and Mac
191 gmake                           buill all targets for windows
192 (g)make VERBOSE=1               build all targets and print build command lines
193 make check                      test all targets and summarize
194 make dist                       make the distrib
195 make distcheck                  check the dist (make + make dist + make check) 
196 (g)make install                 install the project (doc/ bin/ lib/ include/)
197 (g)make uninstall               uninstall the project (doc/ bin/ lib/ include/)
198 (g)make clean                   clean all targets
199 make simgrid_documentation      Create simgrid documentation
200 \endverbatim
201
202 When the project have been succesfully compiling and build you can make tests.
203
204  \li CTest
205 \verbatim
206 ctest                   launch only tests
207 ctest -D Continuous
208 ctest -D Continuous(Start|Update|Configure|Build)
209 ctest -D Continuous(Test|Coverage|MemCheck|Submit)
210 ctest -D Experimental
211 ctest -D Experimental(Start|Update|Configure|Build)
212 ctest -D Experimental(Test|Coverage|MemCheck|Submit)
213 ctest -D Nightly                                
214 ctest -D Nightly(Start|Update|Configure|Build)
215 ctest -D Nightly(Test|Coverage|MemCheck|Submit)
216 ctest -D NightlyMemoryCheck
217 \endverbatim
218
219 If you want to test before make a commit you can simply make "ctest -D Experimental" and then you can visualize results submitted into Cdash. <a href="http://cdash.inria.fr/CDash/index.php?project=Simgrid">(Go to Cdash site)</a>.
220
221 \subsection installSimgrid_cmakeinstall How to install with cmake?
222
223 \subsubsection installSimgrid_cmakeinstall1 From svn. 
224
225 \verbatim
226 cmake -Denable_maintainer_mode=on -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
227 make 
228 make install
229 \endverbatim
230
231 \subsubsection installSimgrid_cmakeinstall2 From a distrib
232
233 \verbatim
234 For version 3.4.1 and 3.4
235         cmake -Dprefix=/home/navarrop/Bureau/install_simgrid ./
236         make
237         make install-simgrid
238 Since version 3.5
239         cmake -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
240         make
241         make install
242 \endverbatim
243
244
245 \subsection installSimgrid_cmakehowto How to modified sources files for developers
246
247 \subsubsection installSimgrid_cmakehowto1 Add an executable or examples.
248
249 If you want make an executable you have to create a CMakeList.txt to the src directory. 
250 You must specified where to create the executable, source list, dependencies and the name of the binary.
251
252 \verbatim
253 cmake_minimum_required(VERSION 2.6)
254
255 set(EXECUTABLE_OUTPUT_PATH "./")                        
256 set(LIBRARY_OUTPUT_PATH "${CMAKE_HOME_DIRECTORY}/lib")
257
258 add_executable(get_sender get_sender.c)                                 #add_executable(<name_of_target> <src list>)
259
260 ### Add definitions for compile
261 target_link_libraries(get_sender simgrid m pthread)     #target_link_libraries(<name_of_targe> <dependencies>)
262 \endverbatim
263
264 Then you have to modified <project/directory>/buildtools/Cmake/MakeExeLib.cmake and add 
265 this line :
266 \verbatim
267 add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
268 \endverbatim
269
270 \subsubsection installSimgrid_cmakehowto2 Delete/add sources to lib.
271
272 If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/DefinePackages.cmake
273
274 \verbatim
275 set(JMSG_JAVA_SRC
276         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/MsgException.java
277         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/JniException.java
278         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/NativeException.java
279         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/HostNotFoundException.java
280         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/ProcessNotFoundException.java
281         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Msg.java
282         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Process.java
283         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Host.java
284         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Task.java
285         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/MsgNative.java
286         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/ApplicationHandler.java
287         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Sem.java
288 )
289 \endverbatim
290
291
292 \section installSimgrid_installation Installing the SimGrid library with Autotools (valid until V3.3.4)
293
294 Many people have been asking me questions on how to use SimGrid. Quite
295 often, the questions were not really about SimGrid but on the
296 installation process. This section is intended to help people that are
297 not familiar with compiling C files under UNIX. If you follow these
298 instructions and still have some troubles, drop an e-mail to
299 <simgrid-user@lists.gforge.inria.fr>.
300
301 \subsection installSimgrid_compiling Compiling SimGrid from a stable archive
302
303 First of all, you need to download the latest version of SimGrid from 
304 <a href="http://gforge.inria.fr/frs/?group_id=12">here</a>.
305 Suppose you have uncompressed SimGrid in some temporary location of
306 your home directory (say <tt>/home/joe/tmp/simgrid-3.0.1 </tt>). The
307 simplest way to use SimGrid is to install it in your home
308 directory. Change your directory to
309 <tt>/home/joe/tmp/simgrid-3.0.1</tt> and type
310
311 \verbatim
312 ./configure --prefix=$HOME
313 make
314 make install
315 \endverbatim
316
317 If at some point, something fails, check the <a href="http://simgrid.gforge.inria.fr/doc/faq.html#faq_trouble_compil">FAQ section</a>. .
318 If it does not help, you can report this problem to the
319 list but, please, avoid sending a laconic mail like "There is a problem. Is it
320 okay?". Send the config.log file which is automatically generated by
321 configure. Try to capture both the standard output and the error output of the
322 <tt>make</tt> command with <tt>script</tt>. There is no way for us to help you
323 without the relevant bits of information.
324
325 Now, the following directory should have been created : 
326
327       \li <tt>/home/joe/doc/simgrid/html/</tt>
328       \li <tt>/home/joe/lib/</tt>
329       \li <tt>/home/joe/include/</tt>
330
331 SimGrid is not a binary, it is a library. Both a static and a dynamic
332 version are available. Here is what you can find if you try a <tt>ls
333 /home/joe/lib</tt>:
334
335 \verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1
336 \endverbatim
337
338 Thus, there is two ways to link your program with SimGrid:
339       \li Either you use the static version, e.g 
340 \verbatim gcc libsimgrid.a -o MainProgram MainProgram.c
341 \endverbatim
342           In this case, all the SimGrid functions are directly
343           included in <tt>MainProgram</tt> (hence a bigger binary).
344       \li Either you use the dynamic version (the preferred method)
345 \verbatim gcc -lsimgrid -o MainProgram MainProgram.c
346 \endverbatim
347           In this case, the SimGrid functions are not included in
348           <tt>MainProgram</tt> and you need to set your environment
349           variable in such a way that <tt>libsimgrid.so</tt> will be
350           found at runtime. This can be done by adding the following
351           line in your .bashrc (if you use bash and if you have
352           installed the SimGrid libraries in your home directory):
353 \verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
354 \endverbatim
355
356 \subsection installSimgrid_compiling_snapshoot SimGrid development snapshots
357
358 We have very high standards on software quality, and we are reluctant releasing
359 a stable release as long as there is still some known bug in the code base. In
360 addition, we added quite an extensive test base, making sure that we correctly
361 test the most important parts of the tool. 
362
363 As an unfortunate conclusion, there may be some time between the stable
364 releases. If you want to benefit from the most recent features we introduced,
365 but don't want to take the risk of an untested version from the SVN, then
366 development snapshots are done for you. 
367
368 These are pre-releases of SimGrid that still fail some tests about features
369 that almost nobody use, or on platforms not being in our core target (which is
370 Linux, Mac, other Unixes and Windows, from the most important to the less
371 one). That means that using this development releases should be safe for most
372 users. 
373
374 These archives can be found on 
375 <a href="http://www.loria.fr/~quinson/Research/SimGrid/">this web page</a>. Once you 
376 got the lastest archive, you can compile it just like any archive (see above).
377
378 \subsection installSimgrid_compiling_svn Compiling SimGrid from the SVN
379
380 The project development takes place in the SVN, where all changes are
381 committed when they happen. Then every once in a while, we make sure that the
382 code quality meets our standard and release an archive from the code in the
383 SVN. We afterward go back to the development in the SVN. So, if you need a
384 recently added feature and can afford some little problem with the stability
385 of the lastest features, you may want to use the SVN version instead of a
386 released one.
387
388 For that, you first need to get the "simgrid" module from
389 <a href="http://gforge.inria.fr/scm/?group_id=12">here</a>. 
390
391 You won't find any <tt>configure</tt> and a few other things
392 (<tt>Makefile.in</tt>'s, documentation, ...) will be missing as well. The
393 reason for that is that all these files have to be regenerated using the
394 latest versions of <tt>autoconf</tt>, <tt>libtool</tt>, <tt>automake</tt>
395 (>1.9) and <tt>doxygen</tt> (>1.4). To generate the <tt>configure</tt> and
396 the <tt>Makefile.in</tt>'s, you just have to launch the <tt>bootstrap</tt>
397 command that resides in the top of the source tree. Then just follow the
398 instructions of Section \ref installSimgrid_compiling.
399
400 We insist on the fact that you really need the latest versions of
401 autoconf, automake and libtool. Doing this step on exotic architectures/systems
402 (i.e. anything different from a recent linux distribution) may be
403 ... uncertain. If you need to compile the SVN version on a machine where all these
404 dependencies are not met, the easiest is to do <tt>make dist</tt> in the SVN
405 directory of another machine where all dependencies are met. It will create an
406 archive you may deploy on other sites just as a regular stable release.
407
408 In summary, the following commands will checkout the SVN, regenerate the
409 configure script and friends, configure SimGrid and build it.
410
411 \verbatim svn checkout svn://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk simgrid
412 cd simgrid
413 ./bootstrap
414 ./configure --enable-maintainer-mode --prefix=<where to install SimGrid>
415 make \endverbatim
416
417 Then, if you want to install SimGrid on the current box, just do:
418 \verbatim make install \endverbatim
419
420 If you want to build an snapshot of the SVN to deploy it on another box (for
421 example because the other machine don't have the autotools), do:
422 \verbatim make dist \endverbatim
423
424 Moreover, you should never call the autotools manually since you must run
425 them in a specific order with specific arguments. Most of the times, the
426 makefiles will automatically call the tools for you. When it's not possible
427 (such as the first time you checkout the SVN), use the ./bootstrap command
428 to call them explicitly.
429
430 \subsection installSimgrid_setting_MSG Setting up your own MSG code
431
432 Do not build your simulator by modifying the SimGrid examples.  Go
433 outside the SimGrid source tree and create your own working directory
434 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
435
436 Suppose your simulation has the following structure (remember it is
437 just an example to illustrate a possible way to compile everything;
438 feel free to organize it as you want).
439
440       \li <tt>sched.h</tt>: a description of the core of the
441           scheduler (i.e. which functions are can be used by the
442           agents). For example we could find the following functions
443           (master, forwarder, slave).
444
445       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
446           implementing the core of the scheduler. Most of these
447           functions use the MSG functions defined in section \ref
448           msg_gos_functions.
449
450       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
451           the MSG initialization (MSG_global_init()), the platform
452           creation (e.g. with MSG_create_environment()), the
453           deployment phase (e.g. with MSG_function_register() and
454           MSG_launch_application()) and the call to
455           MSG_main()).
456
457 To compile such a program, we suggest to use the following
458 Makefile. It is a generic Makefile that we have used many times with
459 our students when we teach the C language.
460
461 \verbatim
462 all: masterslave 
463 masterslave: masterslave.o sched.o
464
465 INSTALL_PATH = $$HOME
466 CC = gcc
467 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
468                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
469                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
470                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
471                                 -Wpointer-arith -Wwrite-strings -finline-functions
472 REASONABLY_CAREFUL_DUDE =       -Wall
473 NO_PRAYER_FOR_THE_WICKED =      -w -O2 
474 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
475 CFLAGS = -g $(WARNINGS)
476
477 INCLUDES = -I$(INSTALL_PATH)/include
478 DEFS = -L$(INSTALL_PATH)/lib/
479 LDADD = -lm -lsimgrid 
480 LIBS = 
481
482 %: %.o
483         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@ 
484
485 %.o: %.c
486         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
487
488 clean:
489         rm -f $(BIN_FILES) *.o *~
490 .SUFFIXES:
491 .PHONY : clean
492
493 \endverbatim
494
495 The first two lines indicates what should be build when typing make
496 (<tt>masterslave</tt>) and of which files it is to be made of
497 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
498 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
499 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
500 the static version, remove the <tt>-lsimgrid</tt> and add a
501 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
502 after the <tt>LIBS = </tt>.
503
504 More generally, if you have never written a Makefile by yourself, type
505 in a terminal : <tt>info make</tt> and read the introduction. The
506 previous example should be enough for a first try but you may want to
507 perform some more complex compilations...
508
509 \subsection installSimgrid_setting_GRAS Setting up your own GRAS code
510
511 If you use the GRAS interface instead of the MSG one, then previous section
512 is not the better source of information. Instead, you should check the GRAS
513 tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
514
515
516
517 */