Ninja, Makefile, FASTBuild: Enable test_prep by default

Enable test preparation targets by default. Add (better named)
`CMAKE_SKIP_TEST_PREP_TARGETS` variable to control generation of the
same, mirroring `CMAKE_SKIP_INSTALL_PREP_TARGETS`. Remove support for
old `CMAKE_TEST_BUILD_DEPENDS` variable. Update and improve
documentation.

This improves consistency between test and install preparation targets.
It also modifies the descriptions of preparation targets in the
documentation of generators which support them to be consistent.
(Previously, each generator described preparation targets in a manner
unique to each generator.)

Fixes: #28050

Help/command/add_test.rst

@@ -25,6 +25,10 @@ in test properties set by :command:`set_property(TEST)` or
 :command:`set_tests_properties`. Test properties may only be set in the
 directory the test is created in.
 
+.. versionadded:: 4.4
+  Some generators provide ``test_prep/`` build targets that build only the
+  prerequisites of tests.  See :ref:`Test Preparation Targets`.
+
 ``add_test`` options are:
 
 ``COMMAND``
@@ -60,36 +64,6 @@ directory the test is created in.
 
         <launcher> <emulator> <command>
 
-  * .. versionadded:: 4.4
-
-      When the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is enabled,
-      the :ref:`Ninja Generators` and :generator:`FASTBuild` generate a
-      convenience build target named
-      ``test_prep/<name>`` that depends on the test executable target. Building
-      this target ensures the executable is up-to-date before the test runs.
-
-      Additionally, targets referenced by the test command via generator
-      expressions are added as dependencies of the ``test_prep/<name>`` target.
-
-      If multiple tests in different directories share the same name, their
-      dependencies are merged into a single ``test_prep/<name>`` target.
-
-      Tests with names that are not valid target names are excluded from this
-      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.
-
-    .. versionchanged:: 4.5
-
-      :generator:`FASTBuild` and the :ref:`Makefile Generators` gained support
-      for ``test_prep/<name>`` targets.  With the Makefile generators a
-      ``BUILD_DEPENDS`` file is built by building the target whose build
-      produces it; a file that is not the unique output of a single target is
-      reported with a warning, and a test whose name contains a ``:`` character
-      is excluded.
-
   The command may be specified using
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
@@ -105,12 +79,13 @@ directory the test is created in.
 ``BUILD_DEPENDS``
   .. versionadded:: 4.4
 
-  Specify a list of targets or files that must be built before the test can
-  run. Each dependency is added to the ``test_prep/<name>`` build target
-  described above when :variable:`CMAKE_TEST_BUILD_DEPENDS` is enabled with the
-  :ref:`Ninja Generators`, :generator:`FASTBuild`, or :ref:`Makefile
-  Generators`. The test name must be a valid target name in order to list
-  build dependencies with this keyword.
+  Specify targets or files that need to be built before the test runs.
+  They are added as dependencies of the corresponding
+  :ref:`Test Preparation Target <Test Preparation Targets>`.  This is intended
+  for dependencies that CMake cannot infer.
+
+  Each entry naming an existing target or alias is a target dependency.
+  Any other entry names a file, which must exist or be generated by the build.
 
   * .. versionchanged:: 4.5
 

Help/command/discover_tests.rst

@@ -103,11 +103,10 @@ the provided regular expression and replacement strings.
   current source directory if the file exists there, and otherwise with respect
   to the current binary directory.
 
-  When the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is enabled with the
-  :ref:`Ninja Generators`, :generator:`FASTBuild`, or :ref:`Makefile
-  Generators`, these dependencies are built by the ``test_prep/all`` target.
-  If ``COMMAND`` names an executable target created by
-  :command:`add_executable`, that target is also added automatically.
+  When :ref:`Test Preparation Targets` are not disabled, these dependencies are
+  built by the ``test_prep/all`` target.  If ``COMMAND`` names an executable
+  target created by :command:`add_executable`, that target is also added
+  automatically.
 
   Individual ``test_prep/<test-name>`` targets are not created for discovered
   tests because their names are not known at generation time.

Help/generator/FASTBuild.rst

@@ -32,34 +32,37 @@ This writes a FASTBuild configuration file named ``fbuild.bff`` into
 Built-in Targets
 ----------------
 
