doc/doxygen/inside_cmake.doc

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