\subsubsection faq_intro4 Cmake vs Autotools...
-
+TODO
\subsection faq_cmakeoption Cmake options
enable_compile_optimizations ON/OFF or TRUE/FALSE or 1/0
enable_compile_warnings ON/OFF or TRUE/FALSE or 1/0
enable_maintainer_mode ON/OFF or TRUE/FALSE or 1/0
-
- supernovae 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_print_message ON/OFF or TRUE/FALSE or 1/0
gtnets_path <path_to_gtnets_directory>
prefix <path_to_install_directory>
- with_context auto/ucontext/pthread/window
+ BIBTEX2HTML <path_to_bibtex2html>
+ with_context auto/ucontext/pthread/window
\endverbatim
-
+
\subsubsection faq_cmakeoption2 Options explaination
\li disable_gtnets : set to true implie that user doesn't want to use gtnets.
\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_maintainer_mode : set to true make doc and remake files with flex flexml.
+ \li enable_maintainer_mode : set to true it remakes some files.
\verbatim
-/doc/html
-/src/gras/DataDesc/ddt_parse.yy.c
-/src/surf/simgrid_dtd.c
-/src/xbt/graphxml.c
-/src/simdag/dax_dtd.c
-/include/surf/simgrid_dtd.h
-/include/xbt/graphxml.h
-/src/simdag/dax_dtd.h
+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 supernovae : set to true make one file for each lib and compile with those generated files.
+ \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
+
+ \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_print_message : This option when enable permits to see variables from gras_config.h
+
\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.
\subsubsection faq_cmakeoption3 Initialisation
Those options are initialized the first time you launch \"cmake ./\" whithout specified option.
\verbatim
-with_context auto
+disable_gtnets off
+disable_java off
+disable_lua off
+disable_ruby off
+
+enable_compile_optimizations off
+enable_compile_warnings off
enable_maintainer_mode off
-supernovae off
-disable_java off
-disable_lua off
-enable_compile_warnings off
-enable_compile_optimizations off
-disable_gtnets off
-disable_ruby on
+enable_supernovae off
+enable_tracing off
+enable_coverage off
+enable_memcheck off
+enable_print_message off
+
+gtnets_path null
+prefix null
+BIBTEX2HTML null
+with_context auto
\endverbatim
\subsubsection faq_cmakeoption4 Option's cache and how to reset?
\li CMake
\verbatim
cmake ./ configure the project
-make build all tagets
+make build all targets
+make VERBOSE=1 build all targets and print build command lines
make test test all targets and summarize
-make package make the distrib
+make dist make the distrib
+make distcheck check the dist (make + make dist + make test)
make install-simgrid install the project (doc/ lib/ include/)
-make clean" clean all targets
+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
+make maintainer-clean Remove all files generated by mainainer mode
\endverbatim
When the project have been succesfully compiling and build you can make tests.
ctest -D Experimental
ctest -D Experimental(Start|Update|Configure|Build)
ctest -D Experimental(Test|Coverage|MemCheck|Submit)
-ctest -D Nightly
+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_cmakecompilation4 Examples for different mode.
\li Mode maintainer
Here is defined packages for install simgrid and make a distribution.
-\li CMakeFLEXml.txt
+\li CMakeMaintainerMode.txt
-Part for generated sources from flex and flexml.
+Part where are generated source files for maintainer mode.
\li CMakeOption.txt
\verbatim
Cmake sources:
+ ./doc/CMakeLists.txt
./buildtools/Cmake/src/CMakeCompleteInFiles.txt
./buildtools/Cmake/src/CMakeDocs.txt
./buildtools/Cmake/src/CMakeMakeExeLib.txt
./buildtools/Cmake/src/CMakeFlags.txt
./buildtools/Cmake/src/CMakeSupernovae.txt
./buildtools/Cmake/src/CMakeDistrib.txt
- ./buildtools/Cmake/src/CMakeFLEXml.txt
+ ./buildtools/Cmake/src/CMakeMaintainerMode.txt
./buildtools/Cmake/src/CMakeOption.txt
./buildtools/Cmake/src/CMakeTest.txt
./buildtools/Cmake/src/CTestConfig.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
probably be added in the future and many of the previous ones are
experimental and are likely to disappear without notice...
+\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 (const char *filename)</b>: This is the first function to
+be called. It receives a single argument as parameter that contains the name of
+the file that will hold the trace in the end of the simulation. 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_example Example of Instrumentation
+
+A simplified example using the tracing mandatory functions.
+
+\verbatim
+int main (int argc, char **argv)
+{
+ TRACE_start ("traced_simulation.trace");
+ TRACE_category ("request");
+ TRACE_category ("computation");
+ TRACE_category ("finalize");
+
+ MSG_global_init (&argc, &argv);
+
+ //(... 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
+
\section faq_troubleshooting Troubleshooting
\subsection faq_trouble_lib_compil SimGrid compilation and installation problems
