CDash “all-at-once” SubProject builds

Large software projects can almost always be logically divided into distinct yet interrelated components.  At Kitware, we refer to such components as subprojects.  CDash has long supported the notion of subprojects, but up until now it has been a bit tricky to use this feature.  Fear not, now it is easier than ever!

Previously, clients submitting to CDash needed to build and test each subproject separately.  New features in CMake 3.10 and CDash 2.6 allow you to build and test your whole project at once while still splitting the results across subprojects.  Here’s how to do it!

Step 1: In your project’s CMakeLists.txt files, use a label to represent each subproject.

It’s likely that your subprojects are already organized into separate subdirectories in your source code repository.  In this case, you can easily set a label on each directory.

set(CMAKE_DIRECTORY_LABELS “mysubproj1”)

This causes any targets or tests declared in this directory or its subdirectories to inherit the label mysubproj1.

If your subprojects are not organized into separate directories you should instead assign a label to each target and test.

add_executable(foo foo.c)
add_test(NAME foo COMMAND foo)

set_property(TARGET foo PROPERTY LABELS mysubproj1)
set_property(TEST foo PROPERTY LABELS mysubproj1)

Step 2: tell CDash which labels represent subprojects.

Labels are a general feature in CMake that can be used for purposes other than subprojects.  For this reason, you need to explicitly tell CDash which labels should be treated as subprojects.  To do this, set the CTEST_LABELS_FOR_SUBPROJECTS variable in your CTestConfig.cmake file.

set(CTEST_LABELS_FOR_SUBPROJECTS mysubproj1 mysubproj2)

Step 3: build and test your project as normal.

The beauty of the all-at-once subproject approach is that you don’t need to change your CTest driver script to reap the benefits of a subproject dashboard.

After you’ve set up your labels and CTEST_LABELS_FOR_SUBPROJECTS you should be able to build and test your project as normal. The only other caveat is that you need to use CTest launchers so CTest & CDash can assign build errors and warnings to the appropriate subproject.

set(CTEST_USE_LAUNCHERS 1)
set(ENV{CTEST_USE_LAUNCHERS_DEFAULT} 1)

ctest_start(Experimental)
ctest_configure()
ctest_build()
ctest_test()
ctest_submit()

Download and run the example

Download and run our example project to see this new feature in action.  Before you start, make sure that you have CMake 3.10 installed locally.

You may want to modify build_and_test.cmake to change the build name, site name, or type of generator to use.  Once you’re satisfied, you can run an example build.

ctest -VV -S build_and_test.cmake

View the results here:

https://open.cdash.org/index.php?project=SubProjectExample