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