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