2 @page inside_cmake Adding source files or examples
6 SimGrid uses CMake which is a family of tools designed to build, test, and package software. CMake is used to control the software
7 compilation process using simple platform- and compiler-independent configuration files. CMake generates native
8 makefiles and workspaces that can be used in the compiler environment of your choice. For more information see
9 the <a href="http://www.cmake.org/">official CMake web site</a>.
11 \section inside_cmake_addsrc How to add source files?
13 If you want to rename, add, or delete source file(s) in the SimGrid distribution, you have to edit the
14 $SIMGRID_INSTALL_PATH/tools/cmake/DefinePackages.cmake configuration file. Files are organized in sections, then find
15 the section you are interested in and modify it. For instance, a new S4U source file will have to be listed in:
21 src/s4u/s4u_activity.cpp
23 src/s4u/s4u_engine.cpp
26 src/s4u/s4u_mailbox.cpp
27 src/s4u/s4u_storage.cpp
31 If sources file always have to be included into the library, you are all set. However, ther inclusion may depend on
32 specific compiling options. For instance, if Boost contexts are not available, you don't want to compile the
33 src/simix/ContextBoost.* files but still add them to the source distribution. This is done by adding those files to the
34 EXTRA_DIST list, as follows:
37 if (HAVE_BOOST_CONTEXTS)
38 set(SIMIX_SRC ${SIMIX_SRC} src/simix/ContextBoost.hpp
39 src/simix/ContextBoost.cpp)
41 set(EXTRA_DIST ${EXTRA_DIST} src/simix/ContextBoost.hpp
42 src/simix/ContextBoost.cpp)
46 Once you're done, you must run "make distcheck" to ensure that you did not forget to add any file to the distributed
47 archives. This ensures that everything was commited correctly, so you have to first commit before running
48 "make distcheck". If you forgot something, you want to "git commit --amend". But never amend a commit that you already
49 pushed to public repositories! Do a second commit in that case.
51 \section inside_cmake_examples How to add an example?
53 The first rule is that the content of examples/ must be interesting to the users. It is expected that the users will
54 take one of these examples and start editing it to make it fit their needs. So, it should be self-contained,
55 informative, and should use only the public APIs.
57 To ensure that all examples actually work as expected, every example is also used as an integration test (see
58 @ref inside_tests), but you should still strive to keep the code under examples/ as informative as possible for the
59 users. In particular, torture test cases should be placed in teshsuite/, not examples/, so that the users don't stumble
62 To add a new example, the first thing is to find the right place to add it. The examples/ directory is organized as
64 - examples/java/ for examples using the Java bindings to the MSG API. This directory contains packages (app, async,
65 cloud, ...) which in turn contain individual examples. If your new example fits in an existing package, add it here,
66 or create a new package otherwise.
67 - examples/msg/ for examples using the MSG API. Here the naming convention is package-example (e.g., app-masterworker).
68 Again, please try to fit to an existing package before creating a new one.
69 - examples/platforms/ only contains platforms descriptions in the XML format (see @ref platform for details)
70 - examples/s4u/ for examples using the emerging S4U API
71 - examples/simdag/ for examples using the SimDag API
72 - examples/smpi/ or examples using the SMPI API
74 In each of these directories, there is a CMakeLists.txt file that has to be edited to include the new examples. For
75 instance, examples/msg/CMakeLists.txt starts with a loop over all the (currently) existing tests in which we
76 - compile and link the source file (which has to be named as the directory
77 - add the source and tesh files to the distribution.
80 foreach(x actions-comm actions-storage app-masterworker app-pingpong app-pmm app-token-ring async-wait async-waitall
81 async-waitany cloud-capping cloud-masterworker cloud-migration cloud-multicore cloud-simple
82 cloud-two-tasks dht-chord dht-pastry energy-consumption energy-onoff energy-pstate energy-ptask energy-vm
83 platform-failures io-file io-remote io-storage task-priority process-create process-kill process-migration
84 process-suspend platform-properties maestro-set process-startkilltime synchro-semaphore trace-categories
85 trace-link-srcdst-user-variables trace-link-user-variables trace-masterworker trace-platform
86 trace-process-migration trace-user-variables)
87 add_executable (${x} ${x}/${x}.c)
88 target_link_libraries(${x} simgrid)
89 set_target_properties(${x} PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${x})
90 set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/${x}/${x}.c)
91 set(tesh_files ${tesh_files} ${CMAKE_CURRENT_SOURCE_DIR}/${x}/${x}.tesh)
95 Some more complex examples may require more than one source file. If it is the case for your example, you will find
96 inspiration in the following example
99 add_executable (bittorrent app-bittorrent/bittorrent.c app-bittorrent/messages.c app-bittorrent/peer.c app-bittorrent/tracker.c app-bittorrent/connection.c)
100 target_link_libraries(bittorrent simgrid)
101 set_target_properties(bittorrent PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/app-bittorrent)
102 foreach (file bittorrent connection messages peer tracker)
103 set(examples_src ${examples_src} ${CMAKE_CURRENT_SOURCE_DIR}/app-bittorrent/${file}.c ${CMAKE_CURRENT_SOURCE_DIR}/app-bittorrent/${file}.h)
107 If your example require a deployment file (see @ref deployment for details), name it as the source file adding "_d.xml".
108 Then add the name of your example to this foreach loop.
111 foreach (file actions-comm actions-storage app-bittorrent app-chainsend app-masterworker app-pingpong async-wait
112 async-waitall async-waitany dht-chord dht-kademlia dht-pastry io-remote platform-properties maestro-set
114 set(xml_files ${xml_files} ${CMAKE_CURRENT_SOURCE_DIR}/${file}/${file}_d.xml)
118 If your example includes extra source, text, XML, or tesh files, add them to the existing lists. Finally, register your
119 example to the testing infrastructure. See \ref inside_tests_add_integration for more details.
122 foreach(x actions-comm actions-storage app-bittorrent app-chainsend app-masterworker app-pingpong app-token-ring
123 async-wait async-waitall async-waitany cloud-capping cloud-masterworker cloud-migration cloud-simple
124 cloud-two-tasks dht-chord dht-kademlia platform-failures io-file io-remote io-storage task-priority
125 process-kill process-migration process-suspend platform-properties synchro-semaphore process-startkilltime)
126 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)
130 Note that the structure of the CMakeLists.txt file may vary from one directory to another, but there are enough existing
131 examples to find one that can be adapted to your own example.
133 Once you're done, you must run "make distcheck" to ensure that you did not forget to add any file to the distributed
134 archives. This ensures that everything was commited correctly, so you have to first commit before running
135 "make distcheck". If you forgot something, you want to "git commit --amend". But never amend a commit that you already
136 pushed to public repositories, or you'll break the checkouts of your fellow co-workers! Do a second commit in that case.