2 @page inside_cmake Modifying the cmake files
6 \section inside_cmake_intro Generalities on Cmake
8 \subsection inside_cmake_what What is Cmake?
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>.
17 \subsection inside_cmake_why Why cmake?
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
24 \section inside_cmake_addsrc How to add source files?
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.
36 src/smpi/smpi_global.c
39 src/smpi/smpi_mpi_dt.c
41 src/smpi/smpi_replay.c
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
53 ### If fortran is installed compile source other-whise source is only copied in the dist
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
71 \section cmake_dev_guide_ex How to add examples?
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.
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.
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.
92 cmake_minimum_required(VERSION 2.6)
94 set(EXECUTABLE_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}")
96 add_executable(Hello Hello.c)
98 ### Add definitions for compile
99 target_link_libraries(Hello simgrid)
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.
113 ${CMAKE_CURRENT_SOURCE_DIR}/Hello.c
126 Then, you have to follow these steps:
127 \li Add the following line to <project/directory>/buildtools/Cmake/MakeExe.cmake:
129 add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
132 \li Add your CMakeLists.txt to CMAKE_SOURCE_FILES in <project/directory>/buildtools/Cmake/DefinePackages.cmake:
134 set(CMAKE_SOURCE_FILES
137 <path_to_your_CMakeList.txt>
141 \li if you add tesh files (and you should), please refer to the
142 following section to register them to the testing infrastructure.
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.
147 \section inside_cmake_addtest How to add tests?
149 \subsection inside_cmake_addtest_unit Unit testing in SimGrid
151 If you want to test a specific function or set of functions, you need
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.
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.
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.
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:
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.
186 \subsection inside_cmake_addtest_integration Integration testing in SimGrid
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.
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.
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
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.
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).
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
233 If you prefer to not use tesh for some reasons, prefer the following
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/
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.
249 \subsection inside_cmake_ci Continous Integration
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.