SimGrid requires Lua 5.3; it will not work with Lua 5.2 or Lua 5.1,
-as Lua 5.3 breaks backwards compatibility.
+as Lua 5.3 breaks backwards compatibility.
+Version 5.3.2, 5.3.3 or any 5.3.X are ok, though.
-However, installing Lua 5.3 is easy. (If you're an administrator)
+However, installing Lua 5.3 is easy. (If you are an administrator of your machine)
Step 1: Go to http://www.lua.org/download.html and download the 5.3 package.
Step 3: cd into the new directory
-Step 4: Apply the patch in "<simgrid-source-dir>/contrib/lua/lualib.patch" to the
+Step 4: Apply the patch in "<simgrid-source-dir>/tool/lualib.patch" to the
lua source:
For instance, if you unpacked the lua sourcecode to /tmp/lua-5.3.1, use
the following commands:
- cp contrib/lua/lualib.patch /tmp/lua-5.3.1
+ cp tools/lualib.patch /tmp/lua-5.3.1
cd /tmp/lua-5.3.1/
patch -p1 < lualib.patch
-Step 5: make <platform>, for instance "make linux"
+Step 5: make linux
Step 6: sudo make install
-Step 7: Run ccmake (or supply the config option to cmake) to enable Lua in SimGrid. Done!
+Step 7: Go back to the SimGrid source, and run ccmake again. Try removing CMakeCache.txt if it still complains about Lua being not found.
INPUT = doxygen/index.doc \
doxygen/getting_started.doc \
doxygen/getting_started_index.doc \
- doxygen/introduction.doc \
+ doxygen/tutorial.doc \
doxygen/install.doc \
doxygen/examples.doc \
doxygen/platform.doc \
doxygen/advanced.doc \
doxygen/pls.doc \
doxygen/bindings.doc \
- doxygen/internals.doc \
+ doxygen/inside.doc \
doxygen/inside_doxygen.doc \
doxygen/inside_extending.doc \
doxygen/inside_cmake.doc \
- doxygen/inside_ci.doc \
+ doxygen/inside_tests.doc \
doxygen/inside_release.doc \
doxygen/contributing.doc \
doxygen/tracing.doc \
you could also get in real settings to not hinder the realism of your
simulation.
-\verbatim
+\code
double get_host_load() {
m_task_t task = MSG_task_create("test", 0.001, 0, NULL);
double date = MSG_get_clock();
MSG_task_destroy(task);
return (0.001/date);
}
-\endverbatim
+\endcode
Of course, it may not match your personal definition of "host load". In this
case, please detail what you mean on the mailing list, and we will extend
ready). However, getting the *real* communication time is not really
hard either. The following solution is a good starting point.
-\verbatim
+\code
int sender()
{
m_task_t task = MSG_task_create("Task", task_comp_size, task_comm_size,
MSG_task_destroy(task);
return 0;
}
-\endverbatim
+\endcode
\subsection faq_MIA_SimDag SimDag related questions
create 3 SD_tasks: t1, t2 and c and add dependencies in the following
way:
-\verbatim
+\code
SD_task_dependency_add(NULL, NULL, t1, c);
SD_task_dependency_add(NULL, NULL, c, t2);
-\endverbatim
+\endcode
This way task t2 cannot start before the termination of communication c
which in turn cannot start before t1 ends.
distributed. Here is an example of how you could do that. Assume T1
has to be done before T2.
-\verbatim
+\code
int your_agent(int argc, char *argv[] {
...
T1 = MSG_task_create(...);
}
}
}
-\endverbatim
+\endcode
If you decide that the distributed part is not that much important and that
DAG is really the level of abstraction you want to work with, then you should
don't assume that it's here because we don't care. It survived only
because nobody told us. We unfortunately cannot endlessly review our
large code and documentation base. So please, <b>report any issue you
-find to us</b>, be it a typo in the documentation, a paragraph that
+find</b>, be it a typo in the documentation, a paragraph that
needs to be reworded, a bug in the code or any other problem. The best
way to do so is to open a bug on our
<a href="https://gforge.inria.fr/tracker/?atid=165&group_id=12&func=browse">Bug
\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. |
+| Document name | Description |
+| --------------- | ------------------------------------------------- |
+| \ref tutorial | 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 tutorial | 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. |
| \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. |
+| \ref inside | If you want to contribute or obtain a deeper understanding of SimGrid, this is the right location. |
\section gs_examples Examples shipped with SimGrid
<tr><td width="50%">
@endhtmlonly
-- @subpage introduction
+- @subpage tutorial
- @subpage platform
- @subpage options
- @subpage deployment
- @ref bindings
- @ref pls
- @ref tracing
- - @ref contributing
- @subpage FAQ
-- @subpage internals
+- @subpage inside
+ - @ref inside_tests
+ - @ref inside_doxygen
+ - @ref inside_extending
+ - @ref inside_cmake
+ - @ref inside_release
- @subpage contributing
@htmlonly
-/*! @page internals SimGrid Developer Guide
+/*! @page inside SimGrid Developer Guide
This page does not exist yet, sorry. We are currently refurbishing the
user documentation -- the internal documentation will follow (FIXME).
automatic tests are run, and so on. These informations are split on
several pages, as follows:
+ - @subpage inside_tests
- @subpage inside_doxygen
- @subpage inside_extending
- @subpage inside_cmake
- @subpage inside_release
- - @subpage inside_ci
\htmlonly
+++ /dev/null
-/*!
-\page inside_ci Continous Integration (with Jenkins)
-
-\section ci_jenkins Jenkins Interface
-
-\subsection inside_jenkins_basics Where can I find Jenkins?
-
-The SimGrid team currently uses Jenkins to automate testing. Our Jenkins
-interface can be found here: https://ci.inria.fr/simgrid/
-
-If you need an account, talk to Martin Quinson.
-
-\subsection inside_jenkins_add_host How can I add a new host?
-
-You have to login to the CI interface of INRIA: https://ci.inria.fr
-There you can manage the project and add new nodes.
-
-\subsection inside_jenkins_reboot_host How can I restart / reboot a host?
-
-Exactly the same as in \ref inside_jenkins_add_host. The only exception
-is that you have to click on "restart" of the host you want to restart.
-
-
-\subsection inside_jenkins_config_matrix Disable a certain build in the configuration matrix
-
-Jenkins uses a configuration matrix, i.e., a matrix consisting of configurations
-on the one axis and hosts on the other. Normally, every host will try to build
-every configuration but this may not be desirable.
-
-In order to disable a single configuration for a specific host (but leave
-other configurations for the same host enabled), go to your Project and click
-on "Configuration". There, find the field "combination filter" (if your interface
-language is English) and tick the checkbox; then add a groovy-expression to
-disable a specific configuration. For example, in order to disable the "ModelChecker"
-build on host "small-freebsd-64-clang", use:
-
-\verbatim
-(label=="small-freebsd-64-clang").implies(build_mode!="ModelChecker")
-\endverbatim
-
-\section ci_servers CI Servers
-
-\subsection ci_servers_build_dir Where is SimGrid built?
-
-SimGrid gets built in /builds/workspace/$PROJECT/build_mode/$CONFIG/label/$SERVER/build
-
-Here, $PROJECT could be for instance "SimGrid-Multi", $CONFIG "DEBUG" or "ModelChecker"
-and $SERVER for instance "simgrid-fedora20-64-clang".
-
-*/
to the cmake files: it checks whether all necessary files are present
in the distribution.
-\section cmake_dev_guide_ex How to add examples?
-
-First of all, are you sure that you want to create an example, or is
-it merely a new test case? The examples located in examples/ must be
-interesting to the users. It is expected that the users will take one
-of these examples and start editing it to make it fit their needs. If
-what you are about to write is merly a test, exercising a specific
-part of the tool suite but not really interesting to the users, then
-you want to add it to the teshsuite/ directory.
-
-Actually, the examples are also used as regresion tests by adding tesh
-files and registering them to the testing infrastructure (for that,
-don't forget to add a tesh file and follow the instructions of
-section \ref inside_cmake_addtest). The main difference is that
-examples must be interesting to the users in addition.
-
-In both cases, you have to create a CMakeList.txt in the chosen source
+\section inside_cmake_examples How to add an example?
+
+The first rule is that the content of examples/ must be interesting to
+the users. It is expected that the users will take one of these
+examples and start editing it to make it fit their needs.
+So, it should be self-contained, informative and should use only the
+public APIs.
+
+To ensure that all examples actually work as expected, every examples
+are also used as integration test (see \ref inside_tests), but you
+should still strive to keep the code under examples/ as informative as
+possible for the users. In particular, torture test cases should be
+placed in teshsuite/, not examples/, so that the users don't stumble
+upon them by error.
+
+To add a new example, create a CMakeList.txt in the chosen source
directory. It must specify where to create the executable, the source
list, dependencies and the name of the binary.
\verbatim
-cmake_minimum_required(VERSION 2.6)
-
set(EXECUTABLE_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}")
add_executable(Hello Hello.c)
)
\endverbatim
-\li if you add tesh files (and you should), please refer to the
-following section to register them to the testing infrastructure.
+\li Add the tesh file and register your example to the testing
+ infrastructure. See \ref inside_tests_add_integration for more
+ details.
-Once you're done, you should check with "make distcheck" that you did
+Once you're done, you must run "make distcheck" to ensure that you did
not forget to add any file to the distributed archives.
-\section inside_cmake_addtest How to add tests?
-
-\subsection inside_cmake_addtest_unit Unit testing in SimGrid
-
-If you want to test a specific function or set of functions, you need
-a unit test. Edit
-<project/directory>/tools/cmake/UnitTesting.cmake to add your
-source file to the TEST_CFILES list, and add the corresponding unit
-file to the TEST_UNITS list. For example, if your file is toto.c,
-your unit file will be toto_unit.c. The full path to your file must be
-provided, but the unit file will always be in src/ directly.
-
-Then, you want to actually add your tests in the source file. All the
-tests must be protected by "#ifdef SIMGRID_TEST" so that they don't
-get included in the regular build. Then, you want to add a test suite
-that will contain a bunch of tests (in Junit, that would be a test
-unit) with the macro #XBT_TEST_SUITE, and populate it with a bunch of
-actual tests with the macro #XBT_TEST_UNIT (sorry for the mischosen
-names if you are used to junit). Just look at the dynar example (or
-any other) to see how it works in practice. Do not hesitate to stress
-test your code this way, but make sure that it runs reasonably fast,
-or nobody will run "ctest" before commiting code.
-
-If you are interested in the mechanic turning this into an actual
-test, check the <project/directory>/tools/sg_unit_extractor.pl script.
-
-To actually run your tests once you're done, run "make testall", that
-builds the binary containing all our unit tests and run it. This
-binary allows you to chose which suite you want to test:
-
-\verbatim
-$ testall --help # revise how it goes if you forgot
-$ testall --dump-only # learn about all existing test suites
-$ testall --tests=-all # run no test at all
-$ testall --tests=-all,+foo # run only the foo test suite.
-$ testall --tests=-all,+foo:bar # run only the bar test from the foo suite.
-$ testall --tests=-foo:bar # run all tests but the bar test from the foo suite.
-\endverbatim
-
-\subsection inside_cmake_addtest_integration Integration testing in SimGrid
-
-If you want to test a full binary (such as an example), then you
-probably want to use the tesh binary that ensures that the output
-produced by a command perfectly matches the expected output. In
-particular, this is very precious to ensure that no change modifies
-the timings computed by the models without notice.
-
-The first step is to write a tesh file for your test, containing the
-command to run, the provided input (if any, but almost no SimGrid test
-provide such an input) and the expected output. Check the tesh man
-page for more details.
-
-Tesh is sometimes annoying as you have to ensure that the expected
-output will always be exactly the same. In particular, your should not
-output machine dependent informations, nor memory adresses as they
-would change on each run. Several steps can be used here, such as the
-obfucation of the memory adresses unless the verbose logs are
-displayed (using the #XBT_LOG_ISENABLED() macro), or the modification
-of the log formats to hide the timings when they depend on the host
-machine.
-
-Then you have to request cmake to run your test when "ctest" is
-launched. For that, you have to modify source
-<project/directory>/tools/cmake/Tests.cmake. Make sure to pick
-a wise name for your test. It is often useful to check a category of
-tests together. The only way to do so in ctest is to use the -R
-argument that specifies a regular expression that the test names must
-match. For example, you can run all MSG test with "ctest -R msg" That
-explains the importance of the test names.
-
-Once the name is chosen, create a new test by adding a line similar to
-the following (assuming that you use tesh as expected).
-
-\verbatim
-# ADD_TEST(test-name ${CMAKE_BINARY_DIR}/bin/tesh <options> <tesh-file>)
-# option --setenv bindir set the directory containing the binary
-# --setenv srcdir set the directory containing the source file
-# --cd set the working directory
-ADD_TEST(my-test-name ${CMAKE_BINARY_DIR}/bin/tesh
- --setenv bindir=${CMAKE_BINARY_DIR}/examples/my-test/
- --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/my-test/
- --cd ${CMAKE_HOME_DIRECTORY}/examples/my-test/
- ${CMAKE_HOME_DIRECTORY}/examples/msg/io/io.tesh
-)
-\endverbatim
-
-If you prefer to not use tesh for some reasons, prefer the following
-form:
-
-\verbatim
-# ADD_TEST(NAME <name>]
-# [WORKING_DIRECTORY dir]
-# COMMAND <command> [arg1 [arg2 ...]])
-ADD_TEST(NAME my-test-name
- WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/examples/my-test/
- COMMAND Hello
-)
-\endverbatim
-
-As usual, you must run "make distcheck" after modifying the cmake files,
-to ensure that you did not forget any files in the distributed archive.
-
-\subsection inside_cmake_ci Continous Integration
-
-We are using Continous Integration to help us provide a stable build
-across as many platforms as possible. %As this is not related to cmake,
-you have to head over to Section \ref inside_ci.
*/
/*!
-\page inside_release SimGrid Developer Guide - Releasing
+\page inside_release Releasing SimGrid
\section inside_release_c Releasing the main library
--- /dev/null
+/*!
+@page inside_tests Testing SimGrid
+
+This page will teach you how to run the tests, selecting the ones you
+want, and how to add new tests to the archive.
+
+\tableofcontents
+
+SimGrid code coverage is usually between 70% and 80%, which is much
+more than most projects out there. This is because we consider SimGrid
+to be a rather complex project, and we want to modify it with less fear.
+
+We have two sets of tests in SimGrid: Each of the 10,000+ unit tests
+check one specific case for one specific function, while the 500+
+integration tests run a given simulation specifically intended to
+exercise a larger amount of functions together. Every example provided
+in examples/ is used as an integration test, while some other torture
+tests and corner cases integration tests are located in teshsuite/.
+For each integration test, we ensure that the output exactly matches
+the defined expectations. Since SimGrid displays the timestamp of
+every loggued line, this ensures that every change of the models'
+prediction will be noticed. All these tests should ensure that SimGrid
+is safe to use and to depend on.
+
+\section inside_tests_runintegration Running the tests
+
+Running the tests is done using the ctest binary that comes with
+cmake. These tests are run for every commit and the result is publicly
+<a href="https://ci.inria.fr/simgrid/">available</a>.
+
+\verbatim
+ctest # Launch all tests
+ctest -R msg # Launch only the tests which name match the string "msg"
+ctest -j4 # Launch all tests in parallel, at most 4 at the same time
+ctest --verbose # Display all details on what's going on
+ctest --output-on-failure # Only get verbose for the tests that fail
+
+ctest -R msg- -j5 --output-on-failure # You changed MSG and want to check that you didn't break anything, huh?
+ # That's fine, I do so all the time myself.
+\endverbatim
+
+\section inside_tests_rununit Running the unit tests
+
+All unit tests are packed into the testall binary, that lives in src/.
+These tests are run when you launch ctest, don't worry.
+
+\verbatim
+make testall # Rebuild the test runner on need
+./src/testall # Launch all tests
+./src/testall --help # revise how it goes if you forgot
+./src/testall --tests=-all # run no test at all (yeah, that's useless)
+./src/testall --dump-only # Display all existing test suite
+./src/testall --tests=-all,+dict # Only launch the tests from the dict testsuite
+./src/testall --tests=-all,+foo:bar # run only the bar test from the foo suite.
+\endverbatim
+
+
+\section inside_tests_add_units Adding unit tests
+
+If you want to test a specific function or set of functions, you need
+a unit test. Edit
+<project/directory>/tools/cmake/UnitTesting.cmake to add your
+source file to the TEST_CFILES list, and add the corresponding unit
+file to the TEST_UNITS list. For example, if your file is toto.c,
+your unit file will be toto_unit.c. The full path to your file must be
+provided, but the unit file will always be in src/ directly.
+
+If you want to create unit tests in the file src/xbt/toto.c, your
+changes should look similar to:
+
+\verbatim
+--- a/tools/cmake/UnitTesting.cmake
++++ b/tools/cmake/UnitTesting.cmake
+@@ -11,6 +11,7 @@ set(TEST_CFILES
+ src/xbt/xbt_strbuff.c
+ src/xbt/xbt_sha.c
+ src/xbt/config.c
++ src/xbt/toto.c
+ )
+ set(TEST_UNITS
+ ${CMAKE_CURRENT_BINARY_DIR}/src/cunit_unit.c
+@@ -22,6 +23,7 @@ set(TEST_UNITS
+ ${CMAKE_CURRENT_BINARY_DIR}/src/xbt_strbuff_unit.c
+ ${CMAKE_CURRENT_BINARY_DIR}/src/xbt_sha_unit.c
+ ${CMAKE_CURRENT_BINARY_DIR}/src/config_unit.c
++ ${CMAKE_CURRENT_BINARY_DIR}/src/toto_unit.c
+
+ ${CMAKE_CURRENT_BINARY_DIR}/src/simgrid_units_main.c
+ )
+\endverbatim
+
+Then, you want to actually add your tests in the source file. All the
+tests must be protected by "#ifdef SIMGRID_TEST" so that they don't
+get included in the regular build. The line SIMGRID_TEST must also be
+written on the endif line for the extraction script to work properly.
+
+Tests are subdivided in three levels. The top-level, called <b>test
+suite</b>, is created with the macro #XBT_TEST_SUITE. There can be
+only one suite per source file. A suite contains <b>test units</b>
+that you create with the #XBT_TEST_UNIT macro. Finally, you start
+<b>actual tests</b> with #xbt_test_add. There is no closing marker of
+any sort, and an unit is closed when the next unit starts, or when the
+end of file is reached.
+
+Once a given test is started with #xbt_test_add, you use
+#xbt_test_assert to specify that it was actually an assert, or
+#xbt_test_fail to specify that it failed (if your test cannot easily
+be written as an assert). #xbt_test_exception can be used to report
+that it failed with an exception. There is nothing to do to report
+that a given test succeeded, just start the next test without
+reporting any issue. Finally, #xbt_test_log can be used to report
+intermediate steps. The messages will be shown only if the
+corresponding test fails.
+
+Here is a recaping example, inspired from the dynar implementation.
+@code
+/* The rest of your module implementation */
+
+#ifdef SIMGRID_TEST
+
+XBT_TEST_SUITE("dynar", "Dynar data container");
+XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(xbt_dyn); // Just the regular logging stuff
+
+XBT_TEST_UNIT("int", test_dynar_int, "Dynars of integers")
+{
+ int i, cpt;
+ unsigned int cursor;
+
+ xbt_test_add("==== Traverse the empty dynar");
+ xbt_dynar_t d = xbt_dynar_new(sizeof(int), NULL);
+ xbt_dynar_foreach(d, cursor, i) {
+ xbt_test_fail( "Damnit, there is something in the empty dynar");
+ }
+ xbt_dynar_free(&d);
+
+ xbt_test_add("==== Push %d int and re-read them", NB_ELEM);
+ d = xbt_dynar_new(sizeof(int), NULL);
+ for (cpt = 0; cpt < NB_ELEM; cpt++) {
+ xbt_test_log("Push %d, length=%lu", cpt, xbt_dynar_length(d));
+ xbt_dynar_push_as(d, int, cpt);
+ }
+
+ for (cursor = 0; cursor < NB_ELEM; cursor++) {
+ int *iptr = xbt_dynar_get_ptr(d, cursor);
+ xbt_test_assert(cursor == *iptr,
+ "The retrieved value is not the same than the injected one (%u!=%d)",cursor, cpt);
+ }
+
+ xbt_test_add("==== Check the size of that %d-long dynar", NB_ELEM);
+ xbt_test_assert(xbt_dynar_size(d) == NB_ELEM);
+ xbt_dynar_free(&d);
+}
+
+XBT_TEST_UNIT("insert",test_dynar_insert,"Using the xbt_dynar_insert and xbt_dynar_remove functions")
+{
+ xbt_dynar_t d = xbt_dynar_new(sizeof(unsigned int), NULL);
+ unsigned int cursor;
+ int cpt;
+
+ xbt_test_add("==== Insert %d int, traverse them, remove them",NB_ELEM);
+ // BLA BLA BLA
+}
+
+#endif /* SIMGRID_TEST <-- that string must appear on the endif line */
+@endcode
+
+For more details on the macro used to write unit tests, see their
+reference guide: @ref XBT_cunit. For details on on how the tests are
+extracted from the module source, check the tools/sg_unit_extractor.pl
+script directly.
+
+Last note: please try to keep your tests fast. We run them very very
+very often, and you should strive to make it as fast as possible, to
+not upset the other developers. Do not hesitate to stress test your
+code with such unit tests, but make sure that it runs reasonably fast,
+or nobody will run "ctest" before commiting code.
+
+\section inside_tests_add_integration Adding integration tests
+
+TESH (the TEsting SHell) is the test runner that we wrote for our
+integration tests. It is distributed with the SimGrid source file, and
+even comes with a man page. TESH ensures that the output produced by a
+command perfectly matches the expected output. This is very precious
+to ensure that no change modifies the timings computed by the models
+without notice.
+
+To add a new integration test, you thus have 3 things to do:
+
+ - <b>Write the code exercising the feature you target</b>. You should
+ strive to make this code clear, well documented and informative for
+ the users. If you manage to do so, put this somewhere under
+ examples/ and modify the cmake files as explained on this page:
+ \ref inside_cmake_examples. If you feel like you should write a
+ torture test that is not interesting to the users (because nobody
+ would sainly write something similar in user code), then put it under
+ teshsuite/ somewhere.
+ - <b>Write the tesh file</b>, containing the command to run, the
+ provided input (if any, but almost no SimGrid test provide such an
+ input) and the expected output. Check the tesh man page for more
+ details. \n
+ Tesh is sometimes annoying as you have to ensure that the expected
+ output will always be exactly the same. In particular, your should
+ not output machine dependent informations, nor memory adresses as
+ they would change on each run. Several steps can be used here, such
+ as the obfucation of the memory adresses unless the verbose logs
+ are displayed (using the #XBT_LOG_ISENABLED() macro), or the
+ modification of the log formats to hide the timings when they
+ depend on the host machine.
+ - <b>Add your test in the cmake infrastructure</b>. For that, modify
+ the file <project/directory>/tools/cmake/Tests.cmake. Make sure to
+ pick a wise name for your test. It is often useful to check a
+ category of tests together. The only way to do so in ctest is to
+ use the -R argument that specifies a regular expression that the
+ test names must match. For example, you can run all MSG test with
+ "ctest -R msg". That explains the importance of the test names.
+
+Once the name is chosen, create a new test by adding a line similar to
+the following (assuming that you use tesh as expected).
+
+\verbatim
+# Usage: ADD_TEST(test-name ${CMAKE_BINARY_DIR}/bin/tesh <options> <tesh-file>)
+# option --setenv bindir set the directory containing the binary
+# --setenv srcdir set the directory containing the source file
+# --cd set the working directory
+ADD_TEST(my-test-name ${CMAKE_BINARY_DIR}/bin/tesh
+ --setenv bindir=${CMAKE_BINARY_DIR}/examples/my-test/
+ --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/my-test/
+ --cd ${CMAKE_HOME_DIRECTORY}/examples/my-test/
+ ${CMAKE_HOME_DIRECTORY}/examples/msg/io/io.tesh
+)
+\endverbatim
+
+As usual, you must run "make distcheck" after modifying the cmake files,
+to ensure that you did not forget any files in the distributed archive.
+
+\section inside_tests_ci Continous Integration
+
+We use several systems to automatically test SimGrid with a large set
+of parameters, across as many platforms as possible.
+We use <a href="https://ci.inria.fr/simgrid/">Jenkins on Inria
+servers</a> as a workhorse: it runs all of our tests for many
+configurations. It takes a long time to answer, and it often reports
+issues but when it's green, then you know that SimGrid is very fit!
+We use <a href="https://travis-ci.org/mquinson/simgrid">Travis</a> to
+quickly run some tests on Linux and Mac. It answers quickly but may
+miss issues. And we use <a href="https://ci.appveyor.com/project/mquinson/simgrid">AppVeyor</a>
+to build and somehow test SimGrid on windows.
+
+\subsection inside_tests_jenkins Jenkins on the Inria CI servers
+
+You should not have to change the configuration of the Jenkins tool
+yourself, although you could have to change the slaves' configuration
+using the <a href="https://ci.inria.fr">CI interface of INRIA</a> --
+refer to the <a href="https://wiki.inria.fr/ciportal/">CI documentation</a>.
+
+The result can be seen here: https://ci.inria.fr/simgrid/
+
+We have 3 projects on Jenkins:
+\li <a href="https://ci.inria.fr/simgrid/job/SimGrid-Multi/">SimGrid-Multi</a>
+ is the main project, running the tests that we spoke about.\n It is
+ configured (on Jenkins) to run the script <tt>tools/jenkins/build.sh</tt>
+\li <a href="https://ci.inria.fr/simgrid/job/SimGrid-DynamicAnalysis/">SimGrid-DynamicAnalysis</a>
+ runs the tests both under valgrind to find the memory errors and
+ under gcovr to report the achieved test coverage.\n It is configured
+ (on Jenkins) to run the script <tt>tools/jenkins/DynamicAnalysis.sh</tt>
+\li <a href="https://ci.inria.fr/simgrid/job/SimGrid-Windows/">SimGrid-Windows</a>
+ is an ongoing attempt to get Windows tested on Jenkins too.
+
+In each case, SimGrid gets built in
+/builds/workspace/$PROJECT/build_mode/$CONFIG/label/$SERVER/build
+with $PROJECT being for instance "SimGrid-Multi", $CONFIG "DEBUG" or
+"ModelChecker" and $SERVER for instance "simgrid-fedora20-64-clang".
+
+If some configurations are known to fail on some systems (such as
+model-checking on non-linux systems), go to your Project and click on
+"Configuration". There, find the field "combination filter" (if your
+interface language is English) and tick the checkbox; then add a
+groovy-expression to disable a specific configuration. For example, in
+order to disable the "ModelChecker" build on host
+"small-freebsd-64-clang", use:
+
+\verbatim
+(label=="small-freebsd-64-clang").implies(build_mode!="ModelChecker")
+\endverbatim
+
+\subsection inside_tests_travis Travis
+
+Travis is a free (as in free beer) Continuous Integration system that
+open-sourced project can use freely. It is very well integrated in the
+GitHub ecosystem. There is a plenty of documentation out there. Our
+configuration is in the file .travis.yml as it should be, and the
+result is here: https://travis-ci.org/mquinson/simgrid
+
+\subsection inside_tests_appveyor AppVeyor
+
+AppVeyor aims at becoming the Travis of Windows. It is maybe less
+mature than Travis, or maybe it is just that I'm less trained in
+Windows. Our configuration is in the file appveyor.yml as it should
+be, and the result is here: https://ci.appveyor.com/project/mquinson/simgrid
+
+It should be noted that I miserably failed to use the environment
+provided by AppVeyor, since SimGrid does not build with Microsoft
+Visual Studio. Instead, we download a whole development environment
+from the internet at each build. That's an archive of already compiled
+binaries that are unpacked on the appveyor systems each time we start.
+We re-use the ones from the
+<a href="https://github.com/symengine/symengine">symengine</a>
+project. Thanks to them for compiling sane tools and constituting that
+archive, it saved my mind!
+
+*/
The easiest way to install SimGrid is to go for a binary package.
Under Debian or Ubuntu, this is very easy as SimGrid is directly
-integrated to the official repositories. Under Windows, SimGrid can be
-installed in a few clicks once you downloaded the installer from
-gforge. If you just want to use Java, simply copy the jar file on your
-disk and you're set.
+integrated to the official repositories. If you just want to use
+Java, simply copy the jar file on your disk and you're set. Note that
+under Windows, you should go for Java, as the native C interface is
+not supported on that OS.
Recompiling an official archive is not much more complex, actually.
SimGrid has very few dependencies and rely only on very standard
Please contact us if you want to contribute the build scripts for your
preferred distribution.
-@subsection install_binary_win Installation wizard for Windows
-
-Before starting the installation, make sure that you have the following dependencies:
- @li cmake 2.8 <a href="http://www.cmake.org/cmake/resources/software.html">(download page)</a>
- @li MinGW <a href="http://sourceforge.net/projects/mingw/files/MinGW/">(download page)</a>
- @li perl <a href="http://www.activestate.com/activeperl/downloads">(download page)</a>
- @li git <a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">(download page)</a>
-
-Then download the package <a href="https://gforge.inria.fr/frs/?group_id=12">SimGrid Installer</a>,
-execute it and follow instructions.
-
-@image html win_install_01.png Step 1: Accept the license.
-@image html win_install_02.png Step 2: Select packets to install.
-@image html win_install_03.png Step 3: Choice where to install packets previously selected. Please don't use spaces in path.
-@image html win_install_04.png Step 4: Add CLASSPATH to environment variables.
-@image html win_install_05.png Step 5: Add PATH to environment variables.
-@image html win_install_06.png Step 6: Restart your computer to take in consideration environment variables.
-
@subsection install_binary_java Using the binary jar file
The easiest way to install the Java bindings of SimGrid is to grab the
supported, drop us an email: we may extend the jarfile for you, if we
have access to your architecture to build SimGrid on it.
+If the error message is about the boost-context library, then you
+should install that library on your machine. This is a known issue in
+the 3.12 release that will be fixed in the next release.
+
+You can retrieve a nightly build of the jar file from our autobuilders.
+For Windows, head to
+<a href="https://ci.appveyor.com/project/mquinson/simgrid">AppVeyor</a>.
+Click on the artefact link on the right, and grab your file. If the
+latest build failed, there will be no artefact so you will need to
+first click on "History" on the top to search for the last successful
+build.
+For non-Windows systems (Linux, Mac or FreeBSD), head to
+<a href="https://ci.inria.fr/simgrid/job/SimGrid-Multi">Jenkins</a>.
+In the build history, pick the last green (or at least yellow) build
+that is not blinking (ie, that is done building). In the list, pick a
+system that is close to your system, and click on the ball in the
+Debug row. The build artefact appear on the top of the resulting page.
+
@section install_src Installing from source
@subsection install_src_deps Resolving the dependencies
- perl (but you may try to go without it)
- We use cmake to configure our compilation
(<a href="http://www.cmake.org/cmake/resources/software.html">download page</a>).
- You need cmake version 2.8 or higher. You may want to use ccmake
+ You need cmake version 2.8.8 or higher. You may want to use ccmake
for a graphical interface over cmake.
- LibBoost:
- osX: with <a href="http://www.finkproject.org/">fink</a>: `sudo fink install boost1.53.nopython`
- - debian: `apt-get install libboost-dev`
+ - debian: `apt-get install libboost-dev libboost-context-dev`
On MacOSX, it is advised to use the clang compiler (version 3.0 or
-higher), from either MacPort or XCode. If you insist on using gcc on
-this system, you still need a recent version of this compiler, so you
-need an unofficial gcc47 from MacPort because the version provided by
-Apple is ways to ancient to suffice. See also @ref install_cmake_mac.
-
-On Windows, it is strongly advised to use the
-<a href="http://sourceforge.net/projects/mingw/files/MinGW/">MinGW
-environment</a> to build SimGrid, with <a href="http://www.mingw.org/wiki/MSYS">
-MSYS tools</a> installed. Any other compilers are not tested
-(and thus probably broken). We usually use the
+higher), from either MacPort or XCode. See also @ref install_cmake_mac.
+
+Building from the source on Windows, may be something of an adventure.
+We never managed to compile SimGrid with something else than MinGW-64
+ourselves. We usually use the
<a href="http://www.activestate.com/activeperl/downloads">activestate</a>
version of Perl, and the
<a href="http://msysgit.googlecode.com/files/Git-1.7.4-preview20110204.exe">msys</a>
-version of git on this architecture, but YMMV. See also @ref install_cmake_win.
+version of git on this architecture, but YMMV. You can have a look at
+the configuration scripts in the appveyor.yml file, but you are
+basically on your own here. Sorry. We are not fluent with Windows so
+we cannot really help.
@subsection install_src_fetch Retrieving the source
make
@endverbatim
-\subsubsection install_cmake_win Cmake on Windows (with MinGW + MSYS)
-
-Cmake can produce several kind of of makefiles. Under Windows, it has
-no way of determining what kind you want to use, so you have to hint it:
-
-@verbatim
-cmake -G "MSYS Makefiles" (other options) .
-make
-@endverbatim
-
\subsubsection install_cmake_mac Cmake on Mac OS X
SimGrid compiles like a charm with clang on Mac OS X:
Once everything is built, you may want to test the result. SimGrid
comes with an extensive set of regression tests (see @ref
-inside_cmake_addtest "that page of the insider manual" for more
+inside_tests "that page of the insider manual" for more
details). Running the tests is done using the ctest binary that comes
-with cmake. These tests are run every night and the result is publicly
-<a href="http://cdash.inria.fr/CDash/index.php?project=Simgrid">available</a>.
+with cmake. These tests are run for every commit and the result is
+publicly <a href="https://ci.inria.fr/simgrid/">available</a>.
\verbatim
ctest # Launch all tests
-ctest -D Experimental # Launch all tests and report the result to
- # http://cdash.inria.fr/CDash/index.php?project=SimGrid
ctest -R msg # Launch only the tests which name match the string "msg"
ctest -j4 # Launch all tests in parallel, at most 4 at the same time
ctest --verbose # Display all details on what's going on
\section install_setting_own Setting up your own code
-\subsection install_setting_MSG MSG code on Unix (Linux or Mac OSX)
+\subsection install_setting_MSG MSG code on Unix
Do not build your simulator by modifying the SimGrid examples. Go
outside the SimGrid source tree and create your own working directory
perform some more complex compilations...
-\subsection install_setting_win_provided Compile the "HelloWorld" project on Windows
-
-In the SimGrid install directory you should have an HelloWorld project to explain you how to start
-compiling a source file. There are:
-\verbatim
-- HelloWorld.c The example source file.
-- CMakeLists.txt It allows to configure the project.
-- README This explanation.
-\endverbatim
-
-Now let's compile this example:
-\li Run windows shell "cmd".
-\li Open HelloWorld Directory ('cd' command line).
-\li Create a build directory and change directory. (optional)
-\li Type 'cmake -G"MinGW Makefiles" \<path_to_HelloWorld_project\>'
-\li Run mingw32-make
-\li You should obtain a runnable example ("HelloWorld.exe").
-
-For compiling your own code you can simply copy the HelloWorld project and rename source name. It will
-create a target with the same name of the source.
-
-
-\subsection install_setting_win_new Adding and Compiling a new example on Windows
-
-\li Put your source file into the helloWord directory.
-\li Edit CMakeLists.txt by removing the Find Targets section and add those two lines into this section
-\verbatim
-################
-# FIND TARGETS #
-################
-#It creates a target called 'TARGET_NAME.exe' with the sources 'SOURCES'
-add_executable(TARGET_NAME SOURCES)
-#Links TARGET_NAME with simgrid
-target_link_libraries(TARGET_NAME simgrid)
-\endverbatim
-\li To initialize and build your project, you'll need to run
-\verbatim
-cmake -G"MinGW Makefiles" <path_to_HelloWorld_project>
-\endverbatim
-\li Run "mingw32-make"
-\li You should obtain "TARGET_NAME.exe".
-
-\subsection install_Win_ruby Setup a virtualbox to use SimGrid-Ruby on windows
-
-Allan Espinosa made these set of Vagrant rules available so that you
-can use the SimGrid Ruby bindings in a virtual machine using
-VirtualBox. Thanks to him for that. You can find his project here:
-https://github.com/aespinosa/simgrid-vagrant
-
-
-
*/
<b>Example:</b>
-\verbatim
+\code
<AS id="AS0" routing="Full">
<host id="host1" power="1000000000"/>
<host id="host2" power="1000000000"/>
<link id="link1" bandwidth="125000000" latency="0.000100"/>
<route src="host1" dst="host2"><link_ctn id="link1"/></route>
</AS>
-\endverbatim
+\endcode
In this example, AS0 contains two hosts (host1 and host2). The route
between the hosts goes through link1.
-/*! @page introduction Introduction to SimGrid
+/*! @page tutorial SimGrid First Tutorial
+SimGrid is a toolkit providing the core functionalities for the
+simulation of distributed applications in heterogeneous distributed
+environments.
-[SimGrid](http://simgrid.gforge.inria.fr/) is a toolkit
-that provides core functionalities for the simulation of distributed
-applications in heterogeneous distributed environments.
-
-The specific goal of the project is to facilitate research in the area of
-distributed and parallel application scheduling on distributed computing
-platforms ranging from simple network of workstations to Computational
-Grids.
+The project goal is both to facilitate research and to help improving
+real applications in the area of distributed and parallel systems,
+ranging from simple network of workstations to Computational Grids to
+Clouds and to supercomputers.
\tableofcontents
if args.topology ~= "TORUS" and args.topology ~= "FAT_TREE" then
args.topology = "Cluster"
end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
- --if args.core==nil then args.core = 1 end
-- Check the mode = Cluster here
return function()
/**
* @addtogroup XBT_cunit
- * @brief Unit test mechanism (to test a set of functions)
+ * @brief Unit testing implementation (see @ref inside_tests_add_units)
*
* This module is mainly intended to allow the tests of SimGrid
* itself and may lack the level of genericity that you would expect
* feature of SimGrid (and this code is sufficient to cover our
* needs, actually, so why should we bother switching?)
*
- * Note that if you want to test a full binary (such as an example),
- * you want to use our integration testing mechanism, not our unit
- * testing one. Please refer to Section \ref
- * inside_cmake_addtest_integration
+ * Unit testing is not intended to write integration tests.
+ * Please refer to \ref inside_tests_add_integration for that instead.
*
- * Some more information on our unit testing is available in Section @ref inside_cmake_addtest_unit.
- *
- * All code intended to be executed as a unit test will be extracted
- * by a script (tools/sg_unit_extract.pl), and must thus be protected
- * between preprocessor definitions, as follows. Note that
- * SIMGRID_TEST string must appear on the endif line too for the
- * script to work, and that this script does not allow to have more
- * than one suite per file. For now, but patches are naturally
- * welcome.
- *
-@verbatim
-#ifdef SIMGRID_TEST
-
-<your code>
-
-#endif // SIMGRID_TEST
-@endverbatim
*
*
* @{
/** @brief Provide informations about the suite declared in this file
* @hideinitializer
*
- * Actually, this macro is not used by C, but by the script
- * extracting the test units, but that should be transparent for you.
+ * Actually, this macro is only used by the script extracting the test
+ * units, but that should be transparent for you.
*
* @param suite_name the short name of this suite, to be used in the --tests argument of testall afterward. Avoid spaces and any other strange chars
* @param suite_title instructive title that testall should display when your suite is run
__VA_ARGS__)
#define _xbt_test_assert_CHECK(cond, ...) \
do { if (!(cond)) xbt_test_fail(__VA_ARGS__); } while (0)
+/** @brief Report some details to help debugging when the test fails (shown only on failure)
+ * @hideinitializer */
#define xbt_test_log(...) _xbt_test_log(__FILE__, __LINE__, __VA_ARGS__)
/** @brief Declare that the lastly started test failed because of the provided exception */
src/xbt/probes.h
src/xbt/win32_ucontext.c
tools/tesh/generate_tesh
+ tools/lualib.patch
examples/smpi/mc/only_send_deterministic.tesh
examples/smpi/mc/non_deterministic.tesh
)
doc/doxygen/header.html
doc/doxygen/help.doc
doc/doxygen/index.doc
- doc/doxygen/inside_ci.doc
+ doc/doxygen/inside.doc
+ doc/doxygen/inside_tests.doc
doc/doxygen/inside_cmake.doc
doc/doxygen/inside_doxygen.doc
doc/doxygen/inside_extending.doc
doc/doxygen/inside_release.doc
doc/doxygen/install.doc
- doc/doxygen/internals.doc
- doc/doxygen/introduction.doc
+ doc/doxygen/tutorial.doc
doc/doxygen/module-msg.doc
doc/doxygen/module-sd.doc
doc/doxygen/module-simix.doc
${CMAKE_HOME_DIRECTORY}/doc/webcruft/simgrid_logo_2011_small.png
${CMAKE_HOME_DIRECTORY}/doc/webcruft/simgrid_logo_win.bmp
${CMAKE_HOME_DIRECTORY}/doc/webcruft/simgrid_logo_win_2011.bmp
- ${CMAKE_HOME_DIRECTORY}/doc/webcruft/win_install_01.png
- ${CMAKE_HOME_DIRECTORY}/doc/webcruft/win_install_02.png
- ${CMAKE_HOME_DIRECTORY}/doc/webcruft/win_install_03.png
- ${CMAKE_HOME_DIRECTORY}/doc/webcruft/win_install_04.png
- ${CMAKE_HOME_DIRECTORY}/doc/webcruft/win_install_05.png
- ${CMAKE_HOME_DIRECTORY}/doc/webcruft/win_install_06.png
${CMAKE_HOME_DIRECTORY}/doc/webcruft/smpi_simgrid_alltoall_pair_16.png
${CMAKE_HOME_DIRECTORY}/doc/webcruft/smpi_simgrid_alltoall_ring_16.png
)
+This patch is to be applied to the Lua 5.3 source file to get a shared
+library. This is because the authors of Lua don't bother distributing
+a working build system for their software, so we have to make one...
+
+As unfortunate as it may be, there is nothing else we can do.
+
+ -- Da SimGrid team.
+
diff --git a/Makefile b/Makefile
index 5ee5601..93830a3 100644
--- a/Makefile
#! /usr/bin/env perl
-# Copyright (c) 2005-2012, 2014. The SimGrid Team.
-# All rights reserved.
+# Copyright (c) 2005-2012, 2014. The SimGrid Team. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the terms of the license (GNU LGPL) which comes with this package.
+
+
use strict;
use strict;
sub usage($) {
my $ret;
- print "USAGE: $progname [--root=part/to/cut] [--path=where/to/search NOT WORKING] [--outdir=where/to/generate/files] infile [infile+]\n";
+ print "USAGE: $progname [--root=part/to/cut] [--outdir=where/to/generate/files] infile [infile+]\n\n";
+ print "This program is in charge of extracting the unit tests out of the SimGrid source code.\n";
+ print "See http://simgrid.gforge.inria.fr/doc/latest/inside_tests.html for more details.\n";
exit $ret;
}
-my $path=undef;
my $outdir=undef;
my $root;
my $help;
GetOptions(
'help|h' => sub {usage(0)},
'root=s' =>\$root,
- 'path=s' =>\$path,
'outdir=s' =>\$outdir) or usage(1);
usage(1) if (scalar @ARGV == 0);
