diff --git a/Modules/CTestUseLaunchers.cmake b/Modules/CTestUseLaunchers.cmake index 5578c3df31..dc015f805f 100644 --- a/Modules/CTestUseLaunchers.cmake +++ b/Modules/CTestUseLaunchers.cmake @@ -5,34 +5,48 @@ CTestUseLaunchers ----------------- -Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on. +This module sets the ``RULE_LAUNCH_*`` global properties when the +:variable:`CTEST_USE_LAUNCHERS` variable is set to a true-like value (e.g., +``ON``): -CTestUseLaunchers is automatically included when you include(CTest). -However, it is split out into its own module file so projects can use -the CTEST_USE_LAUNCHERS functionality independently. +* :prop_gbl:`RULE_LAUNCH_COMPILE` +* :prop_gbl:`RULE_LAUNCH_CUSTOM` +* :prop_gbl:`RULE_LAUNCH_LINK` -To use launchers, set CTEST_USE_LAUNCHERS to ON in a :option:`ctest -S` -dashboard script, and then also set it in the cache of the configured -project. Both cmake and ctest need to know the value of it for the -launchers to work properly. CMake needs to know in order to generate -proper build rules, and ctest, in order to produce the proper error -and warning analysis. +The ``CTestUseLaunchers`` module is automatically included by the +:module:`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. -For convenience, you may set the ENV variable -CTEST_USE_LAUNCHERS_DEFAULT in your ctest -S script, too. Then, as -long as your CMakeLists uses include(CTest) or -include(CTestUseLaunchers), it will use the value of the ENV variable -to initialize a CTEST_USE_LAUNCHERS cache variable. This cache -variable initialization only occurs if CTEST_USE_LAUNCHERS is not -already defined. +To use launchers, set the ``CTEST_USE_LAUNCHERS`` variable to a true-like value +in a :option:`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 :envvar:`CTEST_USE_LAUNCHERS_DEFAULT` +may be set in the :option:`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. .. versionadded:: 3.8 - If CTEST_USE_LAUNCHERS is on in a :option:`ctest -S` script - the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE - to the cmake command used to configure the project. + If ``CTEST_USE_LAUNCHERS`` is set to a true-like value in a + :option:`ctest -S` script, the :command:`ctest_configure` command will add + ``-DCTEST_USE_LAUNCHERS:BOOL=TRUE`` to the ``cmake`` command when configuring + the project. -.. TODO Use RST markup +Examples +^^^^^^^^ +.. code-block:: cmake + + set(CTEST_USE_LAUNCHERS ON) + include(CTestUseLaunchers) #]=======================================================================] if(NOT DEFINED CTEST_USE_LAUNCHERS AND DEFINED ENV{CTEST_USE_LAUNCHERS_DEFAULT})