From 1666b715eb2e102e26d310ddadcaef934392a59d Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Mon, 24 Mar 2025 14:34:06 +0100
Subject: [PATCH] TEST_INCLUDE_{FILE,FILES}: Update documentation

The TEST_INCLUDE_FILE directory property got deprecated in CMake 3.10
and TEST_INCLUDE_FILES should be used instead. This extends descriptions
a bit to better understand this property.
---
 Help/prop_dir/TEST_INCLUDE_FILE.rst  | 13 +++++++---
 Help/prop_dir/TEST_INCLUDE_FILES.rst | 37 +++++++++++++++++++++++++---
 2 files changed, 43 insertions(+), 7 deletions(-)

diff --git a/Help/prop_dir/TEST_INCLUDE_FILE.rst b/Help/prop_dir/TEST_INCLUDE_FILE.rst
index 31b23829d4..883b124a4e 100644
--- a/Help/prop_dir/TEST_INCLUDE_FILE.rst
+++ b/Help/prop_dir/TEST_INCLUDE_FILE.rst
@@ -1,9 +1,14 @@
 TEST_INCLUDE_FILE
 -----------------
 
-Deprecated.  Use :prop_dir:`TEST_INCLUDE_FILES` instead.
+.. deprecated:: 3.10
 
-A cmake file that will be included when ctest is run.
+  Use the :prop_dir:`TEST_INCLUDE_FILES` directory property instead, which
+  supports specifying multiple files.
 
-If you specify ``TEST_INCLUDE_FILE``, that file will be included and
-processed when ctest is run on the directory.
+The ``TEST_INCLUDE_FILE`` directory property specifies a CMake script that is
+included and processed when ``ctest`` is run on the directory.
+
+If both the ``TEST_INCLUDE_FILE`` and :prop_dir:`TEST_INCLUDE_FILES` directory
+properties are set, the script specified in ``TEST_INCLUDE_FILE`` is included
+first, followed by the scripts listed in ``TEST_INCLUDE_FILES``.
diff --git a/Help/prop_dir/TEST_INCLUDE_FILES.rst b/Help/prop_dir/TEST_INCLUDE_FILES.rst
index f9a66f42c0..f1c583facd 100644
--- a/Help/prop_dir/TEST_INCLUDE_FILES.rst
+++ b/Help/prop_dir/TEST_INCLUDE_FILES.rst
@@ -3,7 +3,38 @@ TEST_INCLUDE_FILES
 
 .. versionadded:: 3.10
 
-A list of cmake files that will be included when ctest is run.
+This directory property specifies a list of CMake scripts to be included and
+processed when ``ctest`` runs on the directory.  Use absolute paths, to avoid
+ambiguity.  Script files are included in the specified order.
 
-If you specify ``TEST_INCLUDE_FILES``, those files will be included and
-processed when ctest is run on the directory.
+``TEST_INCLUDE_FILES`` scripts are processed when running ``ctest``, not during
+the ``cmake`` configuration phase.  These scripts should be written as if they
+were CTest dashboard scripts.  It is common to generate such scripts dynamically
+since many variables and commands available during configuration are not
+accessible at test phase.
+
+Examples
+^^^^^^^^
+
+Setting this directory property to append one or more CMake scripts:
+
+.. code-block:: cmake
+  :caption: CMakeLists.txt
+
+  configure_file(script.cmake.in script.cmake)
+
+  set_property(
+    DIRECTORY
+    APPEND
+    PROPERTY TEST_INCLUDE_FILES
+      ${CMAKE_CURRENT_BINARY_DIR}/script.cmake
+      ${CMAKE_CURRENT_SOURCE_DIR}/foo.cmake
+      ${dir}/bar.cmake
+  )
+
+.. code-block:: cmake
+  :caption: script.cmake.in
+
+  execute_process(
+    COMMAND "@CMAKE_COMMAND@" -E echo "script.cmake executed during CTest"
+  )