X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/963aa331797f0bc1a8173af4b3970205bcbfbd0c..1cc4b141215ee5de85646a00989478ce9054bebe:/doc/FAQ.doc diff --git a/doc/FAQ.doc b/doc/FAQ.doc index 602c0ed69b..1e10e5f282 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? @@ -492,11 +535,21 @@ Then follow instructions. \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. @@ -510,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 @@ -822,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 @@ -844,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 @@ -852,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 @@ -876,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 @@ -1624,6 +1681,218 @@ 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_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 + +\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 Triva, 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. + +- Installing Triva: the tool is available in the INRIAGforge, +at http://triva.gforge.inria.fr. +Use the following command to get the sources, and then check the file +INSTALL.simplified. 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 + +- Executing Triva: a binary called Triva is available after the + installation (you can execute it passing --help 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 +GNUstep.sh 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 + + -?, --help Give this help list + --usage Give a short usage message +\endverbatim +Triva expects that the user choose one of the available options +(currently --graph or --treemap for a visualization analysis) +and the trace file from the simulation. + +- Understanding Triva - time-slice: the analysis of a trace file using + the tool always takes into account the concept of the time-slice. +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 Time Interval 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 Trace Time, +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 Time Slice Configuration, contains the +aspects related to the time-slice, including its start and its +size. The gray rectangle in the bottom of this part indicates the +current time-slice that is considered for the drawings. If the checkbox +Update Drawings on Sliders Change is not selected, the button +Apply 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 Time Slice Animation 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 Play button in order to see the dynamic +changes on the drawings. +
+\htmlonly + +\endhtmlonly +
+Remarks: 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 +Frequency parameter, but also updates caused by change on configurations +when the checkbox Update Drawings on Sliders +Change is selected will not be followed. + \section faq_troubleshooting Troubleshooting \subsection faq_trouble_lib_compil SimGrid compilation and installation problems