SimGrid  3.16
Versatile Simulation of Distributed Systems
Adding source files or examples

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 official CMake web site.

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:

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
)

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:

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()

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.

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 example is also used as an integration test (see Testing SimGrid), 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, 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 Describing the virtual platform for details)
  • 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

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.
foreach(x actions-comm actions-storage 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()

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

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()

If your example require a deployment file (see Deploy the simulation for details), name it as the source file adding "_d.xml". Then add the name of your example to this foreach loop.

foreach (file actions-comm actions-storage 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()

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 Adding integration tests for more details.

foreach(x actions-comm actions-storage 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()

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, 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.