X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7f89216fa85ff23f78117974fc4d7eac1ca8f9cb..8bca872ed1a62f660c0d5da333eece9edb1d05a4:/doc/FAQ.doc diff --git a/doc/FAQ.doc b/doc/FAQ.doc index 5920b4cd72..aecaa28564 100644 --- a/doc/FAQ.doc +++ b/doc/FAQ.doc @@ -88,263 +88,7 @@ little more tricky than I would have expected, but the work is moving 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 - -Many people have been asking me questions on how to use SimGrid. Quite -often, the questions were not really about SimGrid but on the -installation process. This section is intended to help people that are -not familiar with compiling C files under UNIX. If you follow these -instructions and still have some troubles, drop an e-mail to -. - -\subsection faq_compiling Compiling SimGrid from a stable archive - -First of all, you need to download the latest version of SimGrid from -here. -Suppose you have uncompressed SimGrid in some temporary location of -your home directory (say /home/joe/tmp/simgrid-3.0.1 ). The -simplest way to use SimGrid is to install it in your home -directory. Change your directory to -/home/joe/tmp/simgrid-3.0.1 and type - -\verbatim -./configure --prefix=$HOME -make -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 -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 -make command with script. There is no way for us to help you -without the relevant bits of information. - -Now, the following directory should have been created : - - \li /home/joe/doc/simgrid/html/ - \li /home/joe/lib/ - \li /home/joe/include/ - -SimGrid is not a binary, it is a library. Both a static and a dynamic -version are available. Here is what you can find if you try a ls -/home/joe/lib: - -\verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1 -\endverbatim - -Thus, there is two ways to link your program with SimGrid: - \li Either you use the static version, e.g -\verbatim gcc libsimgrid.a -o MainProgram MainProgram.c -\endverbatim - In this case, all the SimGrid functions are directly - included in MainProgram (hence a bigger binary). - \li Either you use the dynamic version (the preferred method) -\verbatim gcc -lsimgrid -o MainProgram MainProgram.c -\endverbatim - In this case, the SimGrid functions are not included in - MainProgram and you need to set your environment - variable in such a way that libsimgrid.so will be - found at runtime. This can be done by adding the following - line in your .bashrc (if you use bash and if you have - installed the SimGrid libraries in your home directory): -\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 -a stable release as long as there is still some known bug in the code base. In -addition, we added quite an extensive test base, making sure that we correctly -test the most important parts of the tool. - -As an unfortunate conclusion, there may be some time between the stable -releases. If you want to benefit from the most recent features we introduced, -but don't want to take the risk of an untested version from the SVN, then -development snapshots are done for you. - -These are pre-releases of SimGrid that still fail some tests about features -that almost nobody use, or on platforms not being in our core target (which is -Linux, Mac, other Unixes and Windows, from the most important to the less -one). That means that using this development releases should be safe for most -users. - -These archives can be found on -this web page. Once you -got the lastest archive, you can compile it just like any archive (see above). - -\subsection faq_compiling_svn Compiling SimGrid from the SVN - -The project development takes place in the SVN, where all changes are -committed when they happen. Then every once in a while, we make sure that the -code quality meets our standard and release an archive from the code in the -SVN. We afterward go back to the development in the SVN. So, if you need a -recently added feature and can afford some little problem with the stability -of the lastest features, you may want to use the SVN version instead of a -released one. - -For that, you first need to get the "simgrid" module from -here. - -You won't find any configure and a few other things -(Makefile.in's, documentation, ...) will be missing as well. The -reason for that is that all these files have to be regenerated using the -latest versions of autoconf, libtool, automake -(>1.9) and doxygen (>1.4). To generate the configure and -the Makefile.in's, you just have to launch the bootstrap -command that resides in the top of the source tree. Then just follow the -instructions of Section \ref faq_compiling. - -We insist on the fact that you really need the latest versions of -autoconf, automake and libtool. Doing this step on exotic architectures/systems -(i.e. anything different from a recent linux distribution) may be -... uncertain. If you need to compile the SVN version on a machine where all these -dependencies are not met, the easiest is to do make dist in the SVN -directory of another machine where all dependencies are met. It will create an -archive you may deploy on other sites just as a regular stable release. - -In summary, the following commands will checkout the SVN, regenerate the -configure script and friends, configure SimGrid and build it. - -\verbatim svn checkout svn://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk simgrid -cd simgrid -./bootstrap -./configure --enable-maintainer-mode --prefix= -make \endverbatim - -Then, if you want to install SimGrid on the current box, just do: -\verbatim make install \endverbatim - -If you want to build an snapshot of the SVN to deploy it on another box (for -example because the other machine don't have the autotools), do: -\verbatim make dist \endverbatim - -Moreover, you should never call the autotools manually since you must run -them in a specific order with specific arguments. Most of the times, the -makefiles will automatically call the tools for you. When it's not possible -(such as the first time you checkout the SVN), use the ./bootstrap command -to call them explicitly. - - -\subsection faq_setting_MSG Setting up your own MSG code - -Do not build your simulator by modifying the SimGrid examples. Go -outside the SimGrid source tree and create your own working directory -(say /home/joe/SimGrid/MyFirstScheduler/). - -Suppose your simulation has the following structure (remember it is -just an example to illustrate a possible way to compile everything; -feel free to organize it as you want). - - \li sched.h: a description of the core of the - scheduler (i.e. which functions are can be used by the - agents). For example we could find the following functions - (master, forwarder, slave). - - \li sched.c: a C file including sched.h and - implementing the core of the scheduler. Most of these - functions use the MSG functions defined in section \ref - msg_gos_functions. - - \li masterslave.c: a C file with the main function, i.e. - the MSG initialization (MSG_global_init()), the platform - creation (e.g. with MSG_create_environment()), the - deployment phase (e.g. with MSG_function_register() and - MSG_launch_application()) and the call to - MSG_main()). - -To compile such a program, we suggest to use the following -Makefile. It is a generic Makefile that we have used many times with -our students when we teach the C language. - -\verbatim -all: masterslave -masterslave: masterslave.o sched.o - -INSTALL_PATH = $$HOME -CC = gcc -PEDANTIC_PARANOID_FREAK = -O0 -Wshadow -Wcast-align \ - -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \ - -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \ - -Wmissing-noreturn -Wredundant-decls -Wnested-externs \ - -Wpointer-arith -Wwrite-strings -finline-functions -REASONABLY_CAREFUL_DUDE = -Wall -NO_PRAYER_FOR_THE_WICKED = -w -O2 -WARNINGS = $(REASONABLY_CAREFUL_DUDE) -CFLAGS = -g $(WARNINGS) - -INCLUDES = -I$(INSTALL_PATH)/include -DEFS = -L$(INSTALL_PATH)/lib/ -LDADD = -lm -lsimgrid -LIBS = - -%: %.o - $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@ - -%.o: %.c - $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $< - -clean: - rm -f $(BIN_FILES) *.o *~ -.SUFFIXES: -.PHONY : clean - -\endverbatim - -The first two lines indicates what should be build when typing make -(masterslave) and of which files it is to be made of -(masterslave.o and sched.o). This makefile assumes -that you have set up correctly your LD_LIBRARY_PATH variable -(look, there is a LDADD = -lm -lsimgrid). If you prefer using -the static version, remove the -lsimgrid and add a -$(INSTALL_PATH)/lib/libsimgrid.a on the next line, right -after the LIBS = . - -More generally, if you have never written a Makefile by yourself, type -in a terminal : info make and read the introduction. The -previous example should be enough for a first try but you may want to -perform some more complex compilations... - -\subsection faq_setting_GRAS Setting up your own GRAS code - -If you use the GRAS interface instead of the MSG one, then previous section -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_cmake CMAKE +\section faq_cmake Installing the SimGrid library with Cmake (since V3.4) \subsection faq_intro Some generalitty @@ -354,7 +98,7 @@ CMake is a family of tools designed to build, test and package software. CMake i \subsubsection faq_intro2 Why cmake? -CMake permits to developers to compil projects on different plateform. Then many tools are embedded like ctest for making test, a link to cdash for vizualise results but also test coverage and bug reports. +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? @@ -404,6 +148,7 @@ SET --> CC TO --> C:\MicrosoftVisualStudio10\VC\bin\cl 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 prefix @@ -428,41 +173,8 @@ SET --> CC TO --> C:\MicrosoftVisualStudio10\VC\bin\cl \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. -\verbatim -include/surf/simgrid_dtd.h -include/xbt/graphxml.h - -src/cunit_unit.c -src/ex_unit.c -src/dynar_unit.c -src/dict_unit.c -src/set_unit.c -src/swag_unit.c -src/xbt_str_unit.c -src/xbt_strbuff_unit.c -src/xbt_sha_unit.c -src/config_unit.c -src/xbt_synchro_unit.c -src/simgrid_units_main.c - -src/simdag/dax_dtd.c -src/simdag/dax_dtd.h -src/simdag/dax_dtd.l - -src/surf/simgrid_dtd.c -src/surf/simgrid_dtd.l - -src/xbt/graphxml.c -src/xbt/graphxml.l - -src/gras/DataDesc/ddt_parse.yy.c -\endverbatim + \li enable_supernovae : set to true make one file for each lib and compile with those generated files. -\verbatim -/src/supernovae_sg.c -/src/supernovae_gras.c -/src/supernovae_smpi.c -\endverbatim \li enable_tracing : To enable the generation of simulation traces for visualization @@ -471,6 +183,8 @@ src/gras/DataDesc/ddt_parse.yy.c \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) @@ -498,6 +212,7 @@ enable_tracing off enable_coverage off enable_memcheck off enable_model-checking off +enable_doc off gtnets_path null prefix null @@ -772,7 +487,7 @@ add_executable(get_sender get_sender.c) #add_executable( ) \endverbatim -Then you have to modified /buildtools/Cmake/CMakeMakeExeLib.txt and add +Then you have to modified /buildtools/Cmake/MakeExeLib.cmake and add this line : \verbatim add_subdirectory(${PROJECT_DIRECTORY}/) @@ -780,7 +495,7 @@ add_subdirectory(${PROJECT_DIRECTORY}/) \subsubsection faq_cmakehowto2 Delete/add sources to lib. -If you want modified, add or delete source files from a library you have to edit /buildtools/Cmake/CMakeDefinePackages.txt +If you want modified, add or delete source files from a library you have to edit /buildtools/Cmake/DefinePackages.cmake \verbatim set(JMSG_JAVA_SRC @@ -801,138 +516,395 @@ set(JMSG_JAVA_SRC \subsubsection faq_cmakehowto3 Add test -If you want modified, add or delete tests you have to edit /buildtools/Cmake/CMakeTest.txt -with this function : ADD_TEST( ) +If you want modified, add or delete tests you have to edit /buildtools/Cmake/AddTests.cmake +with this function : ADD_TEST( ) + +\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_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 +installation process. This section is intended to help people that are +not familiar with compiling C files under UNIX. If you follow these +instructions and still have some troubles, drop an e-mail to +. + +\subsection faq_compiling Compiling SimGrid from a stable archive + +First of all, you need to download the latest version of SimGrid from +here. +Suppose you have uncompressed SimGrid in some temporary location of +your home directory (say /home/joe/tmp/simgrid-3.0.1 ). The +simplest way to use SimGrid is to install it in your home +directory. Change your directory to +/home/joe/tmp/simgrid-3.0.1 and type + +\verbatim +./configure --prefix=$HOME +make +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 +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 +make command with script. There is no way for us to help you +without the relevant bits of information. + +Now, the following directory should have been created : + + \li /home/joe/doc/simgrid/html/ + \li /home/joe/lib/ + \li /home/joe/include/ + +SimGrid is not a binary, it is a library. Both a static and a dynamic +version are available. Here is what you can find if you try a ls +/home/joe/lib: + +\verbatim libsimgrid.a libsimgrid.la libsimgrid.so libsimgrid.so.0 libsimgrid.so.0.0.1 +\endverbatim + +Thus, there is two ways to link your program with SimGrid: + \li Either you use the static version, e.g +\verbatim gcc libsimgrid.a -o MainProgram MainProgram.c +\endverbatim + In this case, all the SimGrid functions are directly + included in MainProgram (hence a bigger binary). + \li Either you use the dynamic version (the preferred method) +\verbatim gcc -lsimgrid -o MainProgram MainProgram.c +\endverbatim + In this case, the SimGrid functions are not included in + MainProgram and you need to set your environment + variable in such a way that libsimgrid.so will be + found at runtime. This can be done by adding the following + line in your .bashrc (if you use bash and if you have + installed the SimGrid libraries in your home directory): +\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 +a stable release as long as there is still some known bug in the code base. In +addition, we added quite an extensive test base, making sure that we correctly +test the most important parts of the tool. + +As an unfortunate conclusion, there may be some time between the stable +releases. If you want to benefit from the most recent features we introduced, +but don't want to take the risk of an untested version from the SVN, then +development snapshots are done for you. -\verbatim -add_test(test-simdag-1 ${PROJECT_DIRECTORY}/testsuite/simdag/sd_test --cfg=path:${PROJECT_DIRECTORY}/testsuite/simdag small_platform_variable.xml) -\endverbatim +These are pre-releases of SimGrid that still fail some tests about features +that almost nobody use, or on platforms not being in our core target (which is +Linux, Mac, other Unixes and Windows, from the most important to the less +one). That means that using this development releases should be safe for most +users. -\subsection faq_cmakeExplain Explaination of sources files for cmake +These archives can be found on +this web page. Once you +got the lastest archive, you can compile it just like any archive (see above). -\li CMakeLists.txt +\subsection faq_compiling_svn Compiling SimGrid from the SVN -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. +The project development takes place in the SVN, where all changes are +committed when they happen. Then every once in a while, we make sure that the +code quality meets our standard and release an archive from the code in the +SVN. We afterward go back to the development in the SVN. So, if you need a +recently added feature and can afford some little problem with the stability +of the lastest features, you may want to use the SVN version instead of a +released one. -\li CMakeCompleteInFiles.txt +For that, you first need to get the "simgrid" module from +here. -Complete all .in files and define Variables for h files +You won't find any configure and a few other things +(Makefile.in's, documentation, ...) will be missing as well. The +reason for that is that all these files have to be regenerated using the +latest versions of autoconf, libtool, automake +(>1.9) and doxygen (>1.4). To generate the configure and +the Makefile.in's, you just have to launch the bootstrap +command that resides in the top of the source tree. Then just follow the +instructions of Section \ref faq_compiling. -\li CMakeDocs.txt +We insist on the fact that you really need the latest versions of +autoconf, automake and libtool. Doing this step on exotic architectures/systems +(i.e. anything different from a recent linux distribution) may be +... uncertain. If you need to compile the SVN version on a machine where all these +dependencies are not met, the easiest is to do make dist in the SVN +directory of another machine where all dependencies are met. It will create an +archive you may deploy on other sites just as a regular stable release. -This file make the html documentation. +In summary, the following commands will checkout the SVN, regenerate the +configure script and friends, configure SimGrid and build it. -\li CMakeMakeExeLib.txt +\verbatim svn checkout svn://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk simgrid +cd simgrid +./bootstrap +./configure --enable-maintainer-mode --prefix= +make \endverbatim -Here are callled all "CMakeLists.txt" for make executables and libraries. +Then, if you want to install SimGrid on the current box, just do: +\verbatim make install \endverbatim -\li CMakePrintArgs.txt +If you want to build an snapshot of the SVN to deploy it on another box (for +example because the other machine don't have the autotools), do: +\verbatim make dist \endverbatim -This file is called at the end of the build for summarize environment variables. +Moreover, you should never call the autotools manually since you must run +them in a specific order with specific arguments. Most of the times, the +makefiles will automatically call the tools for you. When it's not possible +(such as the first time you checkout the SVN), use the ./bootstrap command +to call them explicitly. -\li CMakeDefinePackages.txt -Here is defined sources packages for compiling libs. +\subsection faq_setting_MSG Setting up your own MSG code -\li CMakeFlags.txt +Do not build your simulator by modifying the SimGrid examples. Go +outside the SimGrid source tree and create your own working directory +(say /home/joe/SimGrid/MyFirstScheduler/). -Defined flags which are used for compiling sources. +Suppose your simulation has the following structure (remember it is +just an example to illustrate a possible way to compile everything; +feel free to organize it as you want). -\li CMakeSupernovae.txt + \li sched.h: a description of the core of the + scheduler (i.e. which functions are can be used by the + agents). For example we could find the following functions + (master, forwarder, slave). -Here are made files for the supernovae mode. + \li sched.c: a C file including sched.h and + implementing the core of the scheduler. Most of these + functions use the MSG functions defined in section \ref + msg_gos_functions. -\li CMakeDistrib.txt + \li masterslave.c: a C file with the main function, i.e. + the MSG initialization (MSG_global_init()), the platform + creation (e.g. with MSG_create_environment()), the + deployment phase (e.g. with MSG_function_register() and + MSG_launch_application()) and the call to + MSG_main()). -Here is defined packages for install simgrid and make a distribution. +To compile such a program, we suggest to use the following +Makefile. It is a generic Makefile that we have used many times with +our students when we teach the C language. -\li CMakeMaintainerMode.txt +\verbatim +all: masterslave +masterslave: masterslave.o sched.o -Part where are generated source files for maintainer mode. +INSTALL_PATH = $$HOME +CC = gcc +PEDANTIC_PARANOID_FREAK = -O0 -Wshadow -Wcast-align \ + -Waggregate-return -Wmissing-prototypes -Wmissing-declarations \ + -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations \ + -Wmissing-noreturn -Wredundant-decls -Wnested-externs \ + -Wpointer-arith -Wwrite-strings -finline-functions +REASONABLY_CAREFUL_DUDE = -Wall +NO_PRAYER_FOR_THE_WICKED = -w -O2 +WARNINGS = $(REASONABLY_CAREFUL_DUDE) +CFLAGS = -g $(WARNINGS) -\li CMakeOption.txt +INCLUDES = -I$(INSTALL_PATH)/include +DEFS = -L$(INSTALL_PATH)/lib/ +LDADD = -lm -lsimgrid +LIBS = -Here are defined options and initialized values. +%: %.o + $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) $^ $(LIBS) $(LDADD) -o $@ -\li CMakeTest.txt +%.o: %.c + $(CC) $(INCLUDES) $(DEFS) $(CFLAGS) -c -o $@ $< -All tests are listed. +clean: + rm -f $(BIN_FILES) *.o *~ +.SUFFIXES: +.PHONY : clean -\li CTestConfig.cmake +\endverbatim -Properties which link tests with dashboard. +The first two lines indicates what should be build when typing make +(masterslave) and of which files it is to be made of +(masterslave.o and sched.o). This makefile assumes +that you have set up correctly your LD_LIBRARY_PATH variable +(look, there is a LDADD = -lm -lsimgrid). If you prefer using +the static version, remove the -lsimgrid and add a +$(INSTALL_PATH)/lib/libsimgrid.a on the next line, right +after the LIBS = . -\subsection faq_cmakeList List of files added for cmake +More generally, if you have never written a Makefile by yourself, type +in a terminal : info make and read the introduction. The +previous example should be enough for a first try but you may want to +perform some more complex compilations... -Here is a list of files involved into cmake build (relative to project directory path) : -\verbatim +\subsection faq_setting_GRAS Setting up your own GRAS code -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/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 +If you use the GRAS interface instead of the MSG one, then previous section +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 @@ -2111,89 +2083,49 @@ void MC_assert(int prop); Most of Simgrid modules require a good level in C programming , since simgrid is used to be as standard C library . Sometime ( for some reason or another ) developers prefer using some kind of « easy scripts » - (something like … lua ? Ruby ? ...?) or a language easier to code with ( Java ? ) for their works , + (something like … lua ? Ruby ? ...?) or a language easier to code with ( Java ? ) for their works, which avoid dealing with C errors , and sometime an important gain of time (coding-time?) . -Besides Java Binding , Lua and Ruby bindings are available now( since version 3.4 of Simgrid ) -for MSG Module , and we are currenlty working on bindings for other modules . +Besides Java Binding, Lua and Ruby bindings are available now( 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 (Moon for portuguese !) 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 here) \subsubsection faq_binding_lua_why Why lua ? -Lua is a fast,portable and powerful script language , quite simple to use for developpers . +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 , - but this time , code with Lua ;) : +Actually , the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird, + but this time, code with Lua ;) : - 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 -\verbatim -function Master(...) - nb_task = arg[1]; - comp_size = arg[2]; - comm_size = arg[3]; - slave_count = arg[4] - -- Dispatch the tasks - for i=1,nb_task do - tk = simgrid.Task.new("Task "..i,comp_size,comm_size); - alias = "slave "..(i%slave_count); - simgrid.info("Master sending ’" .. simgrid.Task.name(tk) .."’ To ’" .. alias .."’"); - simgrid.Task.send(tk,alias); - simgrid.info("Master done sending ’".. simgrid.Task.name(tk) .."’ To ’" .. alias .."’"); - end - -- Sending Finalize Message To Others - for i=0,slave_count-1 do - alias = "slave "..i; - simgrid.info("Master: sending finalize to "..alias); - finalize = simgrid.Task.new("finalize",comp_size,comm_size); - simgrid.Task.send(finalize,alias) - end -end -\endverbatim -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 . + \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 -\verbatim -function Slave(...) - local my_mailbox="slave "..arg[1] - while true do - local tk = simgrid.Task.recv(my_mailbox); - if (simgrid.Task.name(tk) == "finalize") then - simgrid.info("Slave ’" ..my_mailbox.."’ got finalize msg"); - break - end - simgrid.Task.execute(tk) - end - simgrid.info("Slave ’" ..my_mailbox.."’: I’m Done . See You !!"); -end -\endverbatim -Here , we could see how we use simgrid.Task.recv(alias) to receive a task with a specific alias , +\until end_of_slave +Here, we could see how we use 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 -\verbatim -require "simgrid" -simgrid.platform("my_platform.xml") -simgrid.application("my_deployment.xml") -simgrid.run() -simgrid.info("Simulation’s over.See you.") -simgrid.clean() -\endverbatim +\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. +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 @@ -2204,8 +2136,8 @@ so you can exchange any kind of data ( tables, matrix , strings … ) between p … 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 . Via this key the receiver could access easily to datas . + After creating task, we associate to it various kind of data with a specific key,( string in this case) + to distinguish between data variables. Via this key the receiver could access easily to datas. \li Receiver processe @@ -2216,16 +2148,16 @@ so you can exchange any kind of data ( tables, matrix , strings … ) between p 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 . + 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 ? + 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 ;) ) + ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) ) \li set Hosts @@ -2260,13 +2192,13 @@ so you can exchange any kind of data ( tables, matrix , strings … ) between p 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 . + 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 ;) +Don't forget to register your platform, that SURF callbacks starts their work ;) \li set application \verbatim @@ -2276,17 +2208,101 @@ Don't forget to register your platform , that SURF callbacks starts their work ; 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 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 . +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 ruby 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 MSG::Process 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 : + - MSG::Task.new(task_name,compute_size,communication_size) : to instanciate a new task. + - MSG::Task.send(mailbox) : to send the task via a mailbox alias. + - MSG::Task.name : to get the task's name. + +\li Slave code +\until end_of_slave +to receive a task, we use the method MSG::Task.receive(mailbox) that return a MSG:Task object (received task). + +\li Main chunk +\until MSG.exit + +- MSG.createEnvironment(platform_file) : set up the environment +- MSG.deployApplication(deployment_file) : load the deployment file description. +- MSG.run : 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. + + -MSG::Task.join : 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 + -MSG::Task.data : 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 \subsection faq_trouble_lib_compil SimGrid compilation and installation problems