From 64ca71c5784c4ef244fa0714554ceefe80342265 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 22 Oct 2026 08:24:21 -0400 Subject: [PATCH] CTest: Document target names reserved for the dashboard --- Help/manual/cmake-buildsystem.7.rst | 3 ++ Modules/CTest.cmake | 43 +++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 123e4d5d0c..475251a002 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -63,6 +63,9 @@ project-wide convenience targets. ``ZERO_CHECK`` are always reserved. * Some modules reserve additional names: e.g., ``test`` when :module:`CTest` is enabled, and ``package`` when :module:`CPack` is enabled. + The :module:`CTest` module also reserves the names of its + :ref:`dashboard targets `, such as + ``Experimental`` and ``NightlyTest``. * Generators may also create their own convenience targets, such as ``install/parallel`` with the :ref:`Ninja Generators`. See the :manual:`cmake-generators(7)` manual for the target names documented by diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index 66f6cda39c..7bb287fddb 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -58,6 +58,49 @@ the :variable:`CTEST_USE_LAUNCHERS` variable: set(CTEST_USE_LAUNCHERS 1) in the ``CTestConfig.cmake`` file. + +.. _`CTest Dashboard Targets`: + +Dashboard Targets +^^^^^^^^^^^^^^^^^ + +When :variable:`BUILD_TESTING` is enabled, the module also adds custom +targets to the build system that run a :ref:`Dashboard Client` from the +build tree and submit the results. Each target runs :option:`ctest -S` +on a script generated by the module in ``CMakeFiles/CTestScript.cmake``. +The script is configured with the settings collected by the module. + +The following targets are added for all generators: + +``Experimental`` + Run the ``Start``, ``Configure``, ``Build``, ``Test``, ``Coverage``, + and ``Submit`` steps in ``Experimental`` mode. + +``Nightly`` + Run the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps in ``Nightly`` mode. + +``Continuous`` + Run the same steps as ``Nightly`` in ``Continuous`` mode, but stop + after the ``Update`` step if it reports no changes. + +``NightlyMemoryCheck`` + Run the ``Start``, ``Update``, ``Configure``, ``Build``, ``MemCheck``, + ``Coverage``, and ``Submit`` steps in ``Nightly`` mode. + +The :ref:`Makefile Generators`, :ref:`Ninja Generators`, and +:generator:`FASTBuild` generator also add a ```` target +for each combination of ```` in ``Experimental``, ``Nightly``, +and ``Continuous`` and ```` in ``Start``, ``Update``, +``Configure``, ``Build``, ``Test``, ``Coverage``, ``MemCheck``, and +``Submit``. Each runs only that step, such as: + +.. code-block:: shell + + cmake --build . --target ExperimentalTest + +See the :ref:`Dashboard Client` documentation for details on each +step and mode. #]=======================================================================] option(BUILD_TESTING "Build the testing tree." ON)