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 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). * :prop_gbl:`RULE_LAUNCH_COMPILE`
However, it is split out into its own module file so projects can use * :prop_gbl:`RULE_LAUNCH_CUSTOM`
the CTEST_USE_LAUNCHERS functionality independently. * :prop_gbl:`RULE_LAUNCH_LINK`
To use launchers, set CTEST_USE_LAUNCHERS to ON in a :option:`ctest -S` The ``CTestUseLaunchers`` module is automatically included by the
dashboard script, and then also set it in the cache of the configured :module:`CTest` module when ``include(CTest)`` is called. However, it is
project. Both cmake and ctest need to know the value of it for the provided as a separate module so that projects can use the
launchers to work properly. CMake needs to know in order to generate ``CTEST_USE_LAUNCHERS`` functionality independently.
proper build rules, and ctest, in order to produce the proper error
and warning analysis.
For convenience, you may set the ENV variable To use launchers, set the ``CTEST_USE_LAUNCHERS`` variable to a true-like value
CTEST_USE_LAUNCHERS_DEFAULT in your ctest -S script, too. Then, as in a :option:`ctest -S` dashboard script, and then also set the
long as your CMakeLists uses include(CTest) or ``CTEST_USE_LAUNCHERS`` cache variable in the configured project. Both
include(CTestUseLaunchers), it will use the value of the ENV variable ``cmake`` and ``ctest`` must be aware of its value for the launchers to function
to initialize a CTEST_USE_LAUNCHERS cache variable. This cache correctly:
variable initialization only occurs if CTEST_USE_LAUNCHERS is not
already defined. * ``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 .. versionadded:: 3.8
If CTEST_USE_LAUNCHERS is on in a :option:`ctest -S` script If ``CTEST_USE_LAUNCHERS`` is set to a true-like value in a
the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE :option:`ctest -S` script, the :command:`ctest_configure` command will add
to the cmake command used to configure the project. ``-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}) if(NOT DEFINED CTEST_USE_LAUNCHERS AND DEFINED ENV{CTEST_USE_LAUNCHERS_DEFAULT})