X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/b972c0a1648acb5be7b667b7fa91408d8adb890b..2731800aa869070da00bf7d38de0dea3ca71682f:/doc/FAQ.doc diff --git a/doc/FAQ.doc b/doc/FAQ.doc index d399c9fcb9..776663ae3d 100644 --- a/doc/FAQ.doc +++ b/doc/FAQ.doc @@ -388,7 +388,7 @@ CMake needs some prerequists like : \subsubsection faq_intro4 Cmake vs Autotools... - +TODO \subsection faq_cmakeoption Cmake options @@ -405,14 +405,18 @@ CMake needs some prerequists like : 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 prefix - with_context auto/ucontext/pthread/window + 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. @@ -427,27 +431,57 @@ CMake needs some prerequists like : \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 @@ -455,15 +489,24 @@ CMake needs some prerequists like : 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? @@ -495,10 +538,18 @@ cmake ./ configure the project 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 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. @@ -512,12 +563,14 @@ 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 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. (Go to Cdash site). + \subsubsection faq_cmakecompilation4 Examples for different mode. \li Mode maintainer @@ -824,9 +877,9 @@ Here are made files for the supernovae mode. 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 @@ -846,6 +899,7 @@ Here is a list of files involved into cmake build (relative to project directory \verbatim Cmake sources: + ./doc/CMakeLists.txt ./buildtools/Cmake/src/CMakeCompleteInFiles.txt ./buildtools/Cmake/src/CMakeDocs.txt ./buildtools/Cmake/src/CMakeMakeExeLib.txt @@ -854,7 +908,7 @@ Cmake sources: ./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 @@ -878,6 +932,7 @@ Test files for define properties : 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 @@ -1626,6 +1681,133 @@ Possible models for the network are currently "Constant", "CM02", 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 platform +utilization 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. The tasks that are not +classified according to a category are not traced. + +\subsubsection faq_tracing_enabling Enabling using CMake + +With the sources of SimGrid, it is possible to enable the tracing +using the parameter -Dtracing=on 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 \c TRACE_start (const char *filename): 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 \c TRACE_category (const char *category): 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 \c TRACE_msg_set_task_category (m_task_t task, const char *category): +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 \c TRACE_end (): 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 \c TRACE_host_variable_declare (const char *variable): +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 \c TRACE_host_variable_[set|add|sub] (const char *variable, double +value): +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_functions Example + +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