# 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`):

- `RULE_LAUNCH_COMPILE`

- `RULE_LAUNCH_CUSTOM`

- `RULE_LAUNCH_LINK`

Load this module in a CMake project with:

    include(CTestUseLaunchers)

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)