-.. versionadded:: 4.5
+``install_prep/<component>``
 
-  If the project has install rules, the generated build file provides the
-  following targets, unless :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
-  :variable:`CMAKE_SKIP_INSTALL_RULES` is enabled:
+  .. versionadded:: 4.5
 
-  ``install_prep/<component>``
-    Builds all known build dependencies for the install component named
-    ``<component>`` added by :command:`install`. Components whose names cannot
-    be represented safely are excluded. See :ref:`Install Preparation Targets`
-    and :ref:`Target Names`.
+    Created if the project has install rules, unless the
+    :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
+    :variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled. Builds all known
+    build dependencies for the named install component. Components whose
+    names cannot be represented safely are excluded. See
+    :ref:`Install Preparation Targets` and :ref:`Target Names`.
 
-  ``install_prep/all``
-    Builds all known build dependencies needed for an installation that does
-    not select a component. See :ref:`Install Preparation Targets`.
+``install_prep/all``
 
-.. versionadded:: 4.5
+  .. versionadded:: 4.5
 
-  When the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is enabled, the
-  generated build file provides the following targets:
+    Created if the project has install rules, unless the
+    :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
+    :variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled. Builds all known
+    build dependencies for an installation that does not select a component.
+    See :ref:`Install Preparation Targets`.
 
-  ``test_prep/<test-name>``
-    Builds all known build dependencies for the test named ``<test-name>``
-    added by :command:`add_test`, including the executable target invoked by
-    the test, targets referenced by generator expressions in the test command,
-    and explicit ``BUILD_DEPENDS`` entries.
+``test_prep/<test-name>``
 
-    Tests whose names are not valid target names are excluded. If multiple
+  .. versionchanged:: 4.5
+
+    Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
+    enabled. Builds all known build dependencies for the named test, including
+    the executable target invoked by the test, targets referenced by generator
+    expressions in the test command, and explicit ``BUILD_DEPENDS`` entries.
+
+    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. See the
     :manual:`cmake-buildsystem(7)` manual for more details on
@@ -69,10 +72,14 @@ Built-in Targets
     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
-    dependencies recorded by the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS` directory
-    property.
+``test_prep/all``
+
+  .. versionchanged:: 4.5
+
+    Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
+    enabled. Depends on every generated ``test_prep/<test-name>`` target. Also
+    builds dependencies recorded by the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS`
+    directory property.
 
 Caching
 -------
@@ -115,7 +122,6 @@ The following variables can be used to configure this generator:
 * :variable:`CMAKE_FASTBUILD_IDE_ARGS`
 * :variable:`CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT`
 * :variable:`CMAKE_FASTBUILD_VERBOSE_GENERATOR`
-* :variable:`CMAKE_TEST_BUILD_DEPENDS`
 
 Target Properties
 -----------------

Help/generator/Ninja.rst

@@ -3,8 +3,8 @@ Ninja
 
 Generates a ``build.ninja`` file into the build tree.
 
-Builtin Targets
-^^^^^^^^^^^^^^^
+Built-In Targets
+^^^^^^^^^^^^^^^^
 
 ``all``
 
@@ -56,7 +56,7 @@ Builtin Targets
 
   .. versionadded:: 4.4
 
-    Created only if the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is
+    Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
     enabled. Builds all known build dependencies for the named test, including
     the executable target invoked by the test, targets referenced by generator
     expressions in the test command, and explicit ``BUILD_DEPENDS`` entries.
@@ -67,12 +67,28 @@ Builtin Targets
     :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.
+
+  .. versionchanged:: 4.5
+
+    These targets are created by default. In CMake 4.4, they were created only
+    if the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable was enabled.
+
 ``test_prep/all``
 
   .. versionadded:: 4.4
 
