Help: Clarify execute_process COMMAND argument behavior

State in the execute_process how COMMAND arguments are passed to
the child.  Add a note at the end about how the command differs
from add_custom_*().

Suggested-by: Alan W. Irwin

1 files changed, 14 insertions, 0 deletions

diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst
index af69f3f..478b30e 100644
--- a/Help/command/execute_process.rst
+++ b/Help/command/execute_process.rst
@@ -26,6 +26,16 @@ A single standard error pipe is used for all processes.
 
 Options:
 
+COMMAND
+ A child process command line.
+
+ CMake executes the child process using operating system APIs directly.
+ All arguments are passed VERBATIM to the child process.
+ No intermediate shell is used, so shell operators such as ``>``
+ are treated as normal arguments.
+ (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
+ redirect stdin, stdout, and stderr.)
+
 WORKING_DIRECTORY
  The named directory will be set as the current working directory of
  the child processes.
@@ -59,3 +69,7 @@ be shared with the corresponding pipes of the CMake process itself.
 
 The :command:`execute_process` command is a newer more powerful version of
 :command:`exec_program`, but the old command has been kept for compatibility.
+Both commands run while CMake is processing the project prior to build
+system generation.  Use :command:`add_custom_target` and
+:command:`add_custom_command` to create custom commands that run at
+build time.