doc/install.doc

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