INPUT = doxygen/index.doc \
doxygen/getting_started.doc \
+ doxygen/getting_started_index.doc \
doxygen/introduction.doc \
doxygen/install.doc \
doxygen/use.doc \
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
<doxygenlayout version="1.0">
<!-- Navigation index tabs for HTML output -->
<navindex>
- <tab type="mainpage" visible="yes" title="" />
-
- <tab type="pages" visible="no" title="Table Of Content" intro="Complete pages list">
- <tab type="pages" visible="yes" title="Table Of Content" intro="Complete pages list"/>
- </tab>
- <tab type="namespaces" visible="no" title="">
- <tab type="namespaces" visible="yes" title="" intro=""/>
- <tab type="namespacemembers" visible="yes" title="" intro=""/>
- </tab>
- <tab type="classes" visible="no" title="">
- <tab type="classes" visible="yes" title="" intro=""/>
- <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
- <tab type="hierarchy" visible="yes" title="" intro=""/>
- <tab type="classmembers" visible="yes" title="" intro=""/>
+ <tab type="usergroup" visible="yes" title="Getting started" intro="Getting started" url="@ref getting_started">
+ <tab type="user" visible="yes" url="@ref getting_started" title="What to read" />
+ <tab type="user" visible="yes" url="@ref install" title="Installing SimGrid" />
+ <tab type="user" visible="yes" url="@ref help" title="Getting help" />
</tab>
- <tab type="files" visible="no" title="">
- <tab type="files" visible="yes" title="" intro=""/>
- <tab type="globals" visible="yes" title="" intro=""/>
- </tab>
- <tab type="modules" visible="no" title="" intro="">
- <tab type="modules" visible="yes" title="APIs Reference"
- intro="Here is the hierarchical view of all SimGrid modules. You can reduce the amount of detail with the 'detail level' setting, on the right."/>
+ <tab type="mainpage" visible="yes" title="SimGrid User Documentation" />
+
+ <!--<tab type="pages" visible="yes" title="Table Of Content" intro="Complete pages list">-->
+ <!--<tab type="pages" visible="yes" title="Table Of Content" intro="Complete pages list"/>-->
+ <!--</tab>-->
+ <tab type="usergroup" visible="yes" title="Technical documentation" intro="Technical documentation">
+ <tab type="namespaces" visible="no" title="">
+ <tab type="namespaces" visible="yes" title="" intro=""/>
+ <tab type="namespacemembers" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="classes" visible="no" title="">
+ <tab type="classes" visible="yes" title="" intro=""/>
+ <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+ <tab type="hierarchy" visible="yes" title="" intro=""/>
+ <tab type="classmembers" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="files" visible="no" title="">
+ <tab type="files" visible="yes" title="" intro=""/>
+ <tab type="globals" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="modules" visible="no" title="" intro="">
+ <tab type="modules" visible="yes" title="APIs Reference"
+ intro="Here is the hierarchical view of all SimGrid modules. You can reduce the amount of detail with the 'detail level' setting, on the right."/>
+ </tab>
</tab>
</navindex>
- @subpage bindings
- @subpage pls
-- @subpage internals
-- @subpage contributing
+- @subpage tracing
-*/
\ No newline at end of file
+*/
-/*! \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
-<?xml version='1.0'?>
-<!DOCTYPE platform SYSTEM "http://simgrid.gforge.inria.fr/simgrid.dtd">
-<platform version="3">
- <!-- The master process (with some arguments) -->
- <process host="Tremblay" function="master">
- <argument value="20"/> <!-- Number of tasks -->
- <argument value="50000000"/> <!-- Computation size of tasks -->
- <argument value="1000000"/> <!-- Communication size of tasks -->
- <argument value="Jupiter"/> <!-- First slave -->
- <argument value="Fafard"/> <!-- Second slave -->
- <argument value="Ginette"/> <!-- Third slave -->
- <argument value="Bourassa"/> <!-- Last slave -->
- <argument value="Tremblay"/> <!-- Me! I can work too! -->
- </process>
- <!-- The slave processes (with no argument) -->
- <process host="Tremblay" function="slave"/>
- <process host="Jupiter" function="slave"/>
- <process host="Fafard" function="slave"/>
- <process host="Ginette" function="slave"/>
- <process host="Bourassa" function="slave"/>
-</platform>
-\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 <b>host (mandatory)</b>: the host on which the function will be executed.
-\li <b>process (mandatory)</b>: the process function that will be executed on that host. You can deploy as many process as you want on the same host.
-\li <b>start_time</b>: the (simulated) time when the function will start. Default is zero.
-\li <b>kill_time</b>: 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".
+
*/
-/*! @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
-<a href="http://simgrid.gforge.inria.fr/tutorials.html">tutorials</a>
-on the project web page, looking for the
-<a href="http://simgrid.gforge.inria.fr/tutorials/simgrid-use-101.pdf">SimGrid
-User 101</a> 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: <trace_connect trace="Tremblay_power" element="Tremblay" kind="POWER"/>
+./platforms/two_hosts_platform_with_availability_included.xml:24:<trace_connect kind="POWER" trace="A" element="Cpu A"/>
+./platforms/two_hosts_platform_with_availability_included.xml:25:<trace_connect kind="HOST_AVAIL" trace="A_failure" element="Cpu A"/>
+./platforms/two_hosts_platform_with_availability_included.xml:26:<trace_connect kind="POWER" trace="B" element="Cpu B"/>
+\endverbatim
+
+\note
+ There's also a Section on \ref MSG_examples "examples for MSG".
+
+*/
--- /dev/null
+/*!
+@page getting_started_index Getting Started
+
+- @subpage getting_started
+- @subpage install
+ - @ref help
+- @subpage advanced
+ - @ref bindings
+ - @ref pls
+ - @ref tracing
+ - @ref contributing
+
+*/
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
- <a href="mailto:simgrid-user@lists.gforge.inria.fr">User Mailing list</a>
- - 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
+ <a href="mailto:simgrid-user@lists.gforge.inria.fr">User Mailing list</a> (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
<a href="mailto:simgrid-devel@lists.gforge.inria.fr">Developers Mailing list</a>
- 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
+*/
/*!
-@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"
<tr><td width="50%">
@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
</td><td width="50%" align="center">
-/*! @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).
\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
+*/
-/*! \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
- \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
\subsubsection options_model_network_coord Coordinated-based network models
When you want to use network coordinates, as it happens when you use
-an \<AS\> in your platform file with \c Vivaldi as a routing, you must
+an \<AS\> 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.
-/*! \page platform Step 1: %Model the computation platform
+/*! \page platform Step 1: %Model the underlying platform
@tableofcontents
\subsubsection pf_routing_tag_bypassasroute bypassASroute
-<b>Note : bypassASroute and bypassRoute are under rewriting to perform
-better ; so you may not use it yet</b> %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:
<b>bypassASroute</b> 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).
\subsubsection pf_routing_tag_bypassroute bypassRoute
-<b>Note : bypassASRoute and bypassRoute are under rewriting to perform
-better ; so you may not use it yet</b> %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 :
<b>bypassRoute</b> is the tag you're looking for. It allows to bypass
/*! \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
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.
\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
\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.
\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
\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.
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
\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
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 '<mount ' > ${CMAKE_HOME_DIRECTORY}/doc/example_lists/example_filelist_xmltag_mount
+ COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh '<link_ctn ' > ${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
--- /dev/null
+#!/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