\section faq_simgrid I'm new to SimGrid. I have some questions. Where should I start?
-You are at the right place... Having a look to these
+You are at the right place... Having a look to these
<a href="http://www.loria.fr/~quinson/articles/simgrid-tutorial.pdf">the tutorial slides</a>
(or to these <a href="http://graal.ens-lyon.fr/~alegrand/articles/slides_g5k_simul.pdf">old slides</a>,
or to these
./msg_test small_platform.xml small_deployment.xml 2>&1 | ../../tools/MSG_visualization/colorize.pl
\endverbatim
-We also have a more graphical output. Have a look at MSG_paje_output(). It
-generates an input to <a href="http://www-id.imag.fr/Logiciels/paje/">Paje</a>.
-<center>
-\htmlonly
- <a href="Paje_MSG_screenshot.jpg"><img src="Paje_MSG_screenshot_thn.jpg"></a>
-\endhtmlonly
-</center>
-
-Visualization with Paje can be seen as a kind of postmortem
-analysis. However, as soon as you start playing with big simulations,
-you'll realize that processing such output is kind of tricky. There is
-so much generic information that it is hard to find the information
-you are looking for.
-
-As a matter of fact, logging really depends on simulations (e.g. what
-kind of events is important...). That is why we do not propose a big
-dump of your whole simulation (it would slow everything down) but give
-you neat tools to structure you logs. Have a look at \ref XBT_log. In
-fact, rather than a post-mortem analysis, you may want to do it on the
-fly. The process you are running can do whatever you want. Have you
-thought about adding a global structure where you directly compute the
-information that are really important rather than writing everything
-down and then processing huge files?
+We also have a more graphical output. Have a look at section \ref faq_tracing.
\subsection faq_C Argh! Do I really have to code in C?
fast forward [2006/05/13]. More languages are evaluated, but for now,
we do not feel a real demand for any other language. Please speak up!
-\section faq_installation Installing the SimGrid library
+\section faq_cmake Installing the SimGrid library with Cmake (since V3.4)
+
+\subsection faq_intro Some generalitty
+
+\subsubsection faq_intro1 What is Cmake?
+
+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>.
+
+\subsubsection faq_intro2 Why cmake?
+
+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.
+
+\subsubsection faq_intro3 What cmake need?
+
+CMake needs some prerequists like :
+ \li make
+ \li c, c++ and java compiler regards to developers
+ \li ccmake for graphical used of CMake
+ \li cmake <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
+
+\subsubsection faq_cmakeoption1 Liste of options
+
+\verbatim
+"cmake -D[name]=[value] ... ./"
+
+[name] enable_gtnets [value] ON/OFF or TRUE/FALSE or 1/0
+ enable_java ON/OFF or TRUE/FALSE or 1/0
+ enable_lua ON/OFF or TRUE/FALSE or 1/0
+ enable_ruby ON/OFF or TRUE/FALSE or 1/0
+ enable_compile_optimizations ON/OFF or TRUE/FALSE or 1/0
+ enable_compile_warnings ON/OFF or TRUE/FALSE or 1/0
+ enable_smpi ON/OFF or TRUE/FALSE or 1/0
+ enable_maintainer_mode ON/OFF or TRUE/FALSE or 1/0
+ enable_supernovae ON/OFF or TRUE/FALSE or 1/0
+ enable_tracing ON/OFF or TRUE/FALSE or 1/0
+ enable_coverage ON/OFF or TRUE/FALSE or 1/0
+ enable_memcheck ON/OFF or TRUE/FALSE or 1/0
+ enable_model-checking ON/OFF or TRUE/FALSE or 1/0
+ enable_doc ON/OFF or TRUE/FALSE or 1/0
+ gtnets_path <path_to_gtnets_directory>
+ prefix <path_to_install_directory>
+ BIBTEX2HTML <path_to_bibtex2html>
+ with_context auto/ucontext/pthread/window
+ pipol_user <pipol_username>
+\endverbatim
+
+\subsubsection faq_cmakeoption2 Options explaination
+
+ \li enable_gtnets : set to true implie that user wants to use gtnets.
+
+ \li enable_java : set to true implie that user wants to add java langage into simgrid compilation.
+
+ \li enable_lua : set to true implie that user wants to add lua langage into simgrid compilation.
+
+ \li enable_ruby : set to true implie that user wants to add ruby langage into simgrid compilation.
+
+ \li enable_compile_optimizations : add flags "-O3 -finline-functions -funroll-loops -fno-strict-aliasing"
+
+ \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"
+
+ \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.
+
+ \li enable_maintainer_mode : set to true it remakes some files.
+
+ \li enable_supernovae : set to true make one file for each lib and compile with those generated files.
+
+ \li enable_tracing : To enable the generation of simulation traces for visualization
+
+ \li enable_coverage : When set to true this option enable code coverage by setting -fprofile-arcs -ftest-coverage flags.
+
+ \li enable_memcheck : When set to true this option enable tests for memcheck.
+
+ \li enable_model-checking : Enable the model checking when set to true.
+
+ \li enable_doc : Generate the documentation for simgrid with make command. (You can also make the doc manually with command : make html)
+
+ \li gtnets_path : Path to gtnets install directory (ex /usr)
+
+ \li prefix : Path where are installed lib/ doc/ and include/ directories (ex /usr/local)
+
+ \li BIBTEX2HTML : Path where is installed bibtex2html.
+
+ \li with context : specify which context the user wants to use.
+
+ \li pipol_user : specify your pipol username if you want to use the pipol-remote command.
+
+\subsubsection faq_cmakeoption3 Initialisation
+
+Those options are initialized the first time you launch "cmake ." whithout specified option.
+
+\verbatim
+enable_gtnets on
+enable_lua on
+enable_ruby on
+enable_java off
+enable_compile_optimizations off
+enable_compile_warnings off
+enable_smpi on
+enable_maintainer_mode off
+enable_supernovae off
+enable_tracing off
+enable_coverage off
+enable_memcheck off
+enable_model-checking off
+enable_doc off
+
+gtnets_path null
+prefix null
+BIBTEX2HTML null
+with_context auto
+pipol_user null
+\endverbatim
+
+\subsubsection faq_cmakeoption4 Option's cache and how to reset?
+
+When options have been set they are keep into a cache file named "CMakeCache.txt". So if you want
+reset values you just delete this file located to the project directory.
+
+\subsection faq_cmakecompilation Cmake compilation
+
+\subsubsection faq_cmakecompilation1 With command line.
+
+\verbatim
+cmake -D[name]=[value] ... ./
+make
+\endverbatim
+
+\subsubsection faq_cmakecompilation2 With ccmake tool.
+
+\verbatim
+"ccmake ./"
+\endverbatim
+Then follow instructions.
+
+\subsubsection faq_cmakecompilation2bis Build out of source.
+
+As cmake generate many files used for compilation, we recommand to make a build directory.
+For examples you can make :
+
+\verbatim
+"navarrop@caraja:~/Developments$ cd simgrid/"
+"navarrop@caraja:~/Developments/simgrid$ mkdir build_directory"
+"navarrop@caraja:~/Developments/simgrid$ cd build_directory/"
+"navarrop@caraja:~/Developments/simgrid/build_directory$ cmake ../"
+"navarrop@caraja:~/Developments/simgrid/build_directory$ make"
+\endverbatim
+
+Or complety out of sources :
+
+\verbatim
+"navarrop@caraja:~/Developments$ mkdir build_dir"
+"navarrop@caraja:~/Developments$ cd build_dir/"
+"navarrop@caraja:~/Developments/build_dir$ cmake ../simgrid/"
+"navarrop@caraja:~/Developments/build_dir$ make"
+\endverbatim
+
+Those two kind of compilation permit to delete files created by compilation easier.
+
+\subsubsection faq_cmakecompilation3 Resume of command line
+
+ \li CMake
+\verbatim
+cmake <path> configure the project
+make build all targets
+make VERBOSE=1 build all targets and print build command lines
+make check test all targets and summarize
+make dist make the distrib
+make distcheck check the dist (make + make dist + make check)
+make install install the project (doc/ lib/ include/)
+make uninstall uninstall the project (doc/ lib/ include/)
+make clean clean all targets
+make java-clean clean files created by java option
+make doc-clean clean files created for making doc
+make supernovae-clean clean supernovae files
+make maintainer-clean clean maintainer files
+make all-clean execute the 5 upper clean command
+make html Create simgrid documentation
+\endverbatim
+
+When the project have been succesfully compiling and build you can make tests.
+
+ \li CTest
+\verbatim
+ctest launch only tests
+ctest -D Continuous
+ctest -D Continuous(Start|Update|Configure|Build)
+ctest -D Continuous(Test|Coverage|MemCheck|Submit)
+ctest -D Experimental
+ctest -D Experimental(Start|Update|Configure|Build)
+ctest -D Experimental(Test|Coverage|MemCheck|Submit)
+ctest -D Nightly
+ctest -D Nightly(Start|Update|Configure|Build)
+ctest -D Nightly(Test|Coverage|MemCheck|Submit)
+ctest -D NightlyMemoryCheck
+\endverbatim
+
+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>.
+
+\subsubsection faq_cmakecompilation5 Examples for different mode.
+
+\li Mode maintainer
+
+cmake -Denable_maintainer_mode=on ./
+\verbatim
+-- lookign for config.h
+with_context auto change to ucontext
+GIT_DATE : 2010-05-04~09-59-15
+GIT_VERSION : 53ec816
+GIT_SVN_VERSION : 7669
+
+Configuration of package `simgrid' (revision 7669) on arch (=4):
+ BUILDNAME : UCONTEXT
+ SITE : Linux_2.6.31-21-generic_x86_64
+ Release : simgrid-3.4~rev7669
+
+ Compiler: c++ : /usr/bin/c++
+ version: c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
+ Compiler: c : /usr/bin/gcc
+ version: gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
+
+ CFlags : -I/usr/lib/ruby/1.8/x86_64-linux -I/usr/include/lua5.1 -g3
+ CPPFlags:
+ LDFlags : -L/usr/lib/
+
+ Context backend: ucontext
+ Compile Gtnets : 0
+ Gtnets path :
+ Compile Java : 0
+ Compile Lua : 1
+ Compile Ruby : 1
+
+ Compile Smpi : ON
+ Maintainer mode: ON
+ Supernovae mode: OFF
+ Tracing mode : OFF
+
+ Simgrid dependencies: -lm -lruby1.8 -module -ldl -llua5.1 -lrt
+ Gras dependencies : -lm -lpthread -lrt
+ Smpi dependencies :
+
+ INSTALL_PREFIX: /usr/local
+
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/navarrop/Developments/simgrid
+\endverbatim
+
+\li Mode supernovae
+
+cmake -Dsupernovae=on ./
+\verbatim
+-- lookign for config.h
+with_context auto change to ucontext
+GIT_DATE : 2010-05-04~09-59-15
+GIT_VERSION : 53ec816
+GIT_SVN_VERSION : 7669
+
+Configuration of package `simgrid' (revision 7669) on arch (=4):
+ BUILDNAME : SUPERNOVAE
+ SITE : Linux_2.6.31-21-generic_x86_64
+ Release : simgrid-3.4~rev7669
+
+ Compiler: c++ : /usr/bin/c++
+ version: c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
+ Compiler: c : /usr/bin/gcc
+ version: gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
+
+ CFlags : -O3 -finline-functions -funroll-loops -fno-strict-aliasing -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 -I/usr/lib/ruby/1.8/x86_64-linux -I/usr/include/lua5.1 -g3
+ CPPFlags:
+ LDFlags : -L/usr/lib/
+
+ Context backend: ucontext
+ Compile Gtnets : 0
+ Gtnets path :
+ Compile Java : 0
+ Compile Lua : 1
+ Compile Ruby : 1
+
+ Compile Smpi : ON
+ Maintainer mode: OFF
+ Supernovae mode: OFF
+ Tracing mode : OFF
+
+ Simgrid dependencies: -lm -lruby1.8 -module -ldl -llua5.1 -lrt
+ Gras dependencies : -lm -lpthread -lrt
+ Smpi dependencies :
+
+ INSTALL_PREFIX: /usr/local
+
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/navarrop/Developments/simgrid
+
+\endverbatim
+
+\li Mode GTnetS
+
+cmake -Dgtnets_path=/home/navarrop/Bureau/usr/ ./
+\verbatim
+-- lookign for config.h
+with_context auto change to ucontext
+GIT_DATE : 2010-05-04~09-59-15
+GIT_VERSION : 53ec816
+GIT_SVN_VERSION : 7669
+
+Configuration of package `simgrid' (revision 7669) on arch (=4):
+ BUILDNAME : GTNETS
+ SITE : Linux_2.6.31-21-generic_x86_64
+ Release : simgrid-3.4~rev7669
+
+ Compiler: c++ : /usr/bin/c++
+ version: c++ (Ubuntu 4.4.1-4ubuntu9) 4.4.1
+ Compiler: c : /usr/bin/gcc
+ version: gcc (Ubuntu 4.4.1-4ubuntu9) 4.4.1
+
+ CFlags : -O3 -finline-functions -funroll-loops -fno-strict-aliasing -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 -I/usr/lib/ruby/1.8/x86_64-linux -L/usr/lib -I/usr/include/gtnets -I/usr/include/lua5.1 -g3
+ CPPFlags: -L/usr/lib -I/usr/include/gtnets
+ LDFlags : -L/usr/lib/
+
+ Context backend: ucontext
+ Compile Gtnets : 1
+ Gtnets path : /usr
+ Compile Java : 0
+ Compile Lua : 1
+ Compile Ruby : 1
+
+ Compile Smpi : ON
+ Maintainer mode: OFF
+ Supernovae mode: OFF
+ Tracing mode : OFF
+
+ Simgrid dependencies: -lm -lruby1.8 -module -ldl -llua5.1 -lgtnets -lrt
+ Gras dependencies : -lm -lpthread -lrt
+ Smpi dependencies :
+
+ INSTALL_PREFIX: /usr/local
+
+-- Configuring done
+-- Generating done
+-- Build files have been written to: /home/navarrop/Developments/simgrid
+
+\endverbatim
+
+\subsection faq_cmakeinstall How to install with cmake?
+
+\subsubsection faq_cmakeinstall1 From svn.
+
+\verbatim
+cmake -Denable_maintainer_mode=on -Dprefix=/home/navarrop/Bureau/install_simgrid ./
+make
+make install
+\endverbatim
+
+\subsubsection faq_cmakeinstall2 From a distrib
+
+\verbatim
+For version 3.4.1 and 3.4
+ cmake -Dprefix=/home/navarrop/Bureau/install_simgrid ./
+ make
+ make install-simgrid
+Since version 3.5
+ cmake -Dprefix=/home/navarrop/Bureau/install_simgrid ./
+ make
+ make install
+\endverbatim
+
+\subsection faq_cmakehowto How to modified sources files for developers
+
+\subsubsection faq_cmakehowto1 Add an executable or examples.
+
+If you want make an executable you have to create a CMakeList.txt to the src directory.
+You must specified where to create the executable, source list, dependencies and the name of the binary.
+
+\verbatim
+cmake_minimum_required(VERSION 2.6)
+
+set(EXECUTABLE_OUTPUT_PATH "./")
+set(LIBRARY_OUTPUT_PATH "${PROJECT_DIRECTORY}/lib")
+
+add_executable(get_sender get_sender.c) #add_executable(<name_of_target> <src list>)
+
+### Add definitions for compile
+target_link_libraries(get_sender simgrid m pthread -fprofile-arcs) #target_link_libraries(<name_of_targe> <dependencies>)
+\endverbatim
+
+Then you have to modified <project/directory>/buildtools/Cmake/MakeExeLib.cmake and add
+this line :
+\verbatim
+add_subdirectory(${PROJECT_DIRECTORY}/<path_where_is_CMakeList.txt>)
+\endverbatim
+
+\subsubsection faq_cmakehowto2 Delete/add sources to lib.
+
+If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/DefinePackages.cmake
+
+\verbatim
+set(JMSG_JAVA_SRC
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/MsgException.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/JniException.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/NativeException.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/HostNotFoundException.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/ProcessNotFoundException.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Msg.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Process.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Host.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Task.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/MsgNative.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/ApplicationHandler.java
+ ${PROJECT_DIRECTORY}/src/java/simgrid/msg/Sem.java
+)
+\endverbatim
+
+\subsubsection faq_cmakehowto3 Add test
+
+If you want modified, add or delete tests you have to edit <project/directory>/buildtools/Cmake/AddTests.cmake
+with this function : ADD_TEST(<name> <bin> <ARGS>)
+
+\verbatim
+add_test(test-simdag-1 ${PROJECT_DIRECTORY}/testsuite/simdag/sd_test --cfg=path:${PROJECT_DIRECTORY}/testsuite/simdag small_platform_variable.xml)
+\endverbatim
+
+\subsection faq_PIPOL Pipol-remote
+
+Now we offer the possibility to test your local sources on pipol platforms before a commit. Of course you have to be user of pipol <a href="https://pipol.inria.fr/users/">(Account request)</a> cause you need to give your pipol_username to cmake. Here is a list of available systems :
+\verbatim
+ amd64_kvm-linux-debian-lenny
+ amd64_kvm-linux-debian-testing
+ amd64_kvm-windows-7
+ amd64-linux-centos-5.dd.gz
+ amd64-linux-debian-etch.dd.gz
+ amd64-linux-debian-lenny.dd.gz
+ amd64-linux-debian-testing.dd.gz
+ amd64-linux-fedora-core10.dd.gz
+ amd64-linux-fedora-core11.dd.gz
+ amd64-linux-fedora-core12.dd.gz
+ amd64-linux-fedora-core13.dd.gz
+ amd64-linux-fedora-core7.dd.gz
+ amd64-linux-fedora-core8.dd.gz
+ amd64-linux-fedora-core9.dd.gz
+ amd64-linux-mandriva-2007_springs_powerpack.dd.gz
+ amd64-linux-mandriva-2009_powerpack.dd.gz
+ amd64-linux-opensuse-11.dd.gz
+ amd64-linux-redhatEL-5.0.dd.gz
+ amd64-linux-suse-LES10.dd.gz
+ amd64-linux-ubuntu-feisty.dd.gz
+ amd64-linux-ubuntu-hardy.dd.gz
+ amd64-linux-ubuntu-intrepid.dd.gz
+ amd64-linux-ubuntu-jaunty.dd.gz
+ amd64-linux-ubuntu-karmic.dd.gz
+ amd64-linux-ubuntu-lucid.dd.gz
+ amd64-unix-freebsd-7.dd.gz
+ amd64-windows-server-2003-64bits.dd.gz
+ amd64-windows-server-2008-64bits.dd.gz
+ i386_kvm-linux-debian-lenny
+ i386_kvm-linux-debian-testing
+ i386_kvm-linux-fedora-core13
+ i386_kvm-windows-xp-pro-sp3
+ i386-linux-centos-5.dd.gz
+ i386-linux-debian-etch.dd.gz
+ i386-linux-debian-lenny.dd.gz
+ i386-linux-debian-testing.dd.gz
+ i386-linux-fedora-core10.dd.gz
+ i386-linux-fedora-core11.dd.gz
+ i386-linux-fedora-core12.dd.gz
+ i386-linux-fedora-core13.dd.gz
+ i386-linux-fedora-core7.dd.gz
+ i386-linux-fedora-core8.dd.gz
+ i386-linux-fedora-core9.dd.gz
+ i386-linux-mandriva-2007_springs_powerpack.dd.gz
+ i386-linux-mandriva-2009_powerpack.dd.gz
+ i386-linux-opensuse-11.dd.gz
+ i386-linux-redhatEL-5.0.dd.gz
+ i386-linux-suse-LES10.dd.gz
+ i386-linux-ubuntu-feisty.dd.gz
+ i386-linux-ubuntu-hardy.dd.gz
+ i386-linux-ubuntu-intrepid.dd.gz
+ i386-linux-ubuntu-jaunty.dd.gz
+ i386-linux-ubuntu-karmic.dd.gz
+ i386-linux-ubuntu-lucid.dd.gz
+ i386_mac-mac-osx-server-leopard.dd.gz
+ i386-unix-freebsd-7.dd.gz
+ i386-unix-opensolaris-10.dd.gz
+ i386-unix-opensolaris-11.dd.gz
+ i386-unix-solaris-10.dd.gz
+ ia64-linux-debian-lenny.dd
+ ia64-linux-fedora-core9.dd
+ ia64-linux-redhatEL-5.0.dd
+ x86_64_mac-mac-osx-server-snow-leopard.dd.gz
+ x86_mac-mac-osx-server-snow-leopard.dd.gz
+\endverbatim
+
+Two kind of uses are possible :
+\verbatim
+This command copy your source and execute a configure then a build and finish with tests.
+ bob@caraja:~/Developments/simgrid/tmp_build$ make <name_of_image>
+
+This command copy your source and execute a \"ctest -D Experimental\" and submit the result to cdash.
+ bob@caraja:~/Developments/simgrid/tmp_build$ make <name_of_image>_experimental
+\endverbatim
+All commands are resumed with :
+\verbatim
+bob@caraja:~/Developments/simgrid/tmp_build$ make pipol_experimental_list_images
+bob@caraja:~/Developments/simgrid/tmp_build$ make pipol_test_list_images
+\endverbatim
+
+\subsection faq_cmakeExplain Explaination of sources files for cmake
+
+\li CMakeLists.txt
+
+Those files are the "main parts". One located at the project directory call all the cmake sources files. The others
+are little projects called by the first for make examples.
+
+\li CompleteInFiles.cmake
+
+Complete all .in files and define Variables for h files
+
+\li GenerateDoc.cmake
+
+This file make the html documentation.
+
+\li MakeExeLib.cmake
+
+Here are callled all "CMakeLists.txt" for make executables and libraries.
+
+\li PrintArgs.cmake
+
+This file is called at the end of the build for summarize environment variables.
+
+\li DefinePackages.cmake
+
+Here is defined sources packages for compiling libs.
+
+\li Flags.cmake
+
+Defined flags which are used for compiling sources.
+
+\li Supernovae.cmake
+
+Here are made files for the supernovae mode.
+
+\li Distrib.cmake
+
+Here is defined packages for install simgrid and make a distribution.
+
+\li MaintainerMode.cmake
+
+Part where are generated source files for maintainer mode.
+
+\li Option.cmake
+
+Here are defined options and initialized values.
+
+\li AddTests.cmake
+
+All tests are listed.
+
+\li CTestConfig.cmake
+
+Properties which link tests with dashboard.
+
+\subsection faq_cmakeList List of files added for cmake
+
+Here is a list of files involved into cmake build (relative to project directory path) :
+\verbatim
+
+Cmake sources:
+ ./doc/CMakeLists.txt
+ ./buildtools/Cmake/AddTests.cmake
+ ./buildtools/Cmake/CompleteInFiles.cmake
+ ./buildtools/Cmake/CTestConfig.cmake
+ ./buildtools/Cmake/DefinePackages.cmake
+ ./buildtools/Cmake/Distrib.cmake
+ ./buildtools/Cmake/Flags.cmake
+ ./buildtools/Cmake/GenerateDocs.cmake
+ ./buildtools/Cmake/MaintainerMode.cmake
+ ./buildtools/Cmake/MakeExeLib.cmake
+ ./buildtools/Cmake/MakeExeLibWin.cmake
+ ./buildtools/Cmake/MakeJava.cmake
+ ./buildtools/Cmake/Option.cmake
+ ./buildtools/Cmake/PrintArgs.cmake
+ ./buildtools/Cmake/Supernovae.cmake
+
+CMakeLists for each binaries or examples:
+ ./CMakeLists.txt
+ ./src/CMakeLists.txt
+ ./teshsuite/gras/empty_main/CMakeLists.txt
+ ./teshsuite/gras/small_sleep/CMakeLists.txt
+ ./teshsuite/gras/datadesc/CMakeLists.txt
+ ./teshsuite/gras/msg_handle/CMakeLists.txt
+ ./teshsuite/simdag/CMakeLists.txt
+ ./teshsuite/simdag/partask/CMakeLists.txt
+ ./teshsuite/simdag/platforms/CMakeLists.txt
+ ./teshsuite/simdag/network/CMakeLists.txt
+ ./teshsuite/simdag/network/mxn/CMakeLists.txt
+ ./teshsuite/simdag/network/p2p/CMakeLists.txt
+ ./teshsuite/xbt/CMakeLists.txt
+ ./teshsuite/msg/CMakeLists.txt
+ ./tools/gras/CMakeLists.txt
+ ./tools/tesh/CMakeLists.txt
+ ./testsuite/simdag/CMakeLists.txt
+ ./testsuite/xbt/CMakeLists.txt
+ ./testsuite/surf/CMakeLists.txt
+ ./examples/gras/properties/CMakeLists.txt
+ ./examples/gras/ping/CMakeLists.txt
+ ./examples/gras/pmm/CMakeLists.txt
+ ./examples/gras/mmrpc/CMakeLists.txt
+ ./examples/gras/synchro/CMakeLists.txt
+ ./examples/gras/timer/CMakeLists.txt
+ ./examples/gras/mutual_exclusion/simple_token/CMakeLists.txt
+ ./examples/gras/spawn/CMakeLists.txt
+ ./examples/gras/chrono/CMakeLists.txt
+ ./examples/gras/rpc/CMakeLists.txt
+ ./examples/gras/all2all/CMakeLists.txt
+ ./examples/simdag/properties/CMakeLists.txt
+ ./examples/simdag/CMakeLists.txt
+ ./examples/simdag/metaxml/CMakeLists.txt
+ ./examples/simdag/dax/CMakeLists.txt
+ ./examples/smpi/CMakeLists.txt
+ ./examples/amok/bandwidth/CMakeLists.txt
+ ./examples/amok/saturate/CMakeLists.txt
+ ./examples/msg/priority/CMakeLists.txt
+ ./examples/msg/properties/CMakeLists.txt
+ ./examples/msg/migration/CMakeLists.txt
+ ./examples/msg/gtnets/CMakeLists.txt
+ ./examples/msg/parallel_task/CMakeLists.txt
+ ./examples/msg/trace/CMakeLists.txt
+ ./examples/msg/suspend/CMakeLists.txt
+ ./examples/msg/masterslave/CMakeLists.txt
+ ./examples/msg/actions/CMakeLists.txt
+ ./examples/msg/sendrecv/CMakeLists.txt
+\endverbatim
+
+\section faq_installation Installing the SimGrid library with Autotools (valid until V3.3.4)
Many people have been asking me questions on how to use SimGrid. Quite
often, the questions were not really about SimGrid but on the
make install
\endverbatim
-If at some point, something fails, check the section "\ref
-faq_trouble_compil". If it does not help, you can report this problem to the
+If at some point, something fails, check the section \ref faq_trouble_compil .
+If it does not help, you can report this problem to the
list but, please, avoid sending a laconic mail like "There is a problem. Is it
okay?". Send the config.log file which is automatically generated by
configure. Try to capture both the standard output and the error output of the
\verbatim export LD_LIBRARY_PATH=$HOME/lib/:$LD_LIBRARY_PATH
\endverbatim
+\subsection faq_compiling_java Java bindings don't get compiled
+
+The configure script detects automatically whether you have the
+softwares needed to use the Java bindings or not. At the end of the
+configure, you can see the configuration picked by the script, which
+should look similar to
+\verbatim Configuration of package simgrid' (version 3.3.4-svn) on
+little64 (=4):
+
+ Compiler: gcc (version: )
+
+ CFlags: -O3 -finline-functions -funroll-loops -fno-strict-aliasing -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 -g3
+ CPPFlags:
+ LDFlags:
+
+ Context backend: ucontext
+ Compile Java: no
+
+ Maintainer mode: no
+ Supernovae mode: yes
+\endverbatim
+
+In this example, Java backends won't be compiled.
+
+On Debian-like systems (which includes ubuntu), you need the following
+packages: sun-java6-jdk libgcj10-dev. If you cannot find the
+libgcj10-dev, try another version, like libgcj9-dev (on Ubuntu before
+9.10) or libgcj11-dev (not released yet, but certainly one day).
+Please note that you need to activate the contrib and non-free
+repositories in Debian, and the universe ones in Ubuntu. Java comes at
+this price...
+
\subsection faq_compiling_snapshoot SimGrid development snapshots
We have very high standards on software quality, and we are reluctant releasing
is not the better source of information. Instead, you should check the GRAS
tutorial in general, and the \ref GRAS_tut_tour_setup in particular.
-
\section faq_howto Feature related questions
\subsection faq_MIA "Could you please add (your favorite feature here) to SimGrid?"
\subsubsection faq_MIA_asynchronous I want to do asynchronous communications in MSG
-Up until now, there is no asynchronous communications in MSG. However,
-you can create as many process as you want so you should be able to do
-whatever you want... I've written a queue module to help implementing
-some asynchronous communications at low cost (creating thousands of
-process only to handle communications may be problematic in term of
-performance at some point). I'll add it in the distribution asap.
+In the past (version <= 3.4), there was no function to perform asynchronous communications.
+It could easily be implemented by creating new process when needed though. Since version 3.5,
+we have introduced the following functions:
+ - MSG_task_isend()
+ - MSG_task_irecv()
+ - MSG_comm_test()
+ - MSG_comm_wait()
+ - MSG_comm_waitall()
+ - MSG_comm_waitany()
+ - MSG_comm_destroy()
+
+We refer you to the description of these functions for more details on their usage as well
+as to the exemple section on \ref MSG_ex_asynchronous_communications.
\subsubsection faq_MIA_thread_synchronization I need to synchronize my MSG processes
-You obviously cannot use pthread_mutexes of pthread_conds. The best
-thing would be to propose similar structures. Unfortunately, we
-haven't found time to do it yet. However you can try to play with
-MSG_process_suspend() and MSG_process_resume(). You can even do some
-synchronization with fake communications (using MSG_task_get(),
+You obviously cannot use pthread_mutexes of pthread_conds since we handle every
+scheduling related decision within SimGrid.
+
+In the past (version <=3.3.4) you could do it by playing with
+MSG_process_suspend() and MSG_process_resume() or with fake communications (using MSG_task_get(),
MSG_task_put() and MSG_task_Iprobe()).
+Since version 3.4, you can use classical synchronization structures. See page \ref XBT_synchro or simply check in
+include/xbt/synchro_core.h.
+
\subsubsection faq_MIA_host_load Where is the get_host_load function hidden in MSG?
There is no such thing because its semantic wouldn't be really
<tt>tools/platform_generation/</tt> directory of the SVN. Dinda et Al.
released a very comparable tool, and called it GridG.
-\subsubsection faq_SURF_dynamic Expressing dynamic resource availability in platform files
+\subsubsection faq_SURF_multicore Modeling multi-core resources
+
+There is currently no native support for multi-core or SMP machines in
+SimGrid. We are currently working on it, but coming up with the right
+model is very hard: Cores share caches and bus to access memory and
+thus interfere with each others. Memory contention is a crucial
+component of multi-core modeling.
+
+In the meanwhile, some user-level tricks can reveal sufficient for
+you. For example, you may model each core by a CPU and add some very
+high speed links between them. This complicates a bit the user code
+since you have to remember that when you assign something to a (real)
+host, it can be any of the (fake) hosts representing the cores of a
+given machine. For that, you can use the prop tag of the XML files as
+follows. Your code should then look at the ‘machine’ property
+associated with each workstation, and run parallel tasks over all
+cores of the machine.
+
+\verbatim
+ <host id="machine0/core0" power="91500E6">
+ <prop id="machine" value="machine0"/>
+ <prop id="core" value="0"/>
+ </host>
+ <host id="machine0/core1" power="91500E6">
+ <prop id="machine" value="machine0"/>
+ <prop id="core" value="1"/>
+</host>
+
+
+\endverbatim
+
+\subsubsection faq_SURF_dynamic Modeling dynamic resource availability
A nice feature of SimGrid is that it enables you to seamlessly have
resources whose availability change over time. When you build a
SimGrid behavior. In particular, you can change the default cpu and
network models...
+\subsubsection faq_simgrid_configuration_fullduplex Using Fullduplex
+
+Experimental fullduplex support is now available on the svn branch. In order to fullduple to work your platform must have two links for each pair
+of interconnected hosts, see an example here:
+\verbatim
+ simgrid_svn_sources/exemples/msg/gtnets/fullduplex-p.xml
+\endverbatim
+
+Using fullduplex support ongoing and incoming communication flows are
+treated independently for most models. The exception is the LV08 model which
+adds 0.05 of usage on the opposite direction for each new created flow. This
+can be useful to simulate some important TCP phenomena such as ack compression.
+
+Running a fullduplex example:
+\verbatim
+ cd simgrid_svn_sources/exemples/msg/gtnets
+ ./gtnets fullduplex-p.xml fullduplex-d.xml --cfg=fullduplex:1
+\endverbatim
+
+
+
+
+
\subsubsection faq_simgrid_configuration_gtnets Using GTNetS
It is possible to use a packet-level network simulator
unzip gtnets-current.zip
tar zxvf gtnets-current-patch.tgz
cd gtnets-current
- cp ../KAYO-PATCH-Added-RunUntilNextCompletion-and-some.patch .
- cat *.patch | patch -p1
+ cat ../00*.patch | patch -p1
\endverbatim
+ - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
+
+ \verbatim
+ cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
+ \endverbatim
+
- <b>Compile GTNetS</b>
- Due to portability issues it is possible that GTNetS does not compile in your architecture. Some
- other patches are provided in GTNetS directory. Use those patches at your own risk.
+ Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
+
\verbatim
- cd gtnets-current
ln -sf Makefile.linux Makefile
make depend
make debug
\endverbatim
- - If you have a problem compiling the GTNetS simulator a series of patches can be found <a href="http://mescal.imag.fr/membres/pedro.velho/simgrid/gtnets-current-patch.tgz">here</a>. Although, it is not
-guaranteed that these patches will make GTNetS compile in your architecture, they will just probably fix main issues when using the
-linux operating system.
-</p>
- <b>NOTE</b> A lot of warnings are expected but the application should compile
just fine. If the makefile insists in compiling some QT libraries
- <b>Installing GTNetS</b>
- Replace <userhome> by some path you have write access to.
+ It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
\verbatim
- ln -sf libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
+ ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<userhome>/usr/lib/libgtnets.so
mkdir /<userhome>/usr/include/gtnets
cp -fr SRC/*.h /<userhome>/usr/include/gtnets
- <b>Enable GTNetS support in SimGrid</b>
+
+In order to enable gtnets with simgrid you have to give where is gtnets. (path to <gtnets_path>/lib and <gtnets_path>/include)
\verbatim
+ Since v3.4 (with cmake)
+ cmake . -Dgtnets_path=/<userhome>/usr
+
+ Until v3.4 (with autotools)
./configure --with-gtnets=/<userhome>/usr
\endverbatim
runntime with the following options:</b>
\verbatim
+ Since v3.4 (with cmake)
+ cd simgrid
+ make
+ ctest -R gtnets
+
+ Until v3.4 (with autotools)
cd simgrid/example/msg/
make
make check
<a href="http://mescal.imag.fr/membres/arnaud.legrand/articles/simutools09.pdf">Accuracy Study and Improvement of Network Simulation in the SimGrid Framework</a>)
and can be activated at runtime. For example:
\verbatim
-./mycode platform.xml deployment.xml --cfg=workstation_model:compound --cfg=network_model:LV08 -cfg=cpu_model:Cas01
+./mycode platform.xml deployment.xml --cfg=workstation/model:compound --cfg=network/model:LV08 -cfg=cpu/model:Cas01
\endverbatim
Possible models for the network are currently "Constant", "CM02",
"LegrandVelho", "GTNets", Reno", "Reno2", "Vegas". Others will
probably be added in the future and many of the previous ones are
-experimental and are likely to disappear without notice...
+experimental and are likely to disappear without notice... To know the
+list of the currently implemented models, you should use the
+--help-models command line option.
+
+\verbatim
+./masterslave_forwarder ../small_platform.xml deployment_masterslave.xml --help-models
+Long description of the workstation models accepted by this simulator:
+ CLM03: Default workstation model, using LV08 and CM02 as network and CPU
+ compound: Workstation model allowing you to use other network and CPU models
+ ptask_L07: Workstation model with better parallel task modeling
+Long description of the CPU models accepted by this simulator:
+ Cas01_fullupdate: CPU classical model time=size/power
+ Cas01: Variation of Cas01_fullupdate with partial invalidation optimization of lmm system. Should produce the same values, only faster
+ CpuTI: Variation of Cas01 with also trace integration. Should produce the same values, only faster if you use availability traces
+Long description of the network models accepted by this simulator:
+ Constant: Simplistic network model where all communication take a constant time (one second)
+ CM02: Realistic network model with lmm_solve and no correction factors
+ LV08: Realistic network model with lmm_solve and these correction factors: latency*=10.4, bandwidth*=.92, S=8775
+ Reno: Model using lagrange_solve instead of lmm_solve (experts only)
+ Reno2: Model using lagrange_solve instead of lmm_solve (experts only)
+ Vegas: Model using lagrange_solve instead of lmm_solve (experts only)
+\endverbatim
+
+\subsection faq_tracing Tracing Simulations for Visualization
+
+The trace visualization is widely used to observe and understand the behavior
+of parallel applications and distributed algorithms. Usually, this is done in a
+two-step fashion: the user instruments the application and the traces are
+analyzed after the end of the execution. The visualization itself can highlights
+unexpected behaviors, bottlenecks and sometimes can be used to correct
+distributed algorithms. The SimGrid team is currently instrumenting the library
+in order to let users trace their simulations and analyze them. This part of the
+user manual explains how the tracing-related features can be enabled and used
+during the development of simulators using the SimGrid library.
+
+\subsubsection faq_tracing_howitworks How it works
+
+For now, the SimGrid library is instrumented so users can trace the <b>platform
+utilization</b> using the MSG interface. This means that the tracing will
+register how much power is used for each host and how much bandwidth is used for
+each link of the platform. The idea with this type of tracing is to observe the
+overall view of resources utilization in the first place, especially the
+identification of bottlenecks, load-balancing among hosts, and so on.
+
+The idea of the instrumentation is to classify the MSG tasks by category,
+and trace
+the platform utilization (hosts and links) for each of the categories. For that,
+the tracing interface enables the declaration of categories and a function to
+mark a task with a previously declared category. <em>The tasks that are not
+classified according to a category are not traced</em>.
+
+\subsubsection faq_tracing_enabling Enabling using CMake
+
+With the sources of SimGrid, it is possible to enable the tracing
+using the parameter <b>-Dtracing=on</b> when the cmake is executed.
+The section \ref faq_tracing_functions describes all the functions available
+when this Cmake options is activated. These functions will have no effect
+if SimGrid is configured without this option (they are wiped-out by the
+C-preprocessor).
+
+\verbatim
+$ cmake -Dtracing=on .
+$ make
+\endverbatim
+
+\subsubsection faq_tracing_functions Tracing Functions
+
+\subsubsubsection Mandatory Functions
+
+\li <b>\c TRACE_start ()</b>: This is the first function to
+be called. It returns 0 if everything was properly initialized, 1 otherwise.
+All trace functions called before TRACE_start do nothing.
+
+\li <b>\c TRACE_category (const char *category)</b>: This function should be used
+to define a user category. The category can be used to differentiate the tasks
+that are created during the simulation (for example, tasks from server1,
+server2, or request tasks, computation tasks, communication tasks).
+All resource utilization (host power and link bandwidth) will be
+classified according to the task category. Tasks that do not belong to a
+category are not traced.
+
+\li <b>\c TRACE_msg_set_task_category (m_task_t task, const char *category)</b>:
+This function should be called after the creation of a task, to define the
+category of that task. The first parameter \c task must contain a task that was
+created with the function \c MSG_task_create. The second parameter
+\c category must contain a category that was previously defined by the function
+\c TRACE_category.
+
+\li <b>\c TRACE_end ()</b>: This is the last function to be called. It closes
+the trace file and stops the tracing of the simulation. All tracing will be
+completely disabled after the calling this function. Although we recommend
+the use of this function somewhere in the end of program, it can be used
+anywhere in the code. This function returns 0 if everything is ok, 1 otherwise.
+
+\subsubsubsection Optional Functions
+
+\li <b>\c TRACE_host_variable_declare (const char *variable)</b>:
+Declare a user variable that will be associated to hosts. A variable can
+be used to trace user variables such as the number of tasks in a server,
+the number of clients in an application, and so on.
+
+\li <b>\c TRACE_host_variable_[set|add|sub] (const char *variable, double
+value)</b>:
+Set the value of a given user variable. It is important to remind that
+the value of this variable is always associated to the host. The host
+that will be used when these functions are called is the one returned by
+the function \c MSG_host_self().
+
+\subsubsection faq_tracing_options Tracing configuration Options
+
+These are the options accepted by the tracing system of SimGrid:
+
+\li <b>\c tracing/filename</b>: use this to specify the name of the trace file
+that will be created during the simulation. For example, after the binary
+of your simulator, you can pass as parameter this:
+\verbatim
+--cfg=tracing/filename:mytracefile.trace
+\endverbatim
+in order to trace the behavior of the simulation in a file with the name
+mytracefile.trace.
+
+\li <b>\c tracing/platform</b>: use this to activate the tracing of the
+platform. For example, you can pass as parameter to your simulator:
+\verbatim
+--cfg=tracing/platform:1
+\endverbatim
+to trace the platform utilization by the categories you declared in your
+simulator. By default, this options is set to 0.
+
+\subsubsection faq_tracing_example Example of Instrumentation
+
+A simplified example using the tracing mandatory functions.
+
+\verbatim
+int main (int argc, char **argv)
+{
+ MSG_global_init (&argc, &argv);
+
+ //note that TRACE_start must be called after MSG_global_init
+ TRACE_start ();
+ TRACE_category ("request");
+ TRACE_category ("computation");
+ TRACE_category ("finalize");
+
+ //(... after deployment ...)
+
+ m_task_t req1 = MSG_task_create("1st_request_task", 10, 10, NULL);
+ m_task_t req2 = MSG_task_create("2nd_request_task", 10, 10, NULL);
+ m_task_t req3 = MSG_task_create("3rd_request_task", 10, 10, NULL);
+ m_task_t req4 = MSG_task_create("4th_request_task", 10, 10, NULL);
+ TRACE_msg_set_task_category (req1, "request");
+ TRACE_msg_set_task_category (req2, "request");
+ TRACE_msg_set_task_category (req3, "request");
+ TRACE_msg_set_task_category (req4, "request");
+
+ m_task_t comp = MSG_task_create ("comp_task", 100, 100, NULL);
+ TRACE_msg_set_task_category (comp, "computation");
+
+ m_task_t finalize = MSG_task_create ("finalize", 0, 0, NULL);
+ TRACE_msg_set_task_category (finalize, "finalize");
+
+ //(...)
+
+ MSG_clean();
+
+ TRACE_end();
+ return 0;
+}
+\endverbatim
+
+\subsubsection faq_tracing_analyzing Analyzing the SimGrid Traces
+
+The SimGrid library, during an instrumented simulation, creates a trace file in
+the Paje file format that contains the platform utilization for the simulation
+that was executed. The visualization analysis of this file is performed with the
+visualization tool <a href="http://triva.gforge.inria.fr">Triva</a>, with
+special configurations tunned to SimGrid needs. This part of the documentation
+explains how to configure and use Triva to analyse a SimGrid trace file.
+
+- <b>Installing Triva</b>: the tool is available in the INRIAGforge,
+at <a href="http://triva.gforge.inria.fr">http://triva.gforge.inria.fr</a>.
+Use the following command to get the sources, and then check the file
+<i>INSTALL.simplified</i>. This file contains instructions to install
+the tool's dependencies in a Ubuntu/Debian Linux.
+\verbatim
+$ svn checkout svn://scm.gforge.inria.fr/svn/triva
+$ cd triva
+$ cat INSTALL.simplified
+\endverbatim
+
+- <b>Executing Triva</b>: a binary called <i>Triva</i> is available after the
+ installation (you can execute it passing <em>--help</em> to check its
+options). If the triva binary is not available after following the
+installation instructions, you may want to execute the following command to
+initialize the GNUstep environment variables (note that the location of the
+<i>GNUstep.sh</i> file may vary depending on your GNUstep installation - the
+command is known to work in Ubuntu and Debian Linux):
+\verbatim
+$ source /usr/share/GNUstep/Makefiles/GNUstep.sh
+\endverbatim
+You should be able to see this output after the installation of triva:
+\verbatim
+$ ./Triva.app/Triva --help
+Usage: Triva [OPTION...] TRACEFILE
+Trace Analysis through Visualization
+
+ You need to use one of the following options:
+ -g, --graph Graph Analysis
+ -t, --treemap Treemap Analysis
+
+ Other auxiliary options to check the trace file:
+ -c, --check Check the integrity of trace file
+ -h, --hierarchy Export the trace type hierarchy
+ -l, --list List entity types
+
+ -?, --help Give this help list
+ --usage Give a short usage message
+\endverbatim
+Triva expects that the user choose one of the available options
+(currently <em>--graph</em> or <em>--treemap</em> for a visualization analysis)
+and the trace file from the simulation.
+
+- <b>Understanding Triva - time-slice</b>: the analysis of a trace file using
+ the tool always takes into account the concept of the <em>time-slice</em>.
+This concept means that what is being visualized in the screen is always
+calculated considering a specific time frame, with its beggining and end
+timestamp. The time-slice is configured by the user and can be changed
+dynamically through the window called <em>Time Interval</em> that is opened
+whenever a trace file is being analyzed. The next figure depicts the time-slice
+configuration window.
+In the top of the window, in the space named <i>Trace Time</i>,
+the two fields show the beggining of the trace (which usually starts in 0) and
+the end (that depends on the time simulated by SimGrid). The middle of the
+window, in the square named <i>Time Slice Configuration</i>, contains the
+aspects related to the time-slice, including its <i>start</i> and its
+<i>size</i>. The gray rectangle in the bottom of this part indicates the
+<i>current time-slice</i> that is considered for the drawings. If the checkbox
+<i>Update Drawings on Sliders Change</i> is not selected, the button
+<i>Apply</i> must be clicked in order to inform triva that the
+new time-slice must be considered. The bottom part of the window, in the space
+indicated by the square <i>Time Slice Animation</i> can be used to advance
+the time-frame automatically. The user configures the amount of time that the
+time-frame will forward and how frequent this update will happen. Once this is
+configured, the user clicks the <i>Play</i> button in order to see the dynamic
+changes on the drawings.
+<center>
+\htmlonly
+<a href="triva-time_interval.png" border=0><img src="triva-time_interval.png" width="50%" border=0></a>
+\endhtmlonly
+</center>
+<b>Remarks:</b> when the trace has too many hosts or links, the computation to
+take into account a new time-slice can be expensive. When this happens, the
+<i>Frequency</i> parameter, but also updates caused by change on configurations
+when the checkbox <i>Update Drawings on Sliders
+Change</i> is selected will not be followed.
+
+- <b>Understanding Triva - graph</b>: this part of the documention explains how
+ to analyze the traces using the graph view of Triva, when the user executes
+the tool passing <em>--graph</em> as parameter. Triva opens three windows when
+this parameter is used: the <i>Time Interval</i> window (previously described),
+the <i>Graph Representation</i> window, and the <em>Graph Configuration</em>
+window. The Graph Representation is the window where drawings take place.
+Initially, it is completely white waiting for a proper graph configuration input
+by the user. We start the description of this type of analysis by describing the
+<i>Graph Configuration</i> window (depicted below). By using a particular
+configuration, triva
+can be used to customize the graph drawing according to
+the SimGrid trace that was created with user-specific categories. Before delving
+into the details of this customization, let us first explain the major parts of
+the graph configuration window. The buttons located in the top-right corner can
+be used to delete, copy and create a new configuration. The checkbox in the
+top-middle part of the window indicates if the configuration typed in the
+textfield is syntactically correct (we are using the non-XML
+<a href="http://en.wikipedia.org/wiki/Property_list">Property List Format</a> to
+describe the configuration). The pop-up button located on the top-left corner
+indicates the selected configuration (the user can have multiple graph
+configurations). The bottom-left text field contains the name of the current
+configuration (updates on this field must be followed by typing enter on the
+keyboard to take into account the name change). The bottom-right <em>Apply</em>
+button activates the current configuration, resulting on an update on the graph
+drawings.
+<center>
+\htmlonly
+<a href="triva-graph_configuration.png" border=0><img src="triva-graph_configuration.png" width="50%" border=0></a>
+\endhtmlonly
+</center>
+<b>Basic SimGrid Configuration</b>: The figure shows in the big textfield the
+basic configuration that should be used during the analysis of a SimGrid trace
+file. The basic logic of the configuration is as follows:
+\verbatim
+{
+ node = (HOST);
+ edge = (LINK);
+\endverbatim
+The nodes of the graph will be created based on the <i>node</i> parameter, which
+in this case is the different <em>"HOST"</em>s of the platform
+used to simulate. The <i>edge</i> parameter indicates that the edges of the
+graph will be created based on the <em>"LINK"</em>s of the platform. After the
+definition of these two parameters, the configuration must detail how
+<em>HOST</em>s and <em>LINK</em>s should be drawn. For that, the configuration
+must have an entry for each of the types used. For <em>HOST</em>, as basic
+configuration, we have:
+\verbatim
+ HOST = {
+ size = power;
+ scale = global;
+ };
+\endverbatim
+The parameter <em>size</em> indicates which variable from the trace file will be
+used to define the size of the node HOST in the visualization. If the simulation
+was executed with availability traces, the size of the nodes will be changed
+according to these traces. The parameter <em>scale</em> indicates if the value
+of the variable is <em>global</em> or <em>local</em>. If it is global, the value
+will be relative to the power of all other hosts, if it is local, the value will
+be relative locally.
+For <em>LINK</em> we have:
+\verbatim
+ LINK = {
+ src = source;
+ dst = destination;
+
+ size = bandwidth;
+ scale = global;
+ };
+\endverbatim
+For the types specified in the <em>edge</em> parameter (such as <em>LINK</em>),
+the configuration must contain two additional parameters: <em>src</em> and
+<em>dst</em> that are used to properly identify which nodes this edge is
+connecting. The values <em>source</em> and <em>destination</em> are always present
+in the SimGrid trace file and should not be changed in the configuration. The
+parameter <em>size</em> for the LINK, in this case, is configured as the
+variable <em>bandwidth</em>, with a <em>global</em> scale. The scale meaning
+here is exactly the same used for nodes. The last parameter is the GraphViz
+algorithm used to calculate the position of the nodes in the graph
+representation.
+\verbatim
+ graphviz-algorithm = neato;
+}
+\endverbatim
+<b>Customizing the Graph Representation</b>: triva is capable to handle
+a customized graph representation based on the variables present in the trace
+file. In the case of SimGrid, every time a category is created for tasks, two
+variables in the trace file are defined: one to indicate node utilization (how
+much power was used by that task category), and another to indicate link
+utilization (how much bandwidth was used by that category). For instance, if the
+user declares a category named <i>request</i>, there will be variables named
+<b>p</b><i>request</i> and a <b>b</b><i>request</i> (<b>p</b> for power and
+<b>b</b> for bandwidth). It is important to notice that the variable
+<i>prequest</i> in this case is only available for HOST, and
+<i>brequest</i> is only available for LINK. <b>Example</b>: suppose there are
+two categories for tasks: request and compute. To create a customized graph
+representation with a proportional separation of host and link utilization, use
+as configuration for HOST and LINK this:
+\verbatim
+ HOST = {
+ size = power;
+ scale = global;
+
+ sep_host = {
+ type = separation;
+ size = power;
+ values = (prequest, pcomputation);
+ };
+ };
+
+ LINK = {
+ src = source;
+ dst = destination;
+ size = bandwidth;
+ scale = global;
+
+ sep_link = {
+ type = separation;
+ size = bandwidth;
+ values = (brequest, bcomputation);
+ };
+ };
+\endverbatim
+Where <i>sep_host</i> contains a composition of type <i>separation</i> where
+its max size is the <i>power</i> of the host and the variables <i>prequest</i>
+and <i>pcomputation</i> are drawn proportionally to the size of the HOST. And
+<i>sep_link</i> is also a separation where max is defined as the
+<i>bandwidth</i> of the link, and the variables <i>brequest</i> and
+<i>bcomputation</i> are drawn proportionally within a LINK.
+<i>This configuration enables the analysis of resource utilization by MSG tasks,
+and the identification of load-balancing issues, network bottlenecks, for
+instance.</i> \n
+<b>Other compositions</b>: besides <i>separation</i>, it is possible to use
+other types of compositions, such as gradients, and colors, like this:
+\verbatim
+ gra_host = {
+ type = gradient;
+ scale = global;
+ values = (numberOfTasks);
+ };
+ color_host = {
+ type = color;
+ values = (is_server);
+ };
+\endverbatim
+Where <i>gra_host</i> creates a gradient within a node of the graph, using a
+global scale and using as value a variable called <i>numberOfTasks</i>, that
+could be declared by the user using the optional tracing functions of SimGrid.
+If scale is global, the max and min value for the gradient will be equal to the
+max and min numberOfTasks among all hosts, and if scale is local, the max and
+min value based on the value of numberOfTasks locally in each host.
+And <i>color_host</i> composition draws a square based on a positive value of
+the variable <i>is_server</i>, that could also be defined by the user using the
+SimGrid tracing functions. \n
+<b>The Graph Visualization</b>: The next figure shows a graph visualization of a
+given time-slice of the masterslave_forwarder example (present in the SimGrid
+sources). The red color indicates tasks from the <i>compute</i> category. This
+visualization was generated with the following configuration:
+\verbatim
+{
+ node = (HOST);
+ edge = (LINK);
+
+ HOST = {
+ size = power;
+ scale = global;
+
+ sep_host = {
+ type = separation;
+ size = power;
+ values = (pcompute, pfinalize);
+ };
+ };
+ LINK = {
+ src = source;
+ dst = destination;
+ size = bandwidth;
+ scale = global;
+
+ sep_link = {
+ type = separation;
+ size = bandwidth;
+ values = (bcompute, bfinalize);
+ };
+ };
+ graphviz-algorithm = neato;
+}
+\endverbatim
+<center>
+\htmlonly
+<a href="triva-graph_visualization.png" border=0><img src="triva-graph_visualization.png" width="50%" border=0></a>
+\endhtmlonly
+</center>
+
+- <b>Understading Triva - colors</b>: An important issue when using Triva is how
+ to define colors. To do that, we have to know which variables are defined in
+the trace file generated by the SimGrid library. The parameter <em>--list</em>
+lists the variables for a given trace file:
+\verbatim
+$ Triva -l masterslave_forwarder.trace
+iFile
+c platform
+c HOST
+v power
+v is_slave
+v is_master
+v task_creation
+v task_computation
+v pcompute
+v pfinalize
+c LINK
+v bandwidth
+v latency
+v bcompute
+v bfinalize
+c user_type
+\endverbatim
+We can see that HOST has seven variables (from power to pfinalize) and LINK has
+four (from bandwidth to bfinalize). To define a red color for the
+<i>pcompute</i> and <i>bcompute</i> (which are defined based on user category
+<i>compute</i>), execute:
+\verbatim
+$ defaults write Triva 'pcompute Color' '1 0 0'
+$ defaults write Triva 'bcompute Color' '1 0 0'
+\endverbatim
+Where the three numbers in each line are the RGB color with values from 0 to 1.
+
+\subsection faq_modelchecking Model-Checking
+\subsubsection faq_modelchecking_howto How to use it
+To enable the experimental SimGrid model-checking support the program should
+be executed with the command line argument
+\verbatim
+--cfg=model-check:1
+\endverbatim
+Properties are expressed as assertions using the function
+\verbatim
+void MC_assert(int prop);
+\endverbatim
+
+\subsection faq_binding_lua Lua Binding
+Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library.
+ Sometime users prefer using some kind of « easy scripts » or a language easier to code with, for their works,
+ which avoid dealing with C errors, and sometime an important gain of time.
+Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid
+for MSG Module, and we are currenlty working on bindings for other modules.
+
+
+\subsubsection faq_binding_lua_about What is lua ?
+Lua is a lightweight, reflective, imperative and functional programming language,
+ designed as a scripting language with extensible semantics as a primary goal (see official web site <a href="http://www.lua.org">here</a>).
+\subsubsection faq_binding_lua_why Why lua ?
+Lua is a fast, portable and powerful script language, quite simple to use for developpers.
+it combines procedural features with powerful data description facilities,
+ by using a simple, yet powerful, mechanism of tables.
+Lua has a relatively simple C API compared to other scripting languages,
+and accordingly it provides a robust, easy to use it.
+\subsubsection faq_binding_lua_simgrid How to use lua in Simgrid ?
+Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird :
+ - Coding functions coresponding to each process
+ - loading the platforme/deployment XML file that describe the environment of simulation
+ - and … Running the Simulation.
+
+\dontinclude lua/master_slave.lua
+\subsubsection faq_binding_lua_example_master_slave Master/Slave Example
+
+ \li Master Code
+ \until end_of_master
+we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task,
+ then simgrid.Task.send(task,alias) to send it.
+we use also simgrid.Task.name(task), to get the task's name.
+
+\li Slave Code
+\until end_of_slave
+Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias,
+this function return directly the task recevied.
+
+\li Set Environmenet and run application
+\until simgrid.clean()
+
+\subsubsection faq_binding_lua_example_data Exchanging Data
+You can also exchange data between Process using lua. for that, you have to deal with lua task as a table,
+since lua is based itself on a mechanism of tables,
+so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks.
+
+\li Sender process
+\verbatim
+ task = simgrid.Task.new("data_task",task_comp,task_comm);
+ task['matrix'] = my_matrix;
+ task['table'] = my_table;
+ task['message'] = "Hello from (Lua || Simgrid ) !! "
+ …
+ simgrid.Task.send(task,alias)
+\endverbatim
+ After creating task, we associate to it various kind of data with a specific key (string in this case)
+ to distinguish between data variables. The receiver will use this key to access easily to datas.
+
+
+\li Receiver processe
+\verbatim
+ task = simgrid.Task.recv(alias);
+ sender_matrix = task['matrix'];
+ sender_table = task['table'];
+ sender_message = task['message']
+ ...
+\endverbatim
+ Note that in lua, both sender and receiver share the same lua task.
+ So that the receiver could joint data directly on the received task without sending it back.
+ You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua.
+
+
+\subsubsection faq_binding_lua_example_bypass Bypass XML
+ maybe you wonder if there is a way to bypass the XML files,
+ and describe your platform directly from the code, with lua bindings it's Possible !! how ?
+ We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files
+ ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) )
+
+
+\li set Routing mode
+\verbatim
+ simgrid.AS.new{id="AS0",mode="Full"};
+\endverbatim
+
+\li set Hosts
+\verbatim
+ simgrid.Host.new{id="Tremblay",power=98095000};
+ simgrid.Host.new{id="Jupiter",power=76296000};
+ simgrid.Host.new{id="Fafard",power=76296000};
+ simgrid.Host.new{id="Ginette",power=48492000};
+ simgrid.Host.new{id="Bourassa",power=48492000};
+\endverbatim
+ we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts.
+
+\li set Links
+\verbatim
+ for i=0,11 do
+ simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087}; -- some crazy values ;)
+ end
+\endverbatim
+ we used simgrid.Link.new{id=link_id,bandwidth=bw,latency=lat} with a simple for loop to create all links we need (much easier than XML hein ?)
+
+\li set Routes
+\verbatim
+-- simgrid.Route.new(src_id,des_id,links_nb,links_list)
+ simgrid.Route.new("Tremblay","Jupiter",1,{"1"});
+ simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"});
+ simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"});
+ simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"});
+
+ simgrid.Route.new("Jupiter","Tremblay",1,{"1"});
+ simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"});
+ simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"});
+ simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"});
+ ...
+\endverbatim
+ for each host you have to specify which route to choose to access to the rest of hosts connected in the grid.
+
+\li Save platform
+\verbatim
+ simgrid.register_platform();
+\endverbatim
+Don't forget to register your platform, that SURF callbacks starts their work ;)
+
+\li set application
+\verbatim
+ simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"});
+ simgrid.Host.setFunction("Bourassa","Slave",1,{"0"});
+ simgrid.Host.setFunction("Jupiter","Slave",1,{"1"});
+ simgrid.Host.setFunction("Fafard","Slave",1,{"2"});
+ simgrid.Host.setFunction("Ginette","Slave",1,{"3"});
+\endverbatim
+ you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list)
+ you can associate functions for each host with arguments if needed .
+
+\li
+\verbatim
+ simgrid.register_application();
+\endverbatim
+Yes, Here too you have to resgiter your application before running the simulation.
+
+the full example is distributed in the file examples/lua/master_slave_bypass.lua
+
+\subsection faq_binding_ruby Ruby Binding
+
+
+\subsubsection faq_binding_ruby_simgrid Use Ruby in Simgrid
+Since v3.4, the use of <a href="http://ruby-lang.org">ruby</a> in simgrid is available for the MSG Module.
+you can find almost all MSG functionalities in Ruby code, that allows you to set up your environment, manage tasks between hosts and run the simulation.
+
+\dontinclude ruby/MasterSlave.rb
+\subsubsection faq_binding_ruby_example Master/Slave Ruby Application
+for each process method(master and slave in this example), you have to associate a ruby class, that should inherit from <i>MSG::Process</i> ruby class,
+ with a 'main' function that describe the behaviour of the process during the simulation.
+\li required stuff
+\verbatim
+require 'simgrid'
+include MSG
+\endverbatim
+
+\li Master code
+\until end_of_master
+
+the class MSG::Task contains methods that allows the management of the native MSG tasks.
+in master ruby code we used :
+ - <i>MSG::Task.new(task_name,compute_size,communication_size)</i> : to instanciate a new task.
+ - <i>MSG::Task.send(mailbox)</i> : to send the task via a mailbox alias.
+ - <i>MSG::Task.name</i> : to get the task's name.
+
+\li Slave code
+\until end_of_slave
+to receive a task, we use the method <i>MSG::Task.receive(mailbox)</i> that return a MSG:Task object (received task).
+
+\li Main chunk
+\until MSG.exit
+
+- <i>MSG.createEnvironment(platform_file)</i> : set up the environment
+- <i>MSG.deployApplication(deployment_file)</i> : load the deployment file description.
+- <i>MSG.run</i> : run the simulation
+
+\subsubsection faq_binding_ruby_data Exchanging data
+ruby bindings provides two ways to exchange data between ruby processes.
+\li MSG::Task.join & MSG::Task.data \br
+
+ the MSG::Task class contains 2 methods that allows a data exchange between 2 process.
+
+ -<i>MSG::Task.join</i> : makes possible to join any kind of ruby data within a task.
+ \verbatim
+ ...
+ myTable = Array.new
+ myTable <<1<<-2<<45<<67<<87<<76<<89<<56<<78<<3<<-4<<99
+ # Creates and send Task With the Table inside
+ task = MSG::Task.new("quicksort_task",taskComputeSize, taskCommunicationSize);
+ task.join(myTable);
+ ...
+ task.send(mailbox);
+ \endverbatim
+ -<i>MSG::Task.data</i> : to access to the data contained into the task.
+ \verbatim
+ ...
+ task = MSG::Task.receive(recv_mailbox.to_s)
+ table = task.data
+ quicksort(table,0,table.size-1)
+ ...
+ \endverbatim
+you can find a complet example illustrating the use of those methods in file /example/ruby/Quicksort.rb
+
+\li inheritence
+
+ another 'object-oriented' way to do it, is to make your own 'task' class that inherit from MSG::Task ,
+ and contains data you want to deal with, the only 'tricky' thing is that "the initializer" method has no effect !
+
+ the use of some getter/setter methods would be the simple way to manage your data :)
+ \verbatim
+class PingPongTask < MSG::Task
+ # The initialize method has no effect
+ @time
+ def setTime(t)
+ @time = t
+ end
+ def getTime()
+ return @time
+ end
+end
+ \endverbatim
+ you can find an example of use in file example/ruby/PingPong.rb
\section faq_troubleshooting Troubleshooting
header files with tons of __declspec(dllexport) cruft. We only need to do so
for data, but there is no public data in SimGrid so we are good.
+
