Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
551cc08bb963910beb68af580003d48ec3bde59d
[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
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   
33 \subsubsection installSimgrid_cmakeoption1 Liste of options
34
35 \verbatim
36 "cmake -D[name]=[value] ... ./"
37
38 [name]  enable_gtnets           [value] ON/OFF or TRUE/FALSE or 1/0
39         enable_lua                      ON/OFF or TRUE/FALSE or 1/0
40         enable_compile_optimizations    ON/OFF or TRUE/FALSE or 1/0
41         enable_compile_warnings         ON/OFF or TRUE/FALSE or 1/0
42         enable_smpi                     ON/OFF or TRUE/FALSE or 1/0
43         enable_maintainer_mode          ON/OFF or TRUE/FALSE or 1/0
44         enable_supernovae               ON/OFF or TRUE/FALSE or 1/0
45         enable_tracing                  ON/OFF or TRUE/FALSE or 1/0
46         enable_coverage                 ON/OFF or TRUE/FALSE or 1/0
47         enable_memcheck                 ON/OFF or TRUE/FALSE or 1/0
48         enable_model-checking           ON/OFF or TRUE/FALSE or 1/0
49         enable_debug                    ON/OFF or TRUE/FALSE or 1/0
50         enable_jedule                   ON/OFF or TRUE/FALSE or 1/0
51         enable_latency_bound_tracking   ON/OFF or TRUE/FALSE or 1/0
52         enable_lib_static               ON/OFF or TRUE/FALSE or 1/0
53         enable_pcre                     ON/OFF or TRUE/FALSE or 1/0
54         custom_flags                    <flags>
55         gtnets_path                     <path_to_gtnets_directory>
56         CMAKE_INSTALL_PREFIX            <path_to_install_directory>
57         CMAKE_C_COMPILER                <path_to_compiler>
58         CMAKE_CXX_COMPILER              <path_to_compiler>
59         pipol_user                      <pipol_username>
60 \endverbatim
61                                                                                                                                                           
62 \subsubsection installSimgrid_cmakeoption2 Options explaination
63
64   \li enable_gtnets : set to true implie that user wants to use gtnets.
65
66   \li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
67
68   \li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
69
70   \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"
71
72   \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.
73
74   \li enable_maintainer_mode : set to true it remakes some files. 
75
76   \li enable_supernovae : set to true make one file for each lib and compile with those generated files.
77
78   \li enable_tracing : To enable the generation of simulation traces for visualization.
79
80   \li enable_coverage : When set to true this option enable code coverage by setting -fprofile-arcs -ftest-coverage flags.
81
82   \li enable_memcheck : When set to true this option enable tests for memcheck.
83
84   \li enable_model-checking : Enable the model checking when set to true.
85
86   \li enable_debug : If enable_debug is set to 'off' Simgrid compil flag has '-DNDEBUG' option.
87   
88   \li enable_jedule : To enable jedule mode, which creates visualizations of task schedules with Simdag. 
89   
90   \li enable_latency_bound_tracking : Set to on if you want to be warned when communications are limited by round trip time.
91   
92   \li enable_lib_static : Enable generated Simgrid and smpi static libraries.
93   
94   \li enable_pcre : Use or not the pcre lib for memory optimization.    
95   
96   \li custom_flags : If user wants to use a specific flag during compilation, give here.
97
98   \li gtnets_path : Path to gtnets install directory (ex /usr)
99
100   \li CMAKE_INSTALL_PREFIX : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
101   
102   \li CMAKE_C_COMPILER : Change the c compiler.
103   
104   \li CMAKE_CXX_COMPILER : Change the c++ compiler. 
105   
106   \li pipol_user : specify your pipol username if you want to use the pipol-remote command.
107
108 \subsubsection installSimgrid_cmakeoption3 Initialisation
109
110 Those options are initialized the first time you launch "cmake ." whithout specified option.
111
112 \verbatim
113 enable_gtnets                   on
114 enable_lua                      on
115 enable_smpi                     on
116 enable_supernovae               on
117 enable_tracing                  on
118 enable_compile_optimizations    on
119 enable_debug                    on
120 enable_pcre                     on
121 enable_compile_warnings         off
122 enable_maintainer_mode          off
123 enable_coverage                 off
124 enable_memcheck                 off
125 enable_model-checking           off
126 enable_jedule                   off
127 enable_latency_bound_tracking   off 
128 enable_lib_static               off
129 CMAKE_INSTALL_PREFIX            /usr/local
130 custom_flags                    null
131 gtnets_path                     null
132 pipol_user                      null
133 \endverbatim
134
135 \subsubsection installSimgrid_cmakeoption4 Option's cache and how to reset?
136
137 When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want 
138 reset values you just delete this file located to the project directory.
139
140 \subsection installSimgrid_cmakecompilation Cmake compilation
141
142 \subsubsection installSimgrid_cmakecompilation1 With command line.
143
144 On Unix or Mac platform:
145
146 \verbatim
147 cmake -D[name]=[value] ... ./
148 make
149 \endverbatim
150
151 On Windows platform:
152
153 \verbatim
154 cmake -G"Unix Makefiles" -D[name]=[value] ... ./
155 gmake
156 \endverbatim
157
158 \subsubsection installSimgrid_cmakecompilation2 With ccmake tool.
159
160 \verbatim
161 "ccmake ./"
162 \endverbatim
163 Then follow instructions.
164
165 \subsubsection installSimgrid_cmakecompilation2bis Build out of source.
166
167 As cmake generate many files used for compilation, we recommand to make a build directory.
168 For examples you can make :
169
170 \verbatim
171 "navarrop@caraja:~/Developments$ cd simgrid/"
172 "navarrop@caraja:~/Developments/simgrid$ mkdir build_directory"
173 "navarrop@caraja:~/Developments/simgrid$ cd build_directory/"
174 "navarrop@caraja:~/Developments/simgrid/build_directory$ cmake ../"
175 "navarrop@caraja:~/Developments/simgrid/build_directory$ make"
176 \endverbatim
177
178 Or complety out of sources :
179
180 \verbatim
181 "navarrop@caraja:~/Developments$ mkdir build_dir"
182 "navarrop@caraja:~/Developments$ cd build_dir/"
183 "navarrop@caraja:~/Developments/build_dir$ cmake ../simgrid/"
184 "navarrop@caraja:~/Developments/build_dir$ make"
185 \endverbatim
186
187 Those two kind of compilation permit to delete files created by compilation easier.
188
189 \subsubsection installSimgrid_cmakecompilation3 Resume of command line
190
191  \li CMake
192 \verbatim
193 cmake <path>                    configure the project for Unix and Mac
194 cmake -G"Unix Makefiles" <path> configure the project for Windows
195 make                            build all targets for Unix and Mac
196 gmake                           buill all targets for windows
197 (g)make VERBOSE=1               build all targets and print build command lines
198 make check                      test all targets and summarize
199 make dist                       make the distrib
200 make distcheck                  check the dist (make + make dist + make check) 
201 (g)make install                 install the project (doc/ bin/ lib/ include/)
202 (g)make uninstall               uninstall the project (doc/ bin/ lib/ include/)
203 (g)make clean                   clean all targets
204 make simgrid_documentation      Create simgrid documentation
205 \endverbatim
206
207 When the project have been succesfully compiling and build you can make tests.
208
209  \li CTest
210 \verbatim
211 ctest                   launch only tests
212 ctest -D Continuous
213 ctest -D Continuous(Start|Update|Configure|Build)
214 ctest -D Continuous(Test|Coverage|MemCheck|Submit)
215 ctest -D Experimental
216 ctest -D Experimental(Start|Update|Configure|Build)
217 ctest -D Experimental(Test|Coverage|MemCheck|Submit)
218 ctest -D Nightly                                
219 ctest -D Nightly(Start|Update|Configure|Build)
220 ctest -D Nightly(Test|Coverage|MemCheck|Submit)
221 ctest -D NightlyMemoryCheck
222 \endverbatim
223
224 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>.
225
226 \subsection installSimgrid_cmakeinstall How to install with cmake?
227
228 \subsubsection installSimgrid_cmakeinstall1 From Git. 
229
230 \verbatim
231 git clone git://scm.gforge.inria.fr/simgrid/simgrid.git simgrid
232 cd simgrid
233 cmake -Denable_maintainer_mode=on -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
234 make 
235 make install
236 \endverbatim
237
238 \subsubsection installSimgrid_cmakeinstall2 From a distrib
239
240 \verbatim
241 wget https://gforge.inria.fr/frs/download.php/28674/simgrid-3.6.1.tar.gz
242 tar xf simgrid-3.6.1.tar.gz
243 cd simgrid-3.6.1
244 cmake -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
245 make
246 make install
247 \endverbatim
248
249
250 \subsection installSimgrid_cmakehowto How to modified sources files for developers
251
252 \subsubsection installSimgrid_cmakehowto1 Add an executable or examples.
253
254 If you want make an executable you have to create a CMakeList.txt to the src directory. 
255 You must specified where to create the executable, source list, dependencies and the name of the binary.
256
257 \verbatim
258 cmake_minimum_required(VERSION 2.6)
259
260 set(EXECUTABLE_OUTPUT_PATH "./")                        
261 set(LIBRARY_OUTPUT_PATH "${CMAKE_HOME_DIRECTORY}/lib")
262
263 add_executable(get_sender get_sender.c)                                 #add_executable(<name_of_target> <src list>)
264
265 ### Add definitions for compile
266 target_link_libraries(get_sender simgrid m pthread)     #target_link_libraries(<name_of_targe> <dependencies>)
267 \endverbatim
268
269 Then you have to modified <project/directory>/buildtools/Cmake/MakeExeLib.cmake and add 
270 this line :
271 \verbatim
272 add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
273 \endverbatim
274
275 \subsubsection installSimgrid_cmakehowto2 Delete/add sources to lib.
276
277 If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/DefinePackages.cmake
278
279 \verbatim
280 set(JMSG_JAVA_SRC
281         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/MsgException.java
282         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/JniException.java
283         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/NativeException.java
284         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/HostNotFoundException.java
285         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/ProcessNotFoundException.java
286         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Msg.java
287         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Process.java
288         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Host.java
289         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Task.java
290         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/MsgNative.java
291         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/ApplicationHandler.java
292         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Sem.java
293 )
294 \endverbatim
295
296 \section installSimgrid_Win Installing the SimGrid library with Windows pakage
297
298 \subsection installSimgrid_Win_install Installing SimGrid
299
300 Before start the installation, you need to be sure to have the following dependencies:
301   \li cmake 2.8 <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
302   \li perl strawberry <a href="http://www.strawberryperl.com/download/5.12.2.0/strawberry-perl-5.12.2.0.msi">(download page)</a>
303   \li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
304   
305 Then download the package <a href="https://gforge.inria.fr/frs/?group_id=12">SimGrid Installer</a>,
306 execute it and follow instructions.
307
308 \htmlonly
309 <a href="win_install_01.png" border=0><img src="win_install_01.png" width="50%" border=0></a>
310 \endhtmlonly
311
312 Step 1: Accept the license. 
313
314 \htmlonly
315 <a href="win_install_02.png" border=0><img src="win_install_02.png" width="50%" border=0></a>
316 \endhtmlonly
317
318 Step 2: Select packets to install.
319
320 \htmlonly
321 <a href="win_install_03.png" border=0><img src="win_install_03.png" width="50%" border=0></a>
322 \endhtmlonly
323
324 Step 3: Choice where to install packets previously selected. Please don't use spaces in path.
325  
326 \htmlonly
327 <a href="win_install_04.png" border=0><img src="win_install_04.png" width="50%" border=0></a>
328 \endhtmlonly
329
330 Step 4: Restart your computer to take in consideration environment variables.
331
332 \subsection installSimgrid_Win_compile1 Compile a project "HelloWorld"
333
334 In the SimGrid install directroy you should have an HelloWorld project to explain you how to start 
335 compiling a source file. There are:
336 \verbatim
337 - HelloWorld.c          The example source file.
338 - CMakeLists.txt        It allows to configure the project.
339 - FindPCRE.cmake        This finds and links to the pcre library (Normally included into Simgrid directory "GnuWin32").
340 - README                This explaination.
341 \endverbatim
342
343 Now let's compil this example:
344 \li Run "Git bash" (installed with git) or windows shell "cmd".
345 \li Open HelloWorld Directory ('cd' command line).
346 \li Create a build directory and change directory. (optional)
347 \li Type 'cmake -G"Unix Makefiles" \<path_to_HelloWorld_project\>'
348 \li Run gmake
349 \li You should obtain a runnable example ("HelloWorld.exe").
350
351 For compiling your own code you can simply copy the HelloWorld project and rename source name. It will
352 create a target with the same name of the source. 
353
354 \subsection installSimgrid_Win_compile2 How to add and compile a new example
355
356 \li Put your source file into the helloWord directory.
357 \li Edit CMakeLists.txt by removing the Find Targets section and add those two lines into this section
358 \verbatim 
359 ################
360 # FIND TARGETS #
361 ################
362 add_executable(TARGET_NAME SOURCES)             #It creates a target called 'TARGET_NAME.exe' with the sources 'SOURCES'
363 target_link_libraries(TARGET_NAME simgrid pcre) #Links TARGET_NAME with simgrid and pcre
364 \endverbatim    
365 \li To initialize and build your project, you'll need to run
366 \verbatim
367 cmake -G"Unix Makefiles" \<path_to_HelloWorld_project\>
368 \endverbatim
369 \li Run "gmake"
370 \li You should obtain "TARGET_NAME.exe".
371
372 \section installSimgrid_setting_MSG Setting up your own MSG code
373
374 Do not build your simulator by modifying the SimGrid examples.  Go
375 outside the SimGrid source tree and create your own working directory
376 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
377
378 Suppose your simulation has the following structure (remember it is
379 just an example to illustrate a possible way to compile everything;
380 feel free to organize it as you want).
381
382       \li <tt>sched.h</tt>: a description of the core of the
383           scheduler (i.e. which functions are can be used by the
384           agents). For example we could find the following functions
385           (master, forwarder, slave).
386
387       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
388           implementing the core of the scheduler. Most of these
389           functions use the MSG functions defined in section \ref
390           msg_gos_functions.
391
392       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
393           the MSG initialization (MSG_global_init()), the platform
394           creation (e.g. with MSG_create_environment()), the
395           deployment phase (e.g. with MSG_function_register() and
396           MSG_launch_application()) and the call to
397           MSG_main()).
398
399 To compile such a program, we suggest to use the following
400 Makefile. It is a generic Makefile that we have used many times with
401 our students when we teach the C language.
402
403 \verbatim
404 all: masterslave 
405 masterslave: masterslave.o sched.o
406
407 INSTALL_PATH = $$HOME
408 CC = gcc
409 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
410                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
411                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
412                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
413                                 -Wpointer-arith -Wwrite-strings -finline-functions
414 REASONABLY_CAREFUL_DUDE =       -Wall
415 NO_PRAYER_FOR_THE_WICKED =      -w -O2 
416 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
417 CFLAGS = -g $(WARNINGS)
418
419 INCLUDES = -I$(INSTALL_PATH)/include
420 DEFS = -L$(INSTALL_PATH)/lib/
421 LDADD = -lm -lsimgrid 
422 LIBS = 
423
424 %: %.o
425         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@ 
426
427 %.o: %.c
428         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
429
430 clean:
431         rm -f $(BIN_FILES) *.o *~
432 .SUFFIXES:
433 .PHONY : clean
434
435 \endverbatim
436
437 The first two lines indicates what should be build when typing make
438 (<tt>masterslave</tt>) and of which files it is to be made of
439 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
440 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
441 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
442 the static version, remove the <tt>-lsimgrid</tt> and add a
443 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
444 after the <tt>LIBS = </tt>.
445
446 More generally, if you have never written a Makefile by yourself, type
447 in a terminal : <tt>info make</tt> and read the introduction. The
448 previous example should be enough for a first try but you may want to
449 perform some more complex compilations...
450
451 \section installSimgrid_setting_GRAS Setting up your own GRAS code
452
453 If you use the GRAS interface instead of the MSG one, then previous section
454 is not the better source of information. Instead, you should check the GRAS
455 tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
456
457
458
459 */