doc/install.doc

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