From: Christian Heinrich Date: Tue, 8 Sep 2015 14:25:43 +0000 (+0200) Subject: [Doc] Next major revision of the documentation X-Git-Tag: v3_12~269 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/73e4fd1f87d88fd9396f626cdf5cd50692f1d5e1 [Doc] Next major revision of the documentation This commit changes - the hierarchy of the menu - introduces new menu items, such as a dedicated page linking to other pages that are important to read for the user - it adds a .sh script to automatically generate a list of example files in the platform.doc file --- diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 505dc70ca9..7ea96c54e8 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -644,6 +644,7 @@ WARN_LOGFILE = INPUT = doxygen/index.doc \ doxygen/getting_started.doc \ + doxygen/getting_started_index.doc \ doxygen/introduction.doc \ doxygen/install.doc \ doxygen/use.doc \ @@ -779,7 +780,8 @@ EXCLUDE_SYMBOLS = EXAMPLE_PATH = ./ \ @top_srcdir@/src/surf/ \ @top_srcdir@/src/xbt/ \ - @top_srcdir@/examples + @top_srcdir@/examples \ + @top_srcdir@/doc/example_lists # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp diff --git a/doc/Layout.xml b/doc/Layout.xml index 17001e6319..385846f102 100644 --- a/doc/Layout.xml +++ b/doc/Layout.xml @@ -1,28 +1,35 @@ - - - - - - - - - - - - - - + + + + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/doxygen/advanced.doc b/doc/doxygen/advanced.doc index 614110f384..1ca3d42ee3 100644 --- a/doc/doxygen/advanced.doc +++ b/doc/doxygen/advanced.doc @@ -8,7 +8,6 @@ tutorials. - @subpage bindings - @subpage pls -- @subpage internals -- @subpage contributing +- @subpage tracing -*/ \ No newline at end of file +*/ diff --git a/doc/doxygen/deployment.doc b/doc/doxygen/deployment.doc index 6068893ac2..7199e7a8a5 100644 --- a/doc/doxygen/deployment.doc +++ b/doc/doxygen/deployment.doc @@ -1,45 +1,42 @@ -/*! \page deployment Deployment Description +/*! \page deployment Step 3: Deploy the simulation \section dep_over Overview -When using SimGrid, you basically need your user code, a platform description, and something allowing to map your (simulated) process on your (simulated) platform. This is what deployment file is all about. Note that you can bypass the file stuff and code it directly in your user code, if you want to. - - -\section dep_ex An example -So deployment file just consists of saying which -process runs where and which arguments it should take as input, the easier way to -understand how to write it is just to take a look at the examples. Here is an example of it: - -\verbatim - - - - - - - - - - - - - - - - - - - - - -\endverbatim +When you want to simulate the behavior of your code with SimGrid, you need +to tell SimGrid exactly what code (that you wrote) is supposed to be run by which host - so you need to assign +processes/functions to hosts. The hosts in question here are the hosts of your platform model; see Section \ref platform for details on how to set one up. + +This assignment of the form \c code -> \c host is what the deployment file is all about, which will +be discussed briefly here. + +\note + You can bypass the deployment file by hardcoding it in your user code, at least when you're using + MSG. + +The deployment file looks just like a \ref platform "platform" file, except that in +this case, only two different tags are used: \c process and \c argument, whereas +the latter is just used to supply additional configuration options to the process; the +order in which the \c argument tags are given is important and depends on the application. + +### The process tag ### + +#### Attribute list #### + \section process_tag Process There are optional attributes to the process tag, here is a list of all attributes of process: -\li host (mandatory): the host on which the function will be executed. -\li process (mandatory): the process function that will be executed on that host. You can deploy as many process as you want on the same host. -\li start_time: the (simulated) time when the function will start. Default is zero. -\li kill_time: the (simulated) time when the function will stop. Default is when it's actually finishing. +| Attribute name | Mandatory | Values | Description | +| --------------- | --------- | ---------------------- | ----------- | +| host | yes | String | Describes which host will be used to run this process. The host must be defined in the platform file! | +| process | yes | String | Name of a function that will be executed on this host. This is any function that was registered by #MSG_register_function | +| start_time | no | int (Default: 0) | The simulated time when this function will start to be computed. | +| kill_time | no | int | The simulated time when this function will end to be computed. By default, it stops only when it's done. | + +### An example ### + +A complete example including a \ref MSG_ext_ms_application "deployment file" can be found +in the Section \ref MSG_ex_basics "MSG basics". + */ diff --git a/doc/doxygen/getting_started.doc b/doc/doxygen/getting_started.doc index b4ad556bea..6b86b9bef3 100644 --- a/doc/doxygen/getting_started.doc +++ b/doc/doxygen/getting_started.doc @@ -1,9 +1,71 @@ -/*! @page getting_started SimGrid in 30mn +/*! @page getting_started Getting started with SimGrid! -This page does not exist yet. In the meanwhile, please refer to the -tutorials -on the project web page, looking for the -SimGrid -User 101 tutorial. +\tableofcontents -*/ \ No newline at end of file +Welcome to SimGrid's documentation! %As you may know, SimGrid is (actively +developed) research software and contains many features. This documentation is +\c "work in progress" (and we need the community's help to improve this +documentation! If you're ready to step up and help us, see Section \ref +contributing "Contributing"), but many features are already well described. + +%As for many projects, our documentation consists mostly of documentation +for \ref gs_new_users "new" and \ref gs_experienced_users "experienced" users, but +we also have several pages plus a technical documentation; in addition to that, we have +also written many \ref gs_examples "examples" that you can easily adapt to your +own needs. This page gives you a brief overview of available resources. + +\section gs_introduction Introduction, Installation and how we can help + +| Document name | Description | +| ----------------- | ------------------------------------------------- | +| \ref introduction | Introduces the user to basic features of SimGrid. | +| \ref install | Explains how SimGrid can be installed; this covers Windows as well as Linux; plus, it shows how to install from a package or how to install from source. | +| \ref FAQ | Our FAQ | +| \ref help | There are many ways to find answers to your questions. This document lists them. | + +\section gs_new_users Documentation for new users + +| Document name | Description | +| ----------------- | ------------------------------------------------- | +| \ref introduction | Introduces the user to basic features of SimGrid. | +| \ref install | Explains how SimGrid can be installed; this covers Windows as well as Linux; plus, it shows how to install from a package or how to install from source. | +| [Tutorials](http://simgrid.gforge.inria.fr/tutorials.html) | These tutorials cover most of the basics and might be valuable for what you want to do, especially the [SimGrid User 101](http://simgrid.gforge.inria.fr/tutorials/simgrid-use-101.pdf). | +| \ref MSG_examples | This document explains several tests that we wrote for MSG; these tests are working simulations and you may learn something from looking at them. | + +In order to actually use SimGrid, three steps are necessary: + +\li \ref platform +\li \ref options +\li \ref deployment + +\section gs_experienced_users Documentation for experienced users + +| Document name | Description | +| ----------------- | ------------------------------------------------- | +| \ref tracing | Shows how the behavior of a program can be written to a file so that it can be analyzed. | +| \ref bindings | SimGrid supports many different bindings for languages such as Lua, Ruby, Java, ... You can run your simulations with those! | +| \ref pls | Although SimGrid is not a packet level simulator, it does have bindings to two such simulators. | +| \ref internals | If you want to contribute or obtain a deeper understanding of SimGrid, this is the right location. | + +\section gs_examples Examples shipped with SimGrid + +SimGrid ships with many examples. You can find them in the folder +\c examples/. Especially when you're looking for examples on how to +use a specific XML-tag, this will prove valuable, as you can easily +search through all the files with tools like \c grep. + + +Here is the output of a quick search for examples for \ref pf_trace "trace_connect": + +\verbatim +% grep -R -i -n --include="*.xml" "trace_connect" . +./simdag/two_hosts.xml:22: +./platforms/two_hosts_platform_with_availability_included.xml:24: +./platforms/two_hosts_platform_with_availability_included.xml:25: +./platforms/two_hosts_platform_with_availability_included.xml:26: +\endverbatim + +\note + There's also a Section on \ref MSG_examples "examples for MSG". + +*/ diff --git a/doc/doxygen/getting_started_index.doc b/doc/doxygen/getting_started_index.doc new file mode 100644 index 0000000000..fd207e8750 --- /dev/null +++ b/doc/doxygen/getting_started_index.doc @@ -0,0 +1,13 @@ +/*! +@page getting_started_index Getting Started + +- @subpage getting_started +- @subpage install + - @ref help +- @subpage advanced + - @ref bindings + - @ref pls + - @ref tracing + - @ref contributing + +*/ diff --git a/doc/doxygen/help.doc b/doc/doxygen/help.doc index dc21012e5b..34b8dcc703 100644 --- a/doc/doxygen/help.doc +++ b/doc/doxygen/help.doc @@ -5,19 +5,20 @@ reading the current documentation and studying the provided examples. But if a question remains, don't hesitate to ask to the community. You have several ways of doing so: - - Ask your question to the - User Mailing list - - Asking your quetion on Stack Overflow is also a good idea, as this - site is very well indexed. We answer questions there too (don't - forget to use the SimGrid tag in your question so that we can see - it), and they remain usable for the next users. + - Ask your question on the + User Mailing list (to subscribe, visit the [webinterface](http://lists.gforge.inria.fr/mailman/listinfo/simgrid-user)); + you can also check out [our archives](http://lists.gforge.inria.fr/pipermail/simgrid-user/). - If your question is about the internals and not about using SimGrid, you may prefer to send your question to the Developers Mailing list - Join us on IRC and ask your question directly on the chanel \#simgrid at - irc.debian.org. Be warned that even if many people are connected to + \b irc.debian.org. Be warned that even if many people are connected to the chanel, they may be doing some useful stuff instead of lurking - on IRC. So don't be surprised if you don't get an answer in the + on IRC. So don't be surprised if you don't get an answer in the same second, and turn to the mailing lists if nobody seems to be there. + - Asking your question on Stack Overflow is also a good idea, as this + site is very well indexed. We answer questions there too (don't + forget to use the SimGrid tag in your question so that we can see + it), and they remain usable for the next users. -*/ \ No newline at end of file +*/ diff --git a/doc/doxygen/index.doc b/doc/doxygen/index.doc index 2c4802d752..172ce6ea85 100644 --- a/doc/doxygen/index.doc +++ b/doc/doxygen/index.doc @@ -1,5 +1,5 @@ /*! -@mainpage SimGrid Documentation +@mainpage SimGrid User Documentation @image html simgrid_logo_2011.png "Versatile Simulation of Distributed Systems, for Grids, Clouds, P2P and HPC systems" @image latex simgrid_logo_2011.png "Versatile Simulation of Distributed Systems, for Grids, Clouds, P2P and HPC systems" @@ -10,21 +10,20 @@ @endhtmlonly -- @subpage getting_started - @subpage introduction -- @subpage install - @subpage use - - @ref platform - - @ref deployment - - @ref tracing - - @ref options - @ref help +- @subpage platform +- @subpage options +- @subpage deployment - @subpage advanced - @ref bindings - @ref pls + - @ref tracing - @ref contributing - - @ref internals - @subpage FAQ +- @subpage internals +- @subpage contributing @htmlonly diff --git a/doc/doxygen/internals.doc b/doc/doxygen/internals.doc index c5f74fec19..30e96a8931 100644 --- a/doc/doxygen/internals.doc +++ b/doc/doxygen/internals.doc @@ -1,4 +1,4 @@ -/*! @page internals SimGrid internals +/*! @page internals SimGrid Developer Guide This page does not exist yet, sorry. We are currently refurbishing the user documentation -- the internal documentation will follow (FIXME). @@ -89,4 +89,4 @@ See the \ref XBT_API section for more details. \subsection ug_lucas_layer Tracing simulation Finally, a transversal module allows you to trace your simulation. More documentation in the section \ref TRACE_doc -*/ \ No newline at end of file +*/ diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc index 89af6768d3..979f2c3de1 100644 --- a/doc/doxygen/options.doc +++ b/doc/doxygen/options.doc @@ -1,4 +1,4 @@ -/*! \page options Simgrid options and configurations +/*! \page options Step 2: Configure SimGrid A number of options can be given at runtime to change the default SimGrid behavior. For a complete list of all configuration options @@ -92,7 +92,7 @@ described in - \b LV08 (default one): Realistic network analytic model (slow-start modeled by multiplying latency by 10.4, bandwidth by .92; bottleneck sharing uses a payload of S=8775 for evaluating RTT) - - \b Constant: Simplistic network model where all communication + - \anchor options_model_select_network_constant \b Constant: Simplistic network model where all communication take a constant time (one second). This model provides the lowest realism, but is (marginally) faster. - \b SMPI: Realistic network model specifically tailored for HPC @@ -271,7 +271,8 @@ Note that with the default host model this option is activated by default. \subsubsection options_model_network_coord Coordinated-based network models When you want to use network coordinates, as it happens when you use -an \ in your platform file with \c Vivaldi as a routing, you must +an \ in your platform file with \c Vivaldi as a routing (see also +Section \ref pf_routing_model_vivaldi "Vivaldi Routing Model"), you must set the \b network/coordinates to \c yes so that all mandatory initialization are done in the simulator. diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index a1ca1fa3fb..85d154e0d0 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -1,4 +1,4 @@ -/*! \page platform Step 1: %Model the computation platform +/*! \page platform Step 1: %Model the underlying platform @tableofcontents @@ -1380,11 +1380,10 @@ A route in the \ref pf_routing_model_shortest_path "Shortest-Path routing model" \subsubsection pf_routing_tag_bypassasroute bypassASroute -Note : bypassASroute and bypassRoute are under rewriting to perform -better ; so you may not use it yet %As said before, once you choose -a model, it (if so) calculates routes for you. But maybe you want to +%As said before, once you choose +a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to define some of your routes, which will be specific. You may also want -to bypass some routes defined in lower level AS at an upper stage : +to bypass some routes defined in lower level AS at an upper stage: bypassASroute is the tag you're looking for. It allows to bypass routes defined between already defined between AS (if you want to bypass route for a specific host, you should just use byPassRoute). @@ -1418,9 +1417,8 @@ attribute was not given, this route is presumed to be symmetrical. \subsubsection pf_routing_tag_bypassroute bypassRoute -Note : bypassASRoute and bypassRoute are under rewriting to perform -better ; so you may not use it yet %As said before, once you choose -a model, it (if so) calculates routes for you. But maybe you want to +%As said before, once you choose +a model, it (most likely; the constant network model, for example, doesn't) calculates routes for you. But maybe you want to define some of your routes, which will be specific. You may also want to bypass some routes defined in lower level AS at an upper stage : bypassRoute is the tag you're looking for. It allows to bypass diff --git a/doc/doxygen/pls.doc b/doc/doxygen/pls.doc index b6890c2034..76b528ad8a 100644 --- a/doc/doxygen/pls.doc +++ b/doc/doxygen/pls.doc @@ -1,5 +1,7 @@ /*! \page pls Packet level simulation +\tableofcontents + It is possible to use a packet-level network simulator instead of the default flow-based simulation. You may want to use such an approach if you have doubts about the validity of the default model diff --git a/doc/doxygen/use.doc b/doc/doxygen/use.doc index 38b7a4811f..a7216b4c1c 100644 --- a/doc/doxygen/use.doc +++ b/doc/doxygen/use.doc @@ -2,16 +2,12 @@ This page is under work -- sorry for the inconvinience (FIXME). -- @subpage platform -- @subpage deployment -- @subpage tracing -- @subpage options -- @subpage help +- @ref help \tableofcontents SimGrid comes with many examples provided in the examples/ directory. -Those examples are described in section \ref MSG_examples . Those +Those examples are described in section \ref MSG_examples. Those examples are commented and should be easy to understand. for a first step into SimGrid we also provide some more detailed examples in the sections below. @@ -61,9 +57,9 @@ an external description of the deployment. \paragraph MSG_ext_icomms_Sender Sender function -The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking -we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()". -It also available to "make MSG_comm_wait()" which make both of them. +A host can send an an asynchronous message with \c MSG_task_isend(). %As this function is non-blocking, +we have to call \c MSG_comm_test() to know if the communication has finished and finally destroy it with a call to \c MSG_comm_destroy(). +It is also possible to call \c MSG_comm_wait() which, is provides a shortcut. C style arguments (argc/argv) are interpreted as: - the number of tasks to distribute @@ -80,8 +76,8 @@ It also available to "make MSG_comm_wait()" which make both of them. \paragraph MSG_ext_icomms_Receiver Receiver function -This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know -if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()". +This function executes tasks when it receives them. %As the receiving is asynchronous we have to test the communication to know +if it is completed or not with \c MSG_comm_test() or wait for the completion \c MSG_comm_wait(). C style arguments (argc/argv) are interpreted as: - the id to use for received the communication. @@ -169,7 +165,7 @@ and an external description of the deployment. \paragraph MSG_ext_ms_master Master code -This function has to be assigned to a msg_process_t that will behave as +This function has to be assigned to a #msg_process_t that will behave as the master. It should not be called directly but either given as a parameter to #MSG_process_create() or registered as a public function through #MSG_function_register() and then automatically assigned to a @@ -188,7 +184,7 @@ Tasks are dumbly sent in a round-robin style. \paragraph MSG_ext_ms_slave Slave code This function has to be assigned to a #msg_process_t that has to behave -as a slave. Just like the master fuction (described in \ref +as a slave. Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly. This function keeps waiting for tasks and executes them as it receives them. @@ -201,10 +197,10 @@ This function has to be assigned to a #msg_process_t that has to behave as a forwarder. Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly. -C style arguments (argc/argv) are interpreted as a list of host that +C style arguments (argc/argv) are interpreted as a list of hosts that will accept those tasks. -This function keeps waiting for tasks and dispathes them to its slaves. +This function keeps waiting for tasks and dispatches them to its slaves. \until end_of_forwarder @@ -232,11 +228,13 @@ This initializes MSG, runs a simulation, and free all data-structures created by \subsubsection MSG_ext_ms_helping Helping files -\paragraph MSG_ext_ms_application Example of application file +\paragraph MSG_ext_ms_application Example of a deployment file -\include msg/masterslave/deployment_masterslave.xml +The following listing can be found in \c examples/msg/masterslave/deployment_masterslave_forwarder.xml: -\paragraph MSG_ext_ms_platform Example of platform file +\include msg/masterslave/deployment_masterslave_forwarder.xml + +\paragraph MSG_ext_ms_platform Example of a platform file \include platforms/small_platform.xml diff --git a/tools/cmake/GenerateDoc.cmake b/tools/cmake/GenerateDoc.cmake index 92a4c9bcb8..f20326336f 100644 --- a/tools/cmake/GenerateDoc.cmake +++ b/tools/cmake/GenerateDoc.cmake @@ -70,6 +70,17 @@ if(DOXYGEN_FOUND) COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/index_create.pl simgrid.tag index-API.doc COMMAND ${CMAKE_COMMAND} -E remove ${CMAKE_HOME_DIRECTORY}/doc/doxygen/logcategories.doc COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/xbt_log_extract_hierarchy.pl > ${CMAKE_HOME_DIRECTORY}/doc/doxygen/logcategories.doc + COMMAND ${CMAKE_COMMAND} -E echo "XX Generate list of files in examples/ for routing models" + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh Floyd > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_floyd + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh Dijkstra > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_dijkstra + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh DijkstraCache > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_dijkstra_cache + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh 'routing="None"' > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_none + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh 'routing="Cluster"' > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_cluster + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh 'routing="Vivaldi"' > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_vivaldi + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh 'routing="Full"' > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_routing_full + COMMAND ${CMAKE_COMMAND} -E echo "XX Generate list of files in examples/ for XML tags" + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh ' ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_xmltag_mount + COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh ' ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_xmltag_linkctn COMMAND ${CMAKE_COMMAND} -E echo "XX Run doxygen again" COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile COMMAND ${CMAKE_COMMAND} -E remove ${CMAKE_HOME_DIRECTORY}/doc/simgrid_modules.map diff --git a/tools/doxygen/list_routing_models_examples.sh b/tools/doxygen/list_routing_models_examples.sh new file mode 100755 index 0000000000..7bc3b5e512 --- /dev/null +++ b/tools/doxygen/list_routing_models_examples.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +cd $(dirname $0)/../../ + +# -R -- we want to search recursively +# -l -- only filenames, nothing else +# $1 -- argument to this script, name of the routing model (e.g., "Floyd") +# . -- search in the examples folder and search EVERYTHING +# --include -- but only include results that end in ".xml" +grep -R -l "$1" examples/ --include "*.xml" + +exit 0