add_test: Optionally use a launcher for tests running in-project targets

Add a `CMAKE_TEST_LAUNCHER` variable and corresponding `TEST_LAUNCHER`
target property.

Issue: #23672

1 files changed, 25 insertions, 3 deletions

diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst
index 02dd3986..37b9563 100644
--- a/Help/command/add_test.rst
+++ b/Help/command/add_test.rst
@@ -27,9 +27,31 @@ directory the test is created in.
 ``add_test`` options are:
 
 ``COMMAND``
-  Specify the test command-line.  If ``<command>`` specifies an executable
-  target created by :command:`add_executable`, it will automatically be
-  replaced by the location of the executable created at build time.
+  Specify the test command-line.
+
+  If ``<command>`` specifies an executable target created by
+  :command:`add_executable`:
+
+  * It will automatically be replaced by the location of the executable
+    created at build time.
+
+  * .. versionadded:: 3.3
+
+      The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be
+      used to run the command on the host::
+
+        <emulator> <command>
+
+  * .. versionadded:: 3.29
+
+      The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be
+      used to launch the command::
+
+        <launcher> <command>
+
+      If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used::
+
+        <launcher> <emulator> <command>
 
   The command may be specified using
   :manual:`generator expressions <cmake-generator-expressions(7)>`.