doc/doxygen/install.doc

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