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.
   7
   8 @section inside_cmake_addsrc How to add source files?
   9
  10 If you want to rename, add, or delete source file(s) in the SimGrid distribution, you have to edit the
  11 tools/cmake/DefinePackages.cmake configuration file. Files are organized in sections, then find
  12 the section you are interested in and modify it.
  13
  14 Once you're done, test your changes with ``make distcheck``.
  15
  16 @section inside_cmake_examples How to add an example?
  17
  18 The first rule is that the content of examples/ must be interesting to the users. It is expected that the users will
  19 take one of these examples and start editing it to make it fit their needs. So, it should be self-contained,
  20 informative, and should use only the public APIs.
  21
  22 To ensure that all examples actually work as expected, every example is also used as an integration test (see
  23 @ref inside_tests), but you should still strive to keep the code under examples/ as informative as possible for the
  24 users. In particular, torture test cases should be placed in teshsuite/, not examples/, so that the users don't stumble
  25 upon them by error.
  26
  27 The examples/ directory is organized as  follows:
  28  - examples/s4u/ for examples using the emerging S4U API
  29  - examples/smpi/ or examples using the SMPI API
  30  - examples/platforms/ only contains platforms descriptions in the XML format (see @ref platform for details)
  31  - examples/deprecated/msg/ for examples using the MSG API. Here the naming convention is package-example (e.g., app-masterworker).
  32  - examples/deprecated/simdag/ for examples using the SimDag API
  33  - examples/deprecated/java/ for examples using the Java bindings to the MSG API. This directory contains packages (app, async,
  34    cloud, ...) which in turn contain individual examples. If your new example fits in an existing package, add it here,
  35    or create a new package otherwise.
  36
  37 In each of these directories, there is a CMakeLists.txt file that has
  38 to be edited to include the new examples.
  39
  40 Once you're done, test your changes with ``make distcheck``.
  41
  42 */