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