Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
9269988742d7c7212150fded0cfbb17e9efe20e7
[simgrid.git] / doc / user_guide / doxygen / install.doc
1 /*! 
2 \page install Installing Simgrid
3
4 \section install_cmake Installing the SimGrid library
5
6 \subsection install_intro Some generality
7
8 \subsubsection install_intro1 What is Cmake?
9
10 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>.
11
12 \subsubsection install_intro2 Why cmake?
13
14 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.
15
16 \subsubsection install_intro3 What cmake need?
17
18 CMake needs some prerequists like :
19
20 For Unix and MacOS:
21   \li make
22   \li perl and libpcre
23   \li c and c++ compiler
24   \li ccmake for graphical used of CMake
25   \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
26
27 On MacOSX some users reported that it is still possible to build with clang, provided that you
28 use at least clang3.0 installed with macport or with xcode. If it fails on you, try to
29  use gcc47.
30 \verbatim
31 port install clang-3.0
32 port install gcc47
33 \endverbatim
34
35 For Windows :
36   \li cmake 2.8 <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
37   \li MinGW <a href="http://sourceforge.net/projects/mingw/files/MinGW/">(download page)</a>
38   \li perl <a href="http://www.activestate.com/activeperl/downloads">(download page)</a>
39   \li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
40
41 Note that if you want change the compiler, you can simply specify the environment variables CC and CXX.
42 \verbatim
43         export CC=gcc-4.4
44         export CXX=g++-4.4
45         export CC=clang
46         export CXX=clang++
47 \endverbatim
48
49 \subsubsection install_cmakeoption1 Liste of options
50
51 \verbatim
52 "cmake -D[name]=[value] ... ./"
53
54 [name]  enable_gtnets           [value] ON/OFF or TRUE/FALSE or 1/0
55         enable_ns3                      ON/OFF or TRUE/FALSE or 1/0
56         enable_lua                      ON/OFF or TRUE/FALSE or 1/0
57         enable_compile_optimizations    ON/OFF or TRUE/FALSE or 1/0
58         enable_compile_warnings         ON/OFF or TRUE/FALSE or 1/0
59         enable_smpi                     ON/OFF or TRUE/FALSE or 1/0
60         enable_maintainer_mode          ON/OFF or TRUE/FALSE or 1/0
61         enable_tracing                  ON/OFF or TRUE/FALSE or 1/0
62         enable_coverage                 ON/OFF or TRUE/FALSE or 1/0
63         enable_memcheck                 ON/OFF or TRUE/FALSE or 1/0
64         enable_model-checking           ON/OFF or TRUE/FALSE or 1/0
65         enable_debug                    ON/OFF or TRUE/FALSE or 1/0
66         enable_jedule                   ON/OFF or TRUE/FALSE or 1/0
67         enable_latency_bound_tracking   ON/OFF or TRUE/FALSE or 1/0
68         enable_lib_static               ON/OFF or TRUE/FALSE or 1/0
69         enable_supernovae               ON/OFF or TRUE/FALSE or 1/0
70         enable_msg_deprecated           ON/OFF or TRUE/FALSE or 1/0
71         enable_print_message            ON/OFF or TRUE/FALSE or 1/0
72         gtnets_path                     <path_to_gtnets_directory>
73         ns3_path                        <path_to_ns3_directory>
74         CMAKE_INSTALL_PREFIX            <path_to_install_directory>
75         pipol_user                      <pipol_username>
76 \endverbatim
77
78 \subsubsection install_cmakeoption2 Options explaination
79
80   \li enable_gtnets : set to true implie that user wants to use gtnets.
81
82   \li enable_ns3 : set to true implie that user wants to use ns3.
83
84   \li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
85
86   \li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
87
88   \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"
89
90   \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.
91
92   \li enable_maintainer_mode : set to true it remakes some files.
93
94   \li enable_tracing : To enable the generation of simulation traces for visualization.
95
96   \li enable_coverage : When set to true this option enable code coverage by setting -fprofile-arcs -ftest-coverage flags.
97
98   \li enable_memcheck : When set to true this option enable tests for memcheck.
99
100   \li enable_model-checking : Enable the model checking when set to true.
101
102   \li enable_debug : If enable_debug is set to 'off' Simgrid compil flag has '-DNDEBUG' option.
103
104   \li enable_jedule : To enable jedule mode, which creates visualizations of task schedules with Simdag.
105
106   \li enable_latency_bound_tracking : Set to on if you want to be warned when communications are limited by round trip time.
107
108   \li enable_lib_static : Enable generated Simgrid and smpi static libraries.
109
110   \li enable_supernovae : Set to true make one file for each lib and compile with those generated files.
111
112   \li enable_msg_deprecated : Simgrid is compiled with msg deprecated functions.
113
114   \li enable_print_message : When set to true configuration print more debug output.
115
116   \li gtnets_path : Path to gtnets install directory (ex /usr)
117
118   \li ns3_path : Path to ns3 install directory (ex /usr)
119
120   \li CMAKE_INSTALL_PREFIX : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
121
122   \li pipol_user : specify your pipol username if you want to use the pipol-remote command.
123
124 \subsubsection install_cmakeoption3 Initialisation
125
126 Those options are initialized the first time you launch "cmake ." whithout specified option.
127
128 \verbatim
129 enable_gtnets                   on
130 enable_lua                      on
131 enable_smpi                     on
132 enable_tracing                  on
133 enable_compile_optimizations    on
134 enable_debug                    on
135 enable_compile_warnings         off
136 enable_maintainer_mode          off
137 enable_coverage                 off
138 enable_memcheck                 off
139 enable_model-checking           off
140 enable_jedule                   off
141 enable_latency_bound_tracking   off
142 enable_lib_static               off
143 CMAKE_INSTALL_PREFIX            /usr/local
144 gtnets_path                     null
145 pipol_user                      null
146 \endverbatim
147
148 \subsubsection install_cmakeoption4 Option's cache and how to reset?
149
150 When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want
151 reset values you just delete this file located to the project directory.
152
153 \subsection install_cmakecompilation Cmake compilation
154
155 \subsubsection install_cmakecompilation1 With command line.
156
157 On Unix or Mac platform:
158
159 \verbatim
160 cmake -D[name]=[value] ... ./
161 make
162 \endverbatim
163
164 On Windows platform:
165
166 \verbatim
167 cmake -G"MinGW Makefiles" -D[name]=[value] ... ./
168 mingw32-make
169 \endverbatim
170
171 \subsubsection install_cmakecompilation2 With ccmake tool.
172
173 \verbatim
174 "ccmake ./"
175 \endverbatim
176 Then follow instructions.
177
178 \subsubsection install_cmakecompilation2bis Build out of source.
179
180 As cmake generate many files used for compilation, we recommand to make a build directory.
181 For examples you can make :
182
183 \verbatim
184 "navarrop@caraja:~/Developments$ cd simgrid/"
185 "navarrop@caraja:~/Developments/simgrid$ mkdir build_directory"
186 "navarrop@caraja:~/Developments/simgrid$ cd build_directory/"
187 "navarrop@caraja:~/Developments/simgrid/build_directory$ cmake ../"
188 "navarrop@caraja:~/Developments/simgrid/build_directory$ make"
189 \endverbatim
190
191 Or complety out of sources :
192
193 \verbatim
194 "navarrop@caraja:~/Developments$ mkdir build_dir"
195 "navarrop@caraja:~/Developments$ cd build_dir/"
196 "navarrop@caraja:~/Developments/build_dir$ cmake ../simgrid/"
197 "navarrop@caraja:~/Developments/build_dir$ make"
198 \endverbatim
199
200 Those two kind of compilation permit to delete files created by compilation easier.
201
202 \subsubsection install_cmakecompilation3 Resume of command line
203
204  \li CMake
205 \verbatim
206 cmake <path>                    configure the project for Unix and Mac
207 cmake -G"MinGW Makefiles" <path>        configure the project for Windows
208 make                            build all targets for Unix and Mac
209 ming32-make                             buill all targets for windows
210 (g)make VERBOSE=1               build all targets and print build command lines
211 make check                      test all targets and summarize
212 make dist                       make the distrib
213 make distcheck                  check the dist (make + make dist + make check)
214 (g)make install                 install the project (doc/ bin/ lib/ include/)
215 (g)make uninstall               uninstall the project (doc/ bin/ lib/ include/)
216 (g)make clean                   clean all targets
217 make simgrid_documentation      Create simgrid documentation
218 \endverbatim
219
220 When the project have been succesfully compiling and build you can make tests.
221
222  \li CTest
223 \verbatim
224 ctest                   launch only tests
225 ctest -D Continuous
226 ctest -D Continuous(Start|Update|Configure|Build)
227 ctest -D Continuous(Test|Coverage|MemCheck|Submit)
228 ctest -D Experimental
229 ctest -D Experimental(Start|Update|Configure|Build)
230 ctest -D Experimental(Test|Coverage|MemCheck|Submit)
231 ctest -D Nightly
232 ctest -D Nightly(Start|Update|Configure|Build)
233 ctest -D Nightly(Test|Coverage|MemCheck|Submit)
234 ctest -D NightlyMemoryCheck
235 \endverbatim
236
237 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>.
238
239 \subsection install_cmakeinstall How to install with cmake?
240
241 \subsubsection install_cmakeinstall1 From Git.
242
243 \verbatim
244 git clone git://scm.gforge.inria.fr/simgrid/simgrid.git simgrid
245 cd simgrid
246 cmake -Denable_maintainer_mode=on -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
247 make
248 make install
249 \endverbatim
250
251 \subsubsection install_cmakeinstall2 From a distrib
252
253 \verbatim
254 wget https://gforge.inria.fr/frs/download.php/28674/simgrid-3.6.1.tar.gz
255 tar xf simgrid-3.6.1.tar.gz
256 cd simgrid-3.6.1
257 cmake -DCMAKE_INSTALL_PREFIX=/home/navarrop/Bureau/install_simgrid ./
258 make
259 make install
260 \endverbatim
261
262
263 \subsection install_cmakehowto How to modified sources files for developers
264
265 \subsubsection install_cmakehowto1 Add an executable or examples.
266
267 If you want make an executable you have to create a CMakeList.txt to the src directory.
268 You must specified where to create the executable, source list, dependencies and the name of the binary.
269
270 \verbatim
271 cmake_minimum_required(VERSION 2.6)
272
273 set(EXECUTABLE_OUTPUT_PATH "./")
274 set(LIBRARY_OUTPUT_PATH "${CMAKE_HOME_DIRECTORY}/lib")
275
276 #add_executable(<name_of_target> <src list>)
277 add_executable(get_sender get_sender.c)
278
279 ### Add definitions for compile
280 #target_link_libraries(<name_of_targe> <dependencies>)
281 target_link_libraries(get_sender simgrid m pthread) 
282 \endverbatim
283
284 Then you have to modified <project/directory>/buildtools/Cmake/MakeExeLib.cmake and add
285 this line :
286 \verbatim
287 add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
288 \endverbatim
289
290 \subsubsection install_cmakehowto2 Delete/add sources to lib.
291
292 If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/DefinePackages.cmake
293
294 \verbatim
295 set(JMSG_JAVA_SRC
296         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/MsgException.java
297         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/JniException.java
298         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/NativeException.java
299         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/HostNotFoundException.java
300         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/ProcessNotFoundException.java
301         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Msg.java
302         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Process.java
303         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Host.java
304         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Task.java
305         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/MsgNative.java
306         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/ApplicationHandler.java
307         ${CMAKE_HOME_DIRECTORY}/src/java/simgrid/msg/Sem.java
308 )
309 \endverbatim
310
311 \section install_Win Installing the SimGrid framework on Windows
312
313 \subsection install_Win_install Installing SimGrid with the automatic installer
314
315 Before start the installation, you need to be sure to have the following dependencies:
316   \li cmake 2.8 <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
317   \li MinGW <a href="http://sourceforge.net/projects/mingw/files/MinGW/">(download page)</a>
318   \li perl <a href="http://www.activestate.com/activeperl/downloads">(download page)</a>
319   \li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
320
321 Then download the package <a href="https://gforge.inria.fr/frs/?group_id=12">SimGrid Installer</a>,
322 execute it and follow instructions.
323
324 \htmlonly
325 <a href="win_install_01.png" border=0><img src="win_install_01.png" border=0></a>
326 \endhtmlonly
327
328 Step 1: Accept the license.
329
330 \htmlonly
331 <a href="win_install_02.png" border=0><img src="win_install_02.png" border=0></a>
332 \endhtmlonly
333
334 Step 2: Select packets to install.
335
336 \htmlonly
337 <a href="win_install_03.png" border=0><img src="win_install_03.png" border=0></a>
338 \endhtmlonly
339
340 Step 3: Choice where to install packets previously selected. Please don't use spaces in path.
341
342 \htmlonly
343 <a href="win_install_04.png" border=0><img src="win_install_04.png" border=0></a>
344 \endhtmlonly
345
346 Step 4: Add CLASSPATH to environment variables.
347
348 \htmlonly
349 <a href="win_install_05.png" border=0><img src="win_install_05.png" border=0></a>
350 \endhtmlonly
351
352 Step 5: Add PATH to environment variables.
353
354 \htmlonly
355 <a href="win_install_06.png" border=0><img src="win_install_06.png" border=0></a>
356 \endhtmlonly
357
358 Step 6: Restart your computer to take in consideration environment variables.
359
360 \subsection install_Win_compile1 Compile a project "HelloWorld"
361
362 In the SimGrid install directroy you should have an HelloWorld project to explain you how to start
363 compiling a source file. There are:
364 \verbatim
365 - HelloWorld.c          The example source file.
366 - CMakeLists.txt        It allows to configure the project.
367 - FindPCRE.cmake        This finds and links to the pcre library (Normally included
368                         into Simgrid directory "GnuWin32").
369 - README                This explaination.
370 \endverbatim
371
372 Now let's compil this example:
373 \li Run windows shell "cmd".
374 \li Open HelloWorld Directory ('cd' command line).
375 \li Create a build directory and change directory. (optional)
376 \li Type 'cmake -G"MinGW Makefiles" \<path_to_HelloWorld_project\>'
377 \li Run mingw32-make
378 \li You should obtain a runnable example ("HelloWorld.exe").
379
380 For compiling your own code you can simply copy the HelloWorld project and rename source name. It will
381 create a target with the same name of the source.
382
383 \subsection install_Win_compile2 How to add and compile a new example
384
385 \li Put your source file into the helloWord directory.
386 \li Edit CMakeLists.txt by removing the Find Targets section and add those two lines into this section
387 \verbatim
388 ################
389 # FIND TARGETS #
390 ################
391 #It creates a target called 'TARGET_NAME.exe' with the sources 'SOURCES'
392 add_executable(TARGET_NAME SOURCES)
393 #Links TARGET_NAME with simgrid and pcre
394 target_link_libraries(TARGET_NAME simgrid pcre)
395 \endverbatim
396 \li To initialize and build your project, you'll need to run
397 \verbatim
398 cmake -G"MinGW Makefiles" \<path_to_HelloWorld_project\>
399 \endverbatim
400 \li Run "mingw32-make"
401 \li You should obtain "TARGET_NAME.exe".
402
403 \subsection install_Win_ruby Setup a virtualbox to use SimGrid-Ruby on windows
404
405 Allan Espinosa made these set of Vagrant rules available so that you
406 can use the SimGrid Ruby bindings in a virtual machine using
407 VirtualBox. Thanks to him for that. You can find his project here:
408 https://github.com/aespinosa/simgrid-vagrant
409
410 \section install_mac Installing the SimGrid framework on Mac OS X
411
412 The Mac OS X system is part of the UNIX familly, but it exibits some
413 specificities that complicate a bit the build of SimGrid. Current
414 versions of SimGrid (3.7.x) can only be build with the GCC Compiler,
415 but recent OS X version provide only an ancient version of that tool
416 in the hope to see the users switch to the LLVM compiler family. The
417 problem is that SimGrid uses internal libraries of GCC, for stack
418 manipulation for example. We are working on removing this dependency
419 onto gcc to ease the build process, but this is still ongoing.
420
421 For the time being, you need to get a recent version of GCC on your
422 system to build SimGrid. Version 3.7.1  was successfully built on Mac
423 Lion 10.7.4 using a GCC compiler retrieved from macport. The package
424 used were gcc47, and the binary in the package were gcc-mp-4.7.
425
426 \section install_setting_MSG Setting up your own MSG code
427
428 Do not build your simulator by modifying the SimGrid examples.  Go
429 outside the SimGrid source tree and create your own working directory
430 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
431
432 Suppose your simulation has the following structure (remember it is
433 just an example to illustrate a possible way to compile everything;
434 feel free to organize it as you want).
435
436 \li <tt>sched.h</tt>: a description of the core of the
437     scheduler (i.e. which functions are can be used by the
438     agents). For example we could find the following functions
439     (master, forwarder, slave).
440 \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
441     implementing the core of the scheduler. Most of these
442     functions use the MSG functions defined in section \ref
443     msg_task_usage.
444 \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
445     the MSG initialization (MSG_init()), the platform
446     creation (e.g. with MSG_create_environment()), the
447     deployment phase (e.g. with MSG_function_register() and
448     MSG_launch_application()) and the call to MSG_main()).
449
450 To compile such a program, we suggest to use the following
451 Makefile. It is a generic Makefile that we have used many times with
452 our students when we teach the C language.
453
454 \verbatim
455 all: masterslave
456 masterslave: masterslave.o sched.o
457
458 INSTALL_PATH = $$HOME
459 CC = gcc
460 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
461                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
462                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
463                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
464                                 -Wpointer-arith -Wwrite-strings -finline-functions
465 REASONABLY_CAREFUL_DUDE =       -Wall
466 NO_PRAYER_FOR_THE_WICKED =      -w -O2
467 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
468 CFLAGS = -g $(WARNINGS)
469
470 INCLUDES = -I$(INSTALL_PATH)/include
471 DEFS = -L$(INSTALL_PATH)/lib/
472 LDADD = -lm -lsimgrid
473 LIBS =
474
475 %: %.o
476         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
477
478 %.o: %.c
479         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
480
481 clean:
482         rm -f $(BIN_FILES) *.o *~
483 .SUFFIXES:
484 .PHONY : clean
485
486 \endverbatim
487
488 The first two lines indicates what should be build when typing make
489 (<tt>masterslave</tt>) and of which files it is to be made of
490 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
491 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
492 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
493 the static version, remove the <tt>-lsimgrid</tt> and add a
494 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
495 after the <tt>LIBS = </tt>.
496
497 More generally, if you have never written a Makefile by yourself, type
498 in a terminal : <tt>info make</tt> and read the introduction. The
499 previous example should be enough for a first try but you may want to
500 perform some more complex compilations...
501
502
503
504 */