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 \subsection installSimgrid_Win_compile1 Compile a project "HelloWorld"
 309
 310 In the SimGrid install directroy you should have an HelloWorld project to explain you how to start
 311 compiling a source file. There are:
 312 \verbatim
 313 - HelloWorld.c          The example source file.
 314 - CMakeLists.txt        It allows to configure the project.
 315 - FindPCRE.cmake        This finds and links to the pcre library (Normally included into Simgrid directory "GnuWin32").
 316 - README                This explaination.
 317 \endverbatim
 318
 319 Now let's compil this example:
 320 \li Run "Git bash" (installed with git) or windows shell "cmd".
 321 \li Open HelloWorld Directory ('cd' command line).
 322 \li Create a build directory and change directory. (optional)
 323 \li Type 'cmake -G"Unix Makefiles" \<path_to_HelloWorld_project\>'
 324 \li Run gmake
 325 \li You should obtain a runnable example ("HelloWorld.exe").
 326
 327 For compiling your own code you can simply copy the HelloWorld project and rename source name. It will
 328 create a target with the same name of the source.
 329
 330 \subsection installSimgrid_Win_compile2 How to add and compile a new example
 331
 332 \li Put your source file into the helloWord directory.
 333 \li Edit CMakeLists.txt by removing the Find Targets section and add those two lines into this section
 334 \verbatim
 335 ################
 336 # FIND TARGETS #
 337 ################
 338 add_executable(TARGET_NAME SOURCES)             #It creates a target called 'TARGET_NAME.exe' with the sources 'SOURCES'
 339 target_link_libraries(TARGET_NAME simgrid pcre) #Links TARGET_NAME with simgrid and pcre
 340 \endverbatim
 341 \li To initialize and build your project, you'll need to run
 342 \verbatim
 343 cmake -G"Unix Makefiles" \<path_to_HelloWorld_project\>
 344 \endverbatim
 345 \li Run "gmake"
 346 \li You should obtain "TARGET_NAME.exe".
 347
 348 \section installSimgrid_setting_MSG Setting up your own MSG code
 349
 350 Do not build your simulator by modifying the SimGrid examples.  Go
 351 outside the SimGrid source tree and create your own working directory
 352 (say <tt>/home/joe/SimGrid/MyFirstScheduler/</tt>).
 353
 354 Suppose your simulation has the following structure (remember it is
 355 just an example to illustrate a possible way to compile everything;
 356 feel free to organize it as you want).
 357
 358       \li <tt>sched.h</tt>: a description of the core of the
 359           scheduler (i.e. which functions are can be used by the
 360           agents). For example we could find the following functions
 361           (master, forwarder, slave).
 362
 363       \li <tt>sched.c</tt>: a C file including <tt>sched.h</tt> and
 364           implementing the core of the scheduler. Most of these
 365           functions use the MSG functions defined in section \ref
 366           msg_gos_functions.
 367
 368       \li <tt>masterslave.c</tt>: a C file with the main function, i.e.
 369           the MSG initialization (MSG_global_init()), the platform
 370           creation (e.g. with MSG_create_environment()), the
 371           deployment phase (e.g. with MSG_function_register() and
 372           MSG_launch_application()) and the call to
 373           MSG_main()).
 374
 375 To compile such a program, we suggest to use the following
 376 Makefile. It is a generic Makefile that we have used many times with
 377 our students when we teach the C language.
 378
 379 \verbatim
 380 all: masterslave
 381 masterslave: masterslave.o sched.o
 382
 383 INSTALL_PATH = $$HOME
 384 CC = gcc
 385 PEDANTIC_PARANOID_FREAK =       -O0 -Wshadow -Wcast-align \
 386                                 -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \
 387                                 -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \
 388                                 -Wmissing-noreturn -Wredundant-decls -Wnested-externs \
 389                                 -Wpointer-arith -Wwrite-strings -finline-functions
 390 REASONABLY_CAREFUL_DUDE =       -Wall
 391 NO_PRAYER_FOR_THE_WICKED =      -w -O2
 392 WARNINGS =                      $(REASONABLY_CAREFUL_DUDE)
 393 CFLAGS = -g $(WARNINGS)
 394
 395 INCLUDES = -I$(INSTALL_PATH)/include
 396 DEFS = -L$(INSTALL_PATH)/lib/
 397 LDADD = -lm -lsimgrid
 398 LIBS =
 399
 400 %: %.o
 401         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@
 402
 403 %.o: %.c
 404         $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $<
 405
 406 clean:
 407         rm -f $(BIN_FILES) *.o *~
 408 .SUFFIXES:
 409 .PHONY : clean
 410
 411 \endverbatim
 412
 413 The first two lines indicates what should be build when typing make
 414 (<tt>masterslave</tt>) and of which files it is to be made of
 415 (<tt>masterslave.o</tt> and <tt>sched.o</tt>). This makefile assumes
 416 that you have set up correctly your <tt>LD_LIBRARY_PATH</tt> variable
 417 (look, there is a <tt>LDADD = -lm -lsimgrid</tt>). If you prefer using
 418 the static version, remove the <tt>-lsimgrid</tt> and add a
 419 <tt>$(INSTALL_PATH)/lib/libsimgrid.a</tt> on the next line, right
 420 after the <tt>LIBS = </tt>.
 421
 422 More generally, if you have never written a Makefile by yourself, type
 423 in a terminal : <tt>info make</tt> and read the introduction. The
 424 previous example should be enough for a first try but you may want to
 425 perform some more complex compilations...
 426
 427 \section installSimgrid_setting_GRAS Setting up your own GRAS code
 428
 429 If you use the GRAS interface instead of the MSG one, then previous section
 430 is not the better source of information. Instead, you should check the GRAS
 431 tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
 432
 433
 434
 435 */