@tableofcontents
-SimGrid uses CMake which is a family of tools designed to build, test, and package software. CMake is used to control the software
-compilation process using simple platform- and compiler-independent configuration files. CMake generates native
-makefiles and workspaces that can be used in the compiler environment of your choice. For more information see
-the <a href="http://www.cmake.org/">official CMake web site</a>.
+SimGrid uses CMake which is a family of tools designed to build, test, and package software.
@section inside_cmake_addsrc How to add source files?
If you want to rename, add, or delete source file(s) in the SimGrid distribution, you have to edit the
-$SIMGRID_INSTALL_PATH/tools/cmake/DefinePackages.cmake configuration file. Files are organized in sections, then find
-the section you are interested in and modify it. For instance, a new S4U source file will have to be listed in:
+tools/cmake/DefinePackages.cmake configuration file. Files are organized in sections, then find
+the section you are interested in and modify it.
-@verbatim
-set(S4U_SRC
- src/s4u/s4u_actor.cpp
- src/s4u/s4u_as.cpp
- src/s4u/s4u_activity.cpp
- src/s4u/s4u_comm.cpp
- src/s4u/s4u_engine.cpp
- src/s4u/s4u_file.cpp
- src/s4u/s4u_host.cpp
- src/s4u/s4u_mailbox.cpp
- src/s4u/s4u_storage.cpp
-)
-@endverbatim
-
-If sources file always have to be included into the library, you are all set. However, ther inclusion may depend on
-specific compiling options. For instance, if Boost contexts are not available, you don't want to compile the
-src/simix/ContextBoost.* files but still add them to the source distribution. This is done by adding those files to the
- EXTRA_DIST list, as follows:
-
-@verbatim
-if (HAVE_BOOST_CONTEXTS)
- set(SIMIX_SRC ${SIMIX_SRC} src/simix/ContextBoost.hpp
- src/simix/ContextBoost.cpp)
-else()
- set(EXTRA_DIST ${EXTRA_DIST} src/simix/ContextBoost.hpp
- src/simix/ContextBoost.cpp)
-endif()
-@endverbatim
-
-Once you're done, you must run "make distcheck" to ensure that you did not forget to add any file to the distributed
-archives. This ensures that everything was commited correctly, so you have to first commit before running
-"make distcheck". If you forgot something, you want to "git commit --amend". But never amend a commit that you already
-pushed to public repositories! Do a second commit in that case.
+Once you're done, test your changes with ``make distcheck``.
@section inside_cmake_examples How to add an example?
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, the first thing is to find the right place to add it. The examples/ directory is organized as
-follows:
- - examples/java/ for examples using the Java bindings to the MSG API. This directory contains packages (app, async,
- cloud, ...) which in turn contain individual examples. If your new example fits in an existing package, add it here,
- or create a new package otherwise.
- - examples/msg/ for examples using the MSG API. Here the naming convention is package-example (e.g., app-masterworker).
- Again, please try to fit to an existing package before creating a new one.
- - examples/platforms/ only contains platforms descriptions in the XML format (see @ref platform for details)
+The examples/ directory is organized as follows:
- examples/s4u/ for examples using the emerging S4U API
- - examples/simdag/ for examples using the SimDag API
- examples/smpi/ or examples using the SMPI API
+ - examples/platforms/ only contains platforms descriptions in the XML format (see @ref platform for details)
+ - examples/deprecated/msg/ for examples using the MSG API. Here the naming convention is package-example (e.g., app-masterworker).
+ - examples/deprecated/simdag/ for examples using the SimDag API
+ - examples/deprecated/java/ for examples using the Java bindings to the MSG API. This directory contains packages (app, async,
+ cloud, ...) which in turn contain individual examples. If your new example fits in an existing package, add it here,
+ or create a new package otherwise.
-In each of these directories, there is a CMakeLists.txt file that has to be edited to include the new examples. For
-instance, examples/msg/CMakeLists.txt starts with a loop over all the (currently) existing tests in which we
- - compile and link the source file (which has to be named as the directory
- - add the source and tesh files to the distribution.
-
-@verbatim
-foreach(x app-masterworker app-pingpong app-pmm app-token-ring async-wait async-waitall
- async-waitany cloud-capping cloud-masterworker cloud-migration cloud-multicore cloud-simple
- cloud-two-tasks dht-chord dht-pastry energy-consumption energy-onoff energy-pstate energy-ptask energy-vm
- platform-failures io-file io-remote io-storage task-priority process-create process-kill process-migration
- process-suspend platform-properties maestro-set process-startkilltime synchro-semaphore trace-categories
- trace-link-srcdst-user-variables trace-link-user-variables trace-masterworker trace-platform
- trace-process-migration trace-user-variables)
- add_executable (${x} ${x}/${x}.c)
- target_link_libraries(${x} simgrid)
- set_target_properties(${x} PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${x})
- set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/${x}/${x}.c)
- set(tesh_files ${tesh_files} ${CMAKE_CURRENT_SOURCE_DIR}/${x}/${x}.tesh)
-endforeach()
-@endverbatim
-
-Some more complex examples may require more than one source file. If it is the case for your example, you will find
-inspiration in the following example
-
-@verbatim
-add_executable (bittorrent app-bittorrent/bittorrent.c app-bittorrent/messages.c app-bittorrent/peer.c app-bittorrent/tracker.c app-bittorrent/connection.c)
-target_link_libraries(bittorrent simgrid)
-set_target_properties(bittorrent PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/app-bittorrent)
-foreach (file bittorrent connection messages peer tracker)
- set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/app-bittorrent/${file}.c ${CMAKE_CURRENT_SOURCE_DIR}/app-bittorrent/${file}.h)
-endforeach()
-@endverbatim
-
-If your example require a deployment file (see @ref deployment for details), name it as the source file adding "_d.xml".
-Then add the name of your example to this foreach loop.
-
-@verbatim
-foreach (file app-bittorrent app-chainsend app-masterworker app-pingpong async-wait
- async-waitall async-waitany dht-chord dht-kademlia dht-pastry io-remote platform-properties maestro-set
- task-priority)
- set(xml_files ${xml_files} ${CMAKE_CURRENT_SOURCE_DIR}/${file}/${file}_d.xml)
-endforeach()
-@endverbatim
-
-If your example includes extra source, text, XML, or tesh files, add them to the existing lists. Finally, register your
-example to the testing infrastructure. See @ref inside_tests_add_integration for more details.
-
-@verbatim
-foreach(x app-bittorrent app-chainsend app-masterworker app-pingpong app-token-ring
- async-wait async-waitall async-waitany cloud-capping cloud-masterworker cloud-migration cloud-simple
- cloud-two-tasks dht-chord dht-kademlia platform-failures io-file io-remote io-storage task-priority
- process-kill process-migration process-suspend platform-properties synchro-semaphore process-startkilltime)
- ADD_TESH_FACTORIES(msg-${x} "thread;ucontext;raw;boost" --setenv bindir=${CMAKE_BINARY_DIR}/examples/msg/${x} --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/platforms --cd ${CMAKE_HOME_DIRECTORY}/examples/msg/${x} ${x}.tesh)
-endforeach()
-@endverbatim
+In each of these directories, there is a CMakeLists.txt file that has
+to be edited to include the new examples.
-Note that the structure of the CMakeLists.txt file may vary from one directory to another, but there are enough existing
-examples to find one that can be adapted to your own example.
+Once you're done, test your changes with ``make distcheck``.
-Once you're done, you must run "make distcheck" to ensure that you did not forget to add any file to the distributed
-archives. This ensures that everything was commited correctly, so you have to first commit before running
-"make distcheck". If you forgot something, you want to "git commit --amend". But never amend a commit that you already
-pushed to public repositories, or you'll break the checkouts of your fellow co-workers! Do a second commit in that case.
*/
