CODEWITHSUNDEEP
unit-testingcmakectest
RAM
RAM

Reputation: 2759

CMake naming convention for option name to generate project with unit tests?

Some CMake projects add conditional support for generating projects with unit test support. The pattern followed in the project's root CMakeLists.txt file goes something like:

cmake_minimum_required(VERSION 3.0)

(...)
# add subdirectories, libraries, executables, etc
(...)

option(ENABLE_TESTS "Generate project with unit test support" ON)
if(ENABLE_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

Although this pattern is rather common, I've also noticed that the names picked for the unit tests option is somewhat arbitrary. Although the option BUILD_TESTING was introduced in cmake v3.15, that name was far from standard prior to that release. So far I've noticed projects using the following option names:

With this in mind, does anyone know if there's a standard naming convention to control whether unit tests are added or not to a CMake project?

Upvotes: 3

Views: 923

Answers (1)

KamilCuk
KamilCuk

Reputation: 140960

if there's a standard naming convention to control whether unit tests are added or not to a CMake project?

I usually see the pattern like:

if (YOUR_LIBRARY_BUILD_TESTING AND BUILD_TESTING)
    enable_testing()
    add_subdirectory(tests)
endif()

That way:

  • You enable tests of your library with -DYOUR_LIBRARY_BUILD_TESTING=1 -DBUILD_TESTING=1.
  • Someone else can enable his library testing with -DHIS_LIBRARY_BUILD_TESTING=1 -DBUILD_TESTING=1
  • When someone else's library includes your library, he can choose if your libraries tests are going to be build or not and usually he wants to only run hes unit tests, not yours.
    • The alternative is to push/pop BUILD_TESTING around add_subdirectory like set(sav ${BUILD_TESTING}) set(BUILD_TESTING 0) add_subdirectory(your_library) set(BUILD_TESTING ${sav}), which looks ugly. And in case you want to test the dependent library (ex. with specific different toolchain the upstream doesn't test with) you have to edit cmake files.
  • Package builders, maintainers and distributors of your library will just set -DBUILD_TESTING=0 to overall disable all possible tests.

Modern cmake, I believe currently the cmake tutorial, recommends:

if((CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME OR MYPROJECT_BUILD_TESTING) AND BUILD_TESTING)

which only just let's you omit setting MYPROJECT_BUILD_TESTING=1 when testing your own project.

Some short research on kitware projects, I see VTK_BUILD_TESTING, PARAVIEW_BUILD_TESTING, VTKm_ENABLE_TESTING, SMTK_ENABLE_TESTING, and even ${PROJECT_NAME}_BUILD_TESTING. Some seem to forcible set BUILD_TESTING to ON when project specific *_BUILD_TESTING is enabled.

So far I've noticed projects using the following option names

Everyone comes and uses hes own convention, I believe this is the reason cmake was actually adopted that well - it doesn't "force" any specific thing. I believe most developers when writing cmake scripts are not aware of BUILD_TESTING variable yet, so they start coming up with their own convention - or maybe BUILD_TESTING is the wrong name, as it only means that tests are going to be build, not run. Anyway, as BUILD_TESTING is with cmake from a loooong time, I recommend naming project specific flag as a *_BUILD_TESTING.

Upvotes: 1

Related Questions