-    Created only if the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is
-    enabled. Depends on every generated ``test_prep/<test-name>`` target.
+    Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
+    enabled. Depends on every generated ``test_prep/<test-name>`` target. Also
+    builds dependencies recorded by the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS`
+    directory property.
+
+  .. versionchanged:: 4.5
+
+    This target is created by default. In CMake 4.4, it was created only if
+    the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable was enabled.
 
 For each subdirectory ``sub/dir`` of the project, additional targets
 are generated:

Help/generator/Unix Makefiles.rst

@@ -30,40 +30,53 @@ be created, containing the following targets:
 ``package``
   Runs the package step in the subdirectory, if any.
 
-.. versionadded:: 4.5
+``install_prep/<component>``
 
-  If the project has install rules, the top-level makefile additionally
-  provides the following targets, unless the
-  :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
-  :variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled:
+  .. versionadded:: 4.5
 
-  ``install_prep/<component>``
-    Builds all known build dependencies for the install component named
-    ``<component>`` added by :command:`install`. Components whose names cannot
-    be represented safely are excluded. See :ref:`Install Preparation Targets`
-    and :ref:`Target Names`.
+    Created if the project has install rules, unless the
+    :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
+    :variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled. Builds all known
+    build dependencies for the named install component. Components whose
+    names cannot be represented safely are excluded. See
+    :ref:`Install Preparation Targets` and :ref:`Target Names`.
 
-  ``install_prep/all``
-    Builds all known build dependencies needed for an installation that does
-    not select a component. See :ref:`Install Preparation Targets`.
+``install_prep/all``
 
-.. versionadded:: 4.5
+  .. versionadded:: 4.5
 
-  When the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is enabled, the
-  top-level makefile additionally provides the following targets:
+    Created if the project has install rules, unless the
+    :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` or
+    :variable:`CMAKE_SKIP_INSTALL_RULES` variable is enabled. Builds all known
+    build dependencies for an installation that does not select a component.
+    See :ref:`Install Preparation Targets`.
 
-  ``test_prep/<test-name>``
-    Builds all known build dependencies for the test named ``<test-name>``
-    added by :command:`add_test`, including the executable target invoked by
-    the test, targets referenced by generator expressions in the test command,
-    and explicit ``BUILD_DEPENDS`` entries.  A ``BUILD_DEPENDS`` file is built
-    by building the target whose build produces it.
+``test_prep/<test-name>``
 
-    Tests whose names are not valid target names, and tests whose names
-    contain a ``:`` character, are excluded.  If multiple tests in different
+  .. versionadded:: 4.5
+
+    Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
+    enabled. Builds all known build dependencies for the named test, including
+    the executable target invoked by the test, targets referenced by generator
+    expressions in the test command, and explicit ``BUILD_DEPENDS`` entries.
+    A ``BUILD_DEPENDS`` file is built by building the target whose build
+    produces it.
+
+    Tests with names that 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.  See the :manual:`cmake-buildsystem(7)`
+    ``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.
+    Individual ``test_prep/<test-name>`` targets are not created for tests
+    discovered at test time, because their names are not known during
+    generation.
+
+``test_prep/all``
+
+  .. versionadded:: 4.5
+
+    Created unless the :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable is
+    enabled. Depends on every generated ``test_prep/<test-name>`` target. Also
+    builds dependencies recorded by the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS`
+    directory property.

Help/manual/cmake-buildsystem.7.rst

@@ -71,8 +71,8 @@ project-wide convenience targets.
 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`.
+  representability rules beyond those above.  The :ref:`Makefile Generators` do
+  not allow ``:``.  See also :ref:`Test Preparation Targets`.
 * The ``install_prep/<component>`` targets use install component names.
   A component name may contain the characters allowed in target names above,
   plus ``:`` and ``/``.  The :ref:`Makefile Generators` do not allow ``:``.
@@ -1786,6 +1786,53 @@ The :ref:`Ninja Generators`, :ref:`Makefile Generators`, and
 :generator:`FASTBuild` generator provide convenience targets that build only
 the prerequisites of a later step, such as running tests or installing.
 
+.. _`Test Preparation Targets`:
+
+Test Preparation Targets
+------------------------
+
+.. versionadded:: 4.4
+
+The generators which support preparation targets provide convenience build
+targets that build the known prerequisites of tests before running the tests,
+unless :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` is enabled:
+
+``test_prep/all``
+  Prepare to run all tests.
+
+``test_prep/<name>``
+  Prepare to run the test ``<name>``.  If multiple tests in different
+  directories share the same name, their dependencies are merged into a single
+  ``test_prep/<name>`` target.
+
+Building a test preparation target ensures that the test executable is
+up-to-date before the test runs.
+
+A test preparation target is generated only when its name can be represented
+safely by the native build tool, as described under :ref:`Target Names`.
+CMake warns about a test that has build dependencies but whose name cannot be
+represented.
+
+CMake infers dependencies associated with tests from the test executable, as
+well as any targets referenced by the test command via generator expressions.
+The ``BUILD_DEPENDS`` option of the :command:`add_test` command can be used to
+add explicit build dependencies.
+
+How file dependencies are prepared depends on how the file is produced.  See
+:ref:`Preparation Target File Dependencies`.
+
+.. versionadded:: 4.5
+
+  Modules may also extend ``test_prep/all`` with directory-scoped dependencies
+  via the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS` directory property.
+
+.. versionchanged:: 4.5
+
+  Test preparation targets are enabled by default.  :generator:`FASTBuild` and
+  the :ref:`Makefile Generators` gained support for test preparation targets.
+  Previously, test preparation targets were only enabled if the
+  :variable:`CMAKE_TEST_BUILD_DEPENDS` variable was enabled.
+
 .. _`Install Preparation Targets`:
 
 Install Preparation Targets
@@ -1846,46 +1893,70 @@ Installing files with the ``FILES`` or ``PROGRAMS`` signatures of the
 :prop_tgt:`PUBLIC_HEADER`, :prop_tgt:`PRIVATE_HEADER`, or :prop_tgt:`RESOURCE`
 files, implies build dependencies only for files that the build produces,
 i.e., target output artifacts, and outputs and byproducts of custom commands
-and custom targets.  How such a file is prepared depends on how it is produced:
+and custom targets.  How such a file is prepared depends on how it is produced.
+See :ref:`Preparation Target File Dependencies`.
+
+.. _`Preparation Target File Dependencies`:
+
+Preparation Target File Dependencies
+------------------------------------
+
+The manner in which a file dependency of a test or install preparation target
+is prepared depends on how it is produced:
 
 * A target's output artifact, such as one named by :genex:`TARGET_FILE`, is
   prepared by building that target.
 
 * A file that is the output of a custom command attached to exactly one
-  target is prepared by running that custom command.  The target which
-  installs the file (or the file set to which the file belongs), if any, is
-  not built.  The :ref:`Makefile Generators` cannot depend on individual
-  files, so they build the target owning the custom command instead.
+  target is prepared by running that custom command.  The
+  :ref:`Makefile Generators` cannot depend on individual files, so they build
+  the target owning the custom command instead.
+
+  The target which installs the file (or the file set to which the file
+  belongs), if any, is not built by installation preparation targets.
 
 * Any other generated file, such as a byproduct or the output of a custom
   command attached to more than one target, is prepared by depending on the
   file itself, which runs whatever produces it.  The
   :ref:`Makefile Generators` and :generator:`FASTBuild` cannot do so, so they
-  warn.  If a target installs the file (or the file set to which the file
-  belongs), they build that target instead, which must therefore depend on
-  the producer, e.g., through :command:`add_dependencies`.  Otherwise, they
-  do not prepare the file.
+  warn.
+
+  For install preparation targets, if a target installs the file (or the file
+  set to which the file belongs), the preparation target will build that target
+  instead, which must therefore depend on the producer, e.g., through
+  :command:`add_dependencies`.  Otherwise, the preparation target does not
+  prepare the file.
 
 For example:
 
 .. code-block:: cmake
 
-  # Preparation runs only the custom command, not the library build.
+  # Preparation which depends on `generated.h` runs only the custom command,
+  # not the library build.
   add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/generated.h"
     COMMAND ...)
   add_library(A a.c "${CMAKE_CURRENT_BINARY_DIR}/generated.h")
   set_property(TARGET A PROPERTY PUBLIC_HEADER
     "${CMAKE_CURRENT_BINARY_DIR}/generated.h")
 
-  # Preparation runs gen, or with some generators builds B instead, so B
-  # must depend on the producer of its byproduct.
+  # Preparation which depends on `byproduct.h` runs `gen`, or with some
+  # generators builds `B` instead, so `B` must depend on the producer of its
+  # byproduct.
   add_custom_target(gen COMMAND ...
     BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/byproduct.h")
   add_library(B b.c)
   add_dependencies(B gen)
+
+  # The preparation target for an install which installs `B` will implicitly
+  # depend on `byproduct.h` when it appears in an associated file set.
   set_property(TARGET B PROPERTY PUBLIC_HEADER
     "${CMAKE_CURRENT_BINARY_DIR}/byproduct.h")
 
+  # A test depending on `byproduct.h` needs to express that dependency
+  # explicitly using `BUILD_DEPENDS`.
+  add_test(test_B COMMAND test_B BUILD_DEPENDS
+    "${CMAKE_CURRENT_BINARY_DIR}/byproduct.h")
+
 The ``BUILD_DEPENDS`` option of the ``FILES``, ``PROGRAMS``, ``DIRECTORY``,
 ``SCRIPT``, and ``CODE`` signatures of the :command:`install` command can
 be used to specify targets or files that CMake cannot infer.  ``DIRECTORY``,

Help/manual/cmake-variables.7.rst

@@ -143,7 +143,6 @@ Variables that Provide Information
    /variable/CMAKE_Swift_MODULE_DIRECTORY
    /variable/CMAKE_Swift_NUM_THREADS
    /variable/CMAKE_Swift_SEPARATE_MODULE_EMISSION
-   /variable/CMAKE_TEST_BUILD_DEPENDS
    /variable/CMAKE_TEST_LAUNCHER
    /variable/CMAKE_TOOLCHAIN_FILE
    /variable/CMAKE_TWEAK_VERSION
@@ -301,6 +300,7 @@ Variables that Change Behavior
    /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
    /variable/CMAKE_SKIP_INSTALL_PREP_TARGETS
    /variable/CMAKE_SKIP_TEST_ALL_DEPENDENCY
+   /variable/CMAKE_SKIP_TEST_PREP_TARGETS
    /variable/CMAKE_STAGING_PREFIX
    /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
    /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
@@ -895,6 +895,7 @@ Deprecated Variables that Change Behavior
    /variable/CMAKE_ERROR_DEPRECATED
    /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
    /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
+   /variable/CMAKE_TEST_BUILD_DEPENDS
    /variable/CMAKE_WARN_DEPRECATED
 
 Deprecated Variables that Describe the System

Help/release/4.5.rst

@@ -86,11 +86,18 @@ Generators
   :ref:`Install Preparation Targets`.
 
 * The :generator:`FASTBuild` generator and the :ref:`Makefile Generators`
-  now generate ``test_prep/<test-name>`` and ``test_prep/all`` convenience
-  build targets when the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is
-  enabled, matching the behavior of the :ref:`Ninja Generators`.  These
-  targets build the dependencies of tests added by :command:`add_test`,
-  including those listed with the ``BUILD_DEPENDS`` keyword.
+  now provide ``test_prep/<test-name>`` and ``test_prep/all`` convenience
+  build targets by default.  The :variable:`CMAKE_SKIP_TEST_PREP_TARGETS`
+  variable may be enabled to skip generating them.  These targets build the
+  dependencies of tests added by :command:`add_test`, including those listed
+  with the ``BUILD_DEPENDS`` keyword.  See :ref:`Test Preparation Targets`.
+
+* The :ref:`Ninja Generators` now provide ``test_prep/<test-name>`` and
+  ``test_prep/all`` convenience build targets build targets by default.  The
+  :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable may be enabled to
+  skip generating them.  These targets were previously generated only if
+  :variable:`CMAKE_TEST_BUILD_DEPENDS` was enabled.  See
+  :ref:`Test Preparation Targets`.
 
 * :ref:`Makefile Generators` and :ref:`Ninja Generators` gained support
   for adding a linker launcher with ``CUDA`` and ``HIP``.
@@ -259,6 +266,11 @@ Variables
 * The :variable:`CMAKE_INSTALL_SBOM_FORMATS` variable was added
   to enable Software Bill of Materials (SBOM) generation.
 
+* The :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is no longer honored.
+  Test preparation targets are now enabled by default.  The
+  :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable may be enabled to skip
+  generating them.
+
 Environment Variables
 ---------------------
 

Help/variable/CMAKE_SKIP_TEST_PREP_TARGETS.rst

@@ -0,0 +1,13 @@
+CMAKE_SKIP_TEST_PREP_TARGETS
+----------------------------
+
+.. versionadded:: 4.5
+
+Do not generate ``test_prep/<name>`` and ``test_prep/all`` build targets.
+
+When this variable is set to a true value, CMake does not generate the
+preparation targets that build the known prerequisites of tests.  See
+:ref:`Test Preparation Targets`.
+
+Set this variable in the top-level directory.  It is off by default, in
+which case the preparation targets are generated.

Help/variable/CMAKE_TEST_BUILD_DEPENDS.rst

@@ -1,36 +1,17 @@
 CMAKE_TEST_BUILD_DEPENDS
 ------------------------
 
+.. deprecated:: 4.5
+
 .. versionadded:: 4.4
 
-Enable ``test_prep/<name>`` build targets for tests added by
-:command:`add_test` when using the :ref:`Ninja Generators`,
-:generator:`FASTBuild`, or :ref:`Makefile Generators`.
+Enabling this variable previously enabled generation of ``test_prep/<name>``
+build targets for tests when using :ref:`Ninja Generators`.  Since CMake 4.5,
+these targets are now enabled by default.  Since CMake 4.5, the
+:variable:`CMAKE_SKIP_TEST_PREP_TARGETS` may be used to disable generation of
+these targets.
 
-.. versionadded:: 4.5
+See Also
+^^^^^^^^
 
-  :generator:`FASTBuild` and the :ref:`Makefile Generators` gained support
-  for ``test_prep/<name>`` targets.
-
-When this variable is set to a true value, CMake generates a
-``test_prep/<name>`` target for each eligible test and a ``test_prep/all``
-target for all such tests. Building these targets ensures the test executable,
-targets referenced by test command generator expressions, and explicit
-``BUILD_DEPENDS`` entries are up-to-date before the test runs.
-
-.. versionadded:: 4.5
-
-  Modules may also extend ``test_prep/all`` with directory-scoped dependencies
-  via the :prop_dir:`CMAKE_TEST_BUILD_DEPENDS` directory property.
-
-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
-unique output of a single target is reported with a warning, and a test whose
-name contains a ``:`` character is excluded because it cannot be expressed as
-a Makefile target.
+* :ref:`Test Preparation Targets`

Source/cmCacheDocumentationTable.cxx

@@ -547,6 +547,8 @@ Entry const kEntries[] = {
     "Default value for the SKIP_LINTING target property"_s },
   { "CMAKE_SKIP_TEST_ALL_DEPENDENCY"_s,
     "If true, test target does not depend on all target; test execution proceeds independently of build status."_s },
+  { "CMAKE_SKIP_TEST_PREP_TARGETS"_s,
+    "Do not generate test_prep/<test> and test_prep/all build targets."_s },
   { "CMAKE_STAGING_PREFIX"_s,
     "Install path to use when cross-compiling; also used as a search prefix by find_*() commands."_s },
   { "CMAKE_STATIC_LINKER_FLAGS"_s,
@@ -579,8 +581,6 @@ Entry const kEntries[] = {
     "Swift language version (defaults based on Xcode version if not set)"_s },
   { "CMAKE_Swift_SEPARATE_MODULE_EMISSION"_s,
     "Whether Swift targets emit .swiftmodule from a dedicated build edge, allowing downstream Swift compilation to overlap with upstream object compilation."_s },
-  { "CMAKE_TEST_BUILD_DEPENDS"_s,
-    "Enable test_prep/<name> build targets for tests added by add_test(), ensuring the test executable and its dependencies are up-to-date before the test runs."_s },
   { "CMAKE_TLS_CAINFO"_s,
     "Path to TLS CA certificate file for file(DOWNLOAD), file(UPLOAD), ExternalProject, and FetchContent"_s },
   { "CMAKE_TLS_VERIFY"_s,

Source/cmGlobalFastbuildGenerator.cxx

@@ -1652,7 +1652,7 @@ void cmGlobalFastbuildGenerator::WriteInstallPrepTargets()
 
 void cmGlobalFastbuildGenerator::WriteTestPrepTargets()
 {
-  if (!this->Makefiles.front()->IsOn("CMAKE_TEST_BUILD_DEPENDS")) {
+  if (this->Makefiles.front()->IsOn("CMAKE_SKIP_TEST_PREP_TARGETS")) {
     return;
   }
 

Source/cmGlobalNinjaGenerator.cxx

@@ -1360,6 +1360,10 @@ void cmGlobalNinjaGenerator::WriteInstallPrepTargets()
 
 void cmGlobalNinjaGenerator::WriteTestPrepTargets()
 {
+  if (this->Makefiles.front()->IsOn("CMAKE_SKIP_TEST_PREP_TARGETS")) {
+    return;
+  }
+
   std::map<std::string, std::set<std::string>> configsByName;
   auto writeConfig = [this, &configsByName](std::string const& config) {
     struct TestPrepTarget
@@ -1444,9 +1448,6 @@ void cmGlobalNinjaGenerator::WriteTestPrepTargets()
     this->WritePerConfigPhony(config, build);
   };
 
-  if (!this->Makefiles.front()->IsOn("CMAKE_TEST_BUILD_DEPENDS")) {
-    return;
-  }
   if (this->IsMultiConfig()) {
     for (std::string const& config : this->GetConfigNames()) {
       writeConfig(config);

Source/cmGlobalUnixMakefileGenerator3.cxx

@@ -1022,7 +1022,7 @@ void cmGlobalUnixMakefileGenerator3::ComputeTestPrepTargets()
   this->TestPrepTargets.clear();
   this->TestPrepEnabled = false;
   if (this->Makefiles.empty() ||
-      !this->Makefiles.front()->IsOn("CMAKE_TEST_BUILD_DEPENDS")) {
+      this->Makefiles.front()->IsOn("CMAKE_SKIP_TEST_PREP_TARGETS")) {
     return;
   }
   this->TestPrepEnabled = true;

Source/cmGlobalUnixMakefileGenerator3.h

@@ -236,9 +236,8 @@ protected:
   void AppendCodegenTargetDepends(std::vector<std::string>& depends,
                                   cmGeneratorTarget* target);
 
-  // Compute the "test_prep/<name>" build targets requested via the
-  // CMAKE_TEST_BUILD_DEPENDS variable.  Each test's dependencies are
-  // resolved to the build-system targets that produce them so that the
+  // Compute the "test_prep/<name>" build targets.  Each test's dependencies
+  // are resolved to the build-system targets that produce them so that the
   // recursive Makefile graph can build them.
   void ComputeTestPrepTargets();
 
@@ -359,7 +358,7 @@ private:
   };
 
   // Ordered map of "test_prep/" target name -> its rules.  Populated by
-  // ComputeTestPrepTargets when CMAKE_TEST_BUILD_DEPENDS is enabled.
+  // ComputeTestPrepTargets when test preparation targets are enabled.
   std::map<std::string, TestPrepTarget> TestPrepTargets;
   TestPrepTarget& GetTestPrepTarget(std::string const& name);
   void AddDirectoryTestPrepTargets(cmLocalGenerator* lg);

Tests/RunCMake/GoogleTest/GoogleTestBuildDepends.cmake

@@ -3,8 +3,6 @@ include(GoogleTest)
 
 enable_testing()
 
-set(CMAKE_TEST_BUILD_DEPENDS ON)
-
 add_executable(fake_gtest fake_gtest.cpp)
 
 gtest_discover_tests(

Tests/RunCMake/TestDependency/AddTest.cmake

@@ -2,7 +2,6 @@ cmake_minimum_required(VERSION 4.3)
 project(TestDependencyAddTest C)
 
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_discovery fake_discovery.c)
 # Ensure the timestamp check uses the artifact path, not the target name.

Tests/RunCMake/TestDependency/DirectoryGeneratedFile.cmake

@@ -1,6 +1,5 @@
 project(TestDependencyDirectoryGeneratedFile NONE)
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 set(output "${CMAKE_CURRENT_BINARY_DIR}/directory-generated.txt")
 add_custom_command(OUTPUT "${output}"

Tests/RunCMake/TestDependency/DiscoverTests.cmake

@@ -2,7 +2,6 @@ cmake_minimum_required(VERSION 4.3)
 project(TestDependencyDiscoverGeneric C)
 
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_discovery fake_discovery.c)
 

Tests/RunCMake/TestDependency/DiscoverTestsBuildDepends.cmake

@@ -2,7 +2,6 @@ cmake_minimum_required(VERSION 4.3)
 project(TestDependencyDiscoverGenericBuildDepends C)
 
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_discovery fake_discovery.c)
 

Tests/RunCMake/TestDependency/DiscoverTestsCommands.cmake

@@ -1,6 +1,5 @@
 project(TestDependencyDiscoverCommands C)
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(command_genex EXCLUDE_FROM_ALL fake_discovery.c)
 add_executable(command_wrapper EXCLUDE_FROM_ALL fake_discovery.c)

Tests/RunCMake/TestDependency/DiscoverTestsGeneratedFile.cmake

@@ -1,6 +1,5 @@
 project(TestDependencyDiscoverGeneratedFile C)
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_discovery EXCLUDE_FROM_ALL fake_discovery.c)
 set(output "${CMAKE_CURRENT_BINARY_DIR}/generated.txt")

Tests/RunCMake/TestDependency/DiscoverTestsUtility.cmake

@@ -1,6 +1,5 @@
 project(TestDependencyDiscoverUtility C)
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_discovery EXCLUDE_FROM_ALL fake_discovery.c)
 add_custom_target(discovery_utility

Tests/RunCMake/TestDependency/GoogleTest-POST_BUILD.cmake

@@ -4,7 +4,6 @@ project(TestDependencyDiscoverPostBuild CXX)
 include(GoogleTest)
 
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_gtest fake_gtest_post_build.cpp)
 

Tests/RunCMake/TestDependency/GoogleTest-PRE_TEST.cmake

@@ -4,7 +4,6 @@ project(TestDependencyGoogleTestPreTest CXX)
 include(GoogleTest)
 
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_gtest fake_gtest_post_build.cpp)
 

Tests/RunCMake/TestDependency/MissingBuildDependency.cmake

@@ -1,5 +1,4 @@
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_test(NAME Direct
   COMMAND "${CMAKE_COMMAND}" -E true

Tests/RunCMake/TestDependency/OFF.cmake

@@ -1,3 +1,3 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS OFF)
+set(CMAKE_SKIP_TEST_PREP_TARGETS ON)
 include(${CMAKE_CURRENT_LIST_DIR}/TestDependency.cmake)

Tests/RunCMake/TestDependency/ON-byproduct.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyByproduct C)
 

Tests/RunCMake/TestDependency/ON-case.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyCase NONE)
 

Tests/RunCMake/TestDependency/ON-colon-name.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyColonName C)
 

Tests/RunCMake/TestDependency/ON-file-generate-config.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyFileGenerateConfig C)
 

Tests/RunCMake/TestDependency/ON-imported.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyImported C)
 

Tests/RunCMake/TestDependency/ON-interface.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyInterface C)
 

Tests/RunCMake/TestDependency/ON-invalid-test-name.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyInvalidTestName C)
 

Tests/RunCMake/TestDependency/ON-orphan.cmake

@@ -1,5 +1,4 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 project(TestDependencyOrphan C)
 

Tests/RunCMake/TestDependency/ON.cmake

@@ -1,3 +1,3 @@
 cmake_minimum_required(VERSION 4.3)
-set(CMAKE_TEST_BUILD_DEPENDS ON)
+set(CMAKE_SKIP_TEST_PREP_TARGETS OFF)
 include(${CMAKE_CURRENT_LIST_DIR}/TestDependency.cmake)

Tests/RunCMake/TestDependency/ObjectLibrary.cmake

@@ -1,6 +1,5 @@
 project(TestDependencyObjectLibrary C)
 enable_testing()
-set(CMAKE_TEST_BUILD_DEPENDS ON)
 
 add_executable(fake_discovery EXCLUDE_FROM_ALL fake_discovery.c)
 add_library(dependency_objects OBJECT EXCLUDE_FROM_ALL fake_discovery.c)

Tests/RunCMake/TestDependency/RunCMakeTest.cmake

@@ -165,7 +165,6 @@ if(RunCMake_GENERATOR MATCHES "Ninja|FASTBuild|Makefiles")
 
     # "Failure" cases, do not generate test dependencies
     block()
-      run_testdependency_case(DEFAULT FALSE)
       run_testdependency_case(OFF FALSE)
       run_cmake(ON-invalid-test-name)
     endblock()
@@ -277,6 +276,7 @@ if(RunCMake_GENERATOR MATCHES "Ninja|FASTBuild|Makefiles")
       endblock()
 
       # Verify test_depends
+      run_testdependency_case(DEFAULT TRUE)
       run_testdependency_case(ON TRUE)
 
       # Verify test_depends + --out-of-date for add_test