Logo AND Algorithmique Numérique Distribuée

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