CTestUseLaunchers

This module sets the RULE_LAUNCH_* global properties when the CTEST_USE_LAUNCHERS variable is set to a true-like value (e.g., ON):

The CTestUseLaunchers module is automatically included by the CTest module when include(CTest) is called. However, it is provided as a separate module so that projects can use the CTEST_USE_LAUNCHERS functionality independently.

To use launchers, set the CTEST_USE_LAUNCHERS variable to a true-like value in a ctest -S dashboard script, and then also set the CTEST_USE_LAUNCHERS cache variable in the configured project. Both cmake and ctest must be aware of its value for the launchers to function correctly:

  • cmake needs it to generate the appropriate build rules

  • ctest requires it for accurate error and warning analysis

For convenience, the environment variable CTEST_USE_LAUNCHERS_DEFAULT may be set in the ctest -S script. Then, as long as the CMakeLists.txt includes the CTest or CTestUseLaunchers module, it will use the value of the environment variable to initialize a CTEST_USE_LAUNCHERS cache variable. This cache variable initialization only occurs if CTEST_USE_LAUNCHERS is not already defined.

Added in version 3.8: If CTEST_USE_LAUNCHERS is set to a true-like value in a ctest -S script, the ctest_configure() command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to the cmake command when configuring the project.

Examples

set(CTEST_USE_LAUNCHERS ON)
include(CTestUseLaunchers)