Help: Add target names description to cmake-buildsystem(7)

Co-authored-by: Taylor Sasser <taylor.sasser@kitware.com>

Help/command/add_test.rst

@@ -75,7 +75,8 @@ directory the test is created in.
       dependencies are merged into a single ``test_prep/<name>`` 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.

Help/generator/FASTBuild.rst

@@ -26,8 +26,8 @@ This writes a FASTBuild configuration file named ``fbuild.bff`` into
    * ``<path-to-build>/VisualStudio`` - Visual Studio solution and projects
    * ``<path-to-build>/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/<test-name>`` target.
+    merged into one ``test_prep/<test-name>`` target. See the
+    :manual:`cmake-buildsystem(7)` manual for more details on
+    :ref:`Target Names`.
 
     Individual ``test_prep/<test-name>`` 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/<test-name>`` target. Also builds

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/<test-name>`` target.
+    merged into one ``test_prep/<test-name>`` target. See the
+    :manual:`cmake-buildsystem(7)` manual for more details on
+    :ref:`Target Names`.
 
 ``test_prep/all``
 

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/<test-name>`` target.
+    ``test_prep/<test-name>`` target.  See the :manual:`cmake-buildsystem(7)`
+    manual for more details on :ref:`Target Names`.
 
   ``test_prep/all``
     Depends on every generated ``test_prep/<test-name>`` target.

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/<name>`` 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

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/<name>`` 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