Help: Clarify how target names are handled in custom commands/targets

Fixes: #19771

2 files changed, 45 insertions, 25 deletions

diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index ab2a023..df7cc4e 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -79,25 +79,33 @@ The options are:
   will be ignored.
 
   If ``COMMAND`` specifies an executable target name (created by the
-  :command:`add_executable` command) it will automatically be replaced
-  by the location of the executable created at build time. If set, the
-  :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
-  also be prepended to the command to allow the executable to run on
-  the host.
-  (Use the ``TARGET_FILE``
-  :manual:`generator expression <cmake-generator-expressions(7)>` to
-  reference an executable later in the command line.)
-  Additionally a target-level dependency will be added so that the
-  executable target will be built before any target using this custom
-  command.  However this does NOT add a file-level dependency that
-  would cause the custom command to re-run whenever the executable is
-  recompiled.
+  :command:`add_executable` command), it will automatically be replaced
+  by the location of the executable created at build time if either of
+  the following is true:
+
+  * The target is not being cross-compiled (i.e. the
+    :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
+  * The target is being cross-compiled and an emulator is provided (i.e.
+    its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
+    In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
+    prepended to the command before the location of the target executable.
+
+  If neither of the above conditions are met, it is assumed that the
+  command name is a program to be found on the ``PATH`` at build time.
 
   Arguments to ``COMMAND`` may use
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
-  References to target names in generator expressions imply target-level
-  dependencies, but NOT file-level dependencies.  List target names with
-  the ``DEPENDS`` option to add file-level dependencies.
+  Use the ``TARGET_FILE`` generator expression to refer to the location of
+  a target later in the command line (i.e. as a command argument rather
+  than as the command to execute).
+
+  Whenever a target is used as a command to execute or is mentioned in a
+  generator expression as a command argument, a target-level dependency
+  will be added automatically so that the mentioned target will be built
+  before any target using this custom command.  However this does NOT add
+  a file-level dependency that would cause the custom command to re-run
+  whenever the executable is recompiled.  List target names with
+  the ``DEPENDS`` option to add such file-level dependencies.
 
 ``COMMENT``
   Display the given message before the commands are executed at
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index e74960c..2d5f5f0 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -58,18 +58,30 @@ The options are:
   a ``COMMAND`` to launch it.)
 
   If ``COMMAND`` specifies an executable target name (created by the
-  :command:`add_executable` command) it will automatically be replaced
-  by the location of the executable created at build time. If set, the
-  :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
-  also be prepended to the command to allow the executable to run on
-  the host.
-  Additionally a target-level dependency will be added so that the
-  executable target will be built before this custom target.
+  :command:`add_executable` command), it will automatically be replaced
+  by the location of the executable created at build time if either of
+  the following is true:
+
+  * The target is not being cross-compiled (i.e. the
+    :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
+  * The target is being cross-compiled and an emulator is provided (i.e.
+    its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
+    In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
+    prepended to the command before the location of the target executable.
+
+  If neither of the above conditions are met, it is assumed that the
+  command name is a program to be found on the ``PATH`` at build time.
 
   Arguments to ``COMMAND`` may use
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
-  References to target names in generator expressions imply target-level
-  dependencies.
+  Use the ``TARGET_FILE`` generator expression to refer to the location of
+  a target later in the command line (i.e. as a command argument rather
+  than as the command to execute).
+
+  Whenever a target is used as a command to execute or is mentioned in a
+  generator expression as a command argument, a target-level dependency
+  will be added automatically so that the mentioned target will be built
+  before this custom target.
 
   The command and arguments are optional and if not specified an empty
   target will be created.