doc/doxygen/inside_cmake.doc

   1 /*!
   2 @page inside_cmake Modifying the cmake files
   3
   4 \tableofcontents
   5
   6 \section inside_cmake_addsrc How to add source files?
   7
   8 If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/DefinePackages.cmake.
   9 Chose the section you are interested in and modify it.
  10
  11 \verbatim
  12 set(SMPI_SRC
  13   src/smpi/smpi_base.c
  14   src/smpi/smpi_bench.c
  15   src/smpi/smpi_c99.c
  16   src/smpi/smpi_coll.c
  17   src/smpi/smpi_comm.c
  18   src/smpi/smpi_global.c
  19   src/smpi/smpi_group.c
  20   src/smpi/smpi_mpi.c
  21   src/smpi/smpi_mpi_dt.c
  22   src/smpi/smpi_pmpi.c
  23   src/smpi/smpi_replay.c
  24   )
  25 \endverbatim
  26
  27 If your source is always added to the library, you are set. But if
  28 it's optional, you must ensure that it gets added to the source
  29 distribution when not compiled in, or it may well be missing if the
  30 archive is built without the option activating your source. This is
  31 done by adding the files to the EXTRA_DIST list, as in the following
  32 example:
  33
  34 \verbatim
  35 ### If f2c is installed compiled source other-whise source is only copy in the dist
  36 if(SMPI_F2C)
  37   set(SMPI_SRC
  38     ${SMPI_SRC}
  39     src/smpi/smpi_f77.c
  40     )
  41 else()
  42   set(EXTRA_DIST
  43     ${EXTRA_DIST}
  44     src/smpi/smpi_f77.c
  45   )
  46 endif()
  47 \endverbatim
  48
  49 Don't forget to run the "make distcheck" target after any modification
  50 to the cmake files: it checks whether all necessary files are present
  51 in the distribution.
  52
  53 \section cmake_dev_guide_ex How to add examples?
  54
  55 First of all, are you sure that you want to create an example, or is
  56 it merely a new test case? The examples located in examples/ must be
  57 interesting to the users. It is expected that the users will take one
  58 of these examples and start editing it to make it fit their needs. If
  59 what you are about to write is merly a test, exercising a specific
  60 part of the tool suite but not really interesting to the users, then
  61 you want to add it to the teshsuite/ directory.
  62
  63 Actually, the examples are also used as regresion tests by adding tesh
  64 files and registering them to the testing infrastructure (for that,
  65 don't forget to add a tesh file and follow the instructions of
  66 section \ref inside_cmake_addtest). The main difference is that
  67 examples must be interesting to the users in addition.
  68
  69 In both cases, you have to create a CMakeList.txt in the chosen source
  70 directory. It must specify where to create the executable, the source
  71 list, dependencies and the name of the binary.
  72
  73 \verbatim
  74 cmake_minimum_required(VERSION 2.6)
  75
  76 set(EXECUTABLE_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}")
  77
  78 add_executable(Hello Hello.c)
  79
  80 ### Add definitions for compile
  81 target_link_libraries(Hello simgrid)
  82
  83 ### You have to put all new files in the apropriated section
  84 ### If they are not there, they can't be on the dist package.
  85 set(tesh_files
  86   ${tesh_files}
  87   PARENT_SCOPE
  88   )
  89 set(xml_files
  90   ${xml_files}
  91   PARENT_SCOPE
  92   )
  93 set(examples_src
  94   ${examples_src}
  95   ${CMAKE_CURRENT_SOURCE_DIR}/Hello.c
  96   PARENT_SCOPE
  97   )
  98 set(bin_files
  99   ${bin_files}
 100   PARENT_SCOPE
 101   )
 102 set(txt_files
 103   ${txt_files}
 104   PARENT_SCOPE
 105   )
 106 \endverbatim
 107
 108 Then, you have to follow these steps:
 109 \li Add the following line to <project/directory>/buildtools/Cmake/MakeExeLib.cmake:
 110 \verbatim
 111 add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
 112 \endverbatim
 113
 114 \li Add your CMakeLists.txt to CMAKE_SOURCE_FILES in <project/directory>/buildtools/Cmake/DefinePackages.cmake:
 115 \verbatim
 116 set(CMAKE_SOURCE_FILES
 117   CMakeLists.txt
 118   ....
 119   <path_to_your_CMakeList.txt>
 120   )
 121 \endverbatim
 122
 123 \li if you add tesh files (and you should), please refer to the
 124 following section to register them to the testing infrastructure.
 125
 126 Once you're done, you should check with "make distcheck" that you did
 127 not forget to add any file to the distributed archives.
 128
 129 \section inside_cmake_addtest How to add tests?
 130
 131 \subsection inside_cmake_addtest_unit Unit testing in SimGrid
 132
 133 If you want to test a specific function or set of functions, you need
 134 a unit test. Edit
 135 <project/directory>/buildtools/Cmake/UnitTesting.cmake to add your
 136 source file to the TEST_CFILES list, and add the corresponding unit
 137 file to the TEST_UNITS list. For example, if your file is toto.c,
 138 your unit file will be toto_unit.c. The full path to your file must be
 139 provided, but the unit file will always be in src/ directly.
 140
 141 Then, you want to actually add your tests in the source file. All the
 142 tests must be protected by "#ifdef SIMGRID_TEST" so that they don't
 143 get included in the regular build. Then, you want to add a test suite
 144 that will contain a bunch of tests (in Junit, that would be a test
 145 unit) with the macro #XBT_TEST_SUITE, and populate it with a bunch of
 146 actual tests with the macro #XBT_TEST_UNIT (sorry for the mischosen
 147 names if you are used to junit). Just look at the dynar example (or
 148 any other) to see how it works in practice. Do not hesitate to stress
 149 test your code this way, but make sure that it runs reasonably fast,
 150 or nobody will run "ctest" before commiting code.
 151
 152 If you are interested in the mechanic turning this into an actual
 153 test, check the <project/directory>/tools/sg_unit_extractor.pl script.
 154
 155 To actually run your tests once you're done, run "make testall", that
 156 builds the binary containing all our unit tests and run it. This
 157 binary allows you to chose which suite you want to test:
 158
 159 \verbatim
 160 $ testall --help # revise how it goes if you forgot
 161 $ testall --dump-only # learn about all existing test suites
 162 $ testall --tests=-all # run no test at all
 163 $ testall --tests=-all,+foo # run only the foo test suite.
 164 $ testall --tests=-all,+foo:bar # run only the bar test from the foo suite.
 165 $ testall --tests=-foo:bar # run all tests but the bar test from the foo suite.
 166 \endverbatim
 167
 168 \subsection inside_cmake_addtest_integration Integration testing in SimGrid
 169
 170 If you want to test a full binary (such as an example), then you
 171 probably want to use the tesh binary that ensures that the output
 172 produced by a command perfectly matches the expected output. In
 173 particular, this is very precious to ensure that no change modifies
 174 the timings computed by the models without notice.
 175
 176 The first step is to write a tesh file for your test, containing the
 177 command to run, the provided input (if any, but almost no SimGrid test
 178 provide such an input) and the expected output. Check the tesh man
 179 page for more details.
 180
 181 Tesh is sometimes annoying as you have to ensure that the expected
 182 output will always be exactly the same. In particular, your should not
 183 output machine dependent informations, nor memory adresses as they
 184 would change on each run. Several steps can be used here, such as the
 185 obfucation of the memory adresses unless the verbose logs are
 186 displayed (using the #XBT_LOG_ISENABLED() macro), or the modification
 187 of the log formats to hide the timings when they depend on the host
 188 machine.
 189
 190 Then you have to request cmake to run your test when "ctest" is
 191 launched. For that, you have to modify source
 192 <project/directory>/buildtools/Cmake/AddTests.cmake. Make sure to pick
 193 a wise name for your test. It is often useful to check a category of
 194 tests together. The only way to do so in ctest is to use the -R
 195 argument that specifies a regular expression that the test names must
 196 match. For example, you can run all MSG test with "ctest -R msg" That
 197 explains the importance of the test names.
 198
 199 Once the name is chosen, create a new test by adding a line similar to
 200 the following (assuming that you use tesh as expected).
 201
 202 \verbatim
 203 #  ADD_TEST(test-name ${CMAKE_BINARY_DIR}/bin/tesh <options> <tesh-file>)
 204 #  option --setenv bindir set the directory containing the binary
 205 #         --setenv srcdir set the directory containing the source file
 206 #         --cd set the working directory
 207 ADD_TEST(my-test-name ${CMAKE_BINARY_DIR}/bin/tesh
 208          --setenv bindir=${CMAKE_BINARY_DIR}/examples/my-test/
 209          --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/my-test/
 210          --cd ${CMAKE_HOME_DIRECTORY}/examples/my-test/
 211          ${CMAKE_HOME_DIRECTORY}/examples/msg/io/io.tesh
 212 )
 213 \endverbatim
 214
 215 If you prefer to not use tesh for some reasons, prefer the following
 216 form:
 217
 218 \verbatim
 219 # ADD_TEST(NAME <name>]
 220 #          [WORKING_DIRECTORY dir]
 221 #          COMMAND <command> [arg1 [arg2 ...]])
 222 ADD_TEST(NAME my-test-name
 223          WORKING_DIRECTORY  ${CMAKE_BINARY_DIR}/examples/my-test/
 224          COMMAND Hello
 225 )
 226 \endverbatim
 227
 228 As usual, you must run "make distcheck" after modifying the cmake files,
 229 to ensure that you did not forget any files in the distributed archive.
 230
 231 \subsection inside_cmake_addtest_perf Performance testing in SimGrid
 232
 233 We are currently in the process of adding an infrastructure for
 234 performance regression testing, but this is not related to cmake
 235 anyhow. They are thus documented elsewhere, in Section \ref
 236 inside_autotests_perf
 237
 238 */