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