@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:
+The examples/ directory is organized as follows:
+ - examples/s4u/ for examples using the emerging S4U 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.
- - examples/deprecated/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)
- - examples/s4u/ for examples using the emerging S4U API
- - examples/deprecated/simdag/ for examples using the SimDag API
- - examples/smpi/ or examples using the SMPI API
-
-In each of these directories, there is a CMakeLists.txt file that has to be edited to include the new examples. For
-instance, examples/deprecated/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/deprecated/msg/${x} --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/platforms --cd ${CMAKE_HOME_DIRECTORY}/examples/deprecated/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.
*/
