From 2a67f00fc817cc7ad77cbabc67aa1e1eaa17ff49 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Tue, 29 Sep 2026 09:27:48 -0400 Subject: [PATCH] Help: Add target names description to `cmake-buildsystem(7)` Co-authored-by: Taylor Sasser --- Help/command/add_test.rst | 3 +- Help/generator/FASTBuild.rst | 11 ++++--- Help/generator/Ninja.rst | 4 ++- Help/generator/Unix Makefiles.rst | 3 +- Help/manual/cmake-buildsystem.7.rst | 36 ++++++++++++++++++++++ Help/variable/CMAKE_TEST_BUILD_DEPENDS.rst | 2 ++ 6 files changed, 52 insertions(+), 7 deletions(-) diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index e4b6040814..86cda7c5e1 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -75,7 +75,8 @@ directory the test is created in. dependencies are merged into a single ``test_prep/`` target. Tests with names that are not valid target names are excluded from this - behavior. + behavior. See the :manual:`cmake-buildsystem(7)` manual for more details + on :ref:`Target Names`. The ``BUILD_DEPENDS`` keyword can be used to add explicit build dependencies. diff --git a/Help/generator/FASTBuild.rst b/Help/generator/FASTBuild.rst index 43c87b7253..e737bee997 100644 --- a/Help/generator/FASTBuild.rst +++ b/Help/generator/FASTBuild.rst @@ -26,8 +26,8 @@ This writes a FASTBuild configuration file named ``fbuild.bff`` into * ``/VisualStudio`` - Visual Studio solution and projects * ``/XCode`` - Xcode workspace and projects - These IDE files can be generated by building ``xcode`` or ``solution`` targets - and will build using FASTBuild as the backend. + These IDE files can be generated by building ``xcode`` or ``solution`` + targets and will build using FASTBuild as the backend. Built-in Targets ---------------- @@ -45,10 +45,13 @@ Built-in Targets Tests whose names are not valid target names are excluded. If multiple tests in different directories share the same name, their dependencies are - merged into one ``test_prep/`` target. + merged into one ``test_prep/`` target. See the + :manual:`cmake-buildsystem(7)` manual for more details on + :ref:`Target Names`. Individual ``test_prep/`` targets are not created for tests - discovered at test time, because their names are not known during generation. + discovered at test time, because their names are not known during + generation. ``test_prep/all`` Depends on every generated ``test_prep/`` target. Also builds diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index d90e8c527c..fdf598a011 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -42,7 +42,9 @@ Builtin Targets Tests with names that are not valid target names are excluded. If multiple tests in different directories share the same name, their dependencies are - merged into one ``test_prep/`` target. + merged into one ``test_prep/`` target. See the + :manual:`cmake-buildsystem(7)` manual for more details on + :ref:`Target Names`. ``test_prep/all`` diff --git a/Help/generator/Unix Makefiles.rst b/Help/generator/Unix Makefiles.rst index 03b577a1cb..459614839a 100644 --- a/Help/generator/Unix Makefiles.rst +++ b/Help/generator/Unix Makefiles.rst @@ -45,7 +45,8 @@ be created, containing the following targets: Tests whose names are not valid target names, and tests whose names contain a ``:`` character, are excluded. If multiple tests in different directories share the same name, their dependencies are merged into one - ``test_prep/`` target. + ``test_prep/`` target. See the :manual:`cmake-buildsystem(7)` + manual for more details on :ref:`Target Names`. ``test_prep/all`` Depends on every generated ``test_prep/`` target. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 85eb969554..32234a6877 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -37,6 +37,42 @@ is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is linked in. +.. _`Target Names`: + +Target Names +------------ + +Targets are addressed by name throughout the buildsystem. A target name +must be non-empty and contain only ASCII letters, digits, ``_``, ``.``, ``+``, +and ``-``. As a special case, ``ALIAS`` and :prop_tgt:`IMPORTED` +targets may also contain ``:``. By convention, a double colon (``::``) is used +as a namespace separator, such as ``Upstream::lib1``, to distinguish +``ALIAS`` and ``IMPORTED`` targets from targets of other types, and to reduce +the likelihood of naming collisions. See the :manual:`cmake-packages(7)` +manual for more details. + +Target names must be globally unique. Non-``GLOBAL`` :prop_tgt:`IMPORTED` +targets are visible only in the directory that defines them and their +subdirectories. + +CMake reserves some names for special targets created by the build tools and +project-wide convenience targets. + +* The names ``all``, ``ALL_BUILD``, ``help``, ``install``, ``INSTALL``, + ``preinstall``, ``clean``, ``edit_cache``, ``rebuild_cache``, and + ``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. +* 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 + each generator. + +Some convenience targets derive their names from other names in the project. +The ``test_prep/`` targets use test names, which have their own +representability rules beyond those above. See also :command:`add_test` and +:variable:`CMAKE_TEST_BUILD_DEPENDS`. + .. _`Executables`: Executables diff --git a/Help/variable/CMAKE_TEST_BUILD_DEPENDS.rst b/Help/variable/CMAKE_TEST_BUILD_DEPENDS.rst index 77ec68d78b..82b2f39e31 100644 --- a/Help/variable/CMAKE_TEST_BUILD_DEPENDS.rst +++ b/Help/variable/CMAKE_TEST_BUILD_DEPENDS.rst @@ -26,6 +26,8 @@ targets referenced by test command generator expressions, and explicit Tests whose names are not valid target names are excluded from this behavior. If multiple tests in different directories share the same name, their dependencies are merged into a single ``test_prep/`` target. +See the :manual:`cmake-buildsystem(7)` manual for more details on +:ref:`Target Names`. With the :ref:`Makefile Generators`, a ``BUILD_DEPENDS`` file is built by building the target whose build produces it. A generated file that is not the