echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CTestUseLaunchers: Update documentation

Browse Source
This commit is contained in:
Peter Kokot 2025-03-05 21:21:21 +01:00
parent 7065c7a586
commit be9011c275
No known key found for this signature in database
GPG Key ID: A94800907AA79B36
1 changed files with 35 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
Modules/CTestUseLaunchers.cmake
View File

@ -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})