doc/doxygen/inside_cmake.doc

   1 /*!
   2 @page inside_cmake Adding source files or examples
   3
   4 \tableofcontents
   5
   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>.
  10
  11 \section inside_cmake_addsrc How to add source files?
  12
  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:
  16
  17 \verbatim
  18 set(S4U_SRC
  19   src/s4u/s4u_actor.cpp
  20   src/s4u/s4u_as.cpp
  21   src/s4u/s4u_activity.cpp
  22   src/s4u/s4u_comm.cpp
  23   src/s4u/s4u_engine.cpp
  24   src/s4u/s4u_file.cpp
  25   src/s4u/s4u_host.cpp
  26   src/s4u/s4u_mailbox.cpp
  27   src/s4u/s4u_storage.cpp
  28 )
  29 \endverbatim
  30
  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:
  35
  36 \verbatim
  37 if (HAVE_BOOST_CONTEXTS)
  38   set(SIMIX_SRC   ${SIMIX_SRC}  src/simix/ContextBoost.hpp
  39                                 src/simix/ContextBoost.cpp)
  40 else()
  41   set(EXTRA_DIST  ${EXTRA_DIST} src/simix/ContextBoost.hpp
  42                                 src/simix/ContextBoost.cpp)
  43 endif()
  44 \endverbatim
  45
  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.
  50
  51 \section inside_cmake_examples How to add an example?
  52
  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.
  56
  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
  60 upon them by error.
  61
  62 To add a new example, the first thing is to find the right place to add it. The examples/ directory is organized as
  63 follows:
  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
  73
  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.
  78
  79 \verbatim
  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)
  92 endforeach()
  93 \endverbatim
  94
  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
  97
  98 \verbatim
  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)
 104 endforeach()
 105 \endverbatim
 106
 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.
 109
 110 \verbatim
 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
 113          task-priority)
 114   set(xml_files    ${xml_files}     ${CMAKE_CURRENT_SOURCE_DIR}/${file}/${file}_d.xml)
 115 endforeach()
 116 \endverbatim
 117
 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.
 120
 121 \verbatim
 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)
 127 endforeach()
 128 \endverbatim
 129
 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.
 132
 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! Do a second commit in that case.
 137 */