kolan/CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'doc-execute_process'

Browse Source 
3bb6266 Help: Clarify execute_process COMMAND argument behavior
ea6b656 Help: Format execute_process command documentation
This commit is contained in:
Brad King 2013-11-08 10:32:58 -05:00 committed by CMake Topic Stage
commit 81d6a0055a
1 changed files with 52 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
Help/command/execute_process.rst
View File

@ -3,7 +3,7 @@ execute_process
Execute one or more child processes. Execute one or more child processes.
:: .. code-block:: cmake
execute_process(COMMAND <cmd1> [args1...]] execute_process(COMMAND <cmd1> [args1...]]
[COMMAND <cmd2> [args2...] [...]] [COMMAND <cmd2> [args2...] [...]]
@ -21,28 +21,55 @@ Execute one or more child processes.
[ERROR_STRIP_TRAILING_WHITESPACE]) [ERROR_STRIP_TRAILING_WHITESPACE])
Runs the given sequence of one or more commands with the standard Runs the given sequence of one or more commands with the standard
output of each process piped to the standard input of the next. A output of each process piped to the standard input of the next.
single standard error pipe is used for all processes. If A single standard error pipe is used for all processes.
WORKING_DIRECTORY is given the named directory will be set as the
current working directory of the child processes. If TIMEOUT is given
the child processes will be terminated if they do not finish in the
specified number of seconds (fractions are allowed). If
RESULT_VARIABLE is given the variable will be set to contain the
result of running the processes. This will be an integer return code
from the last child or a string describing an error condition. If
OUTPUT_VARIABLE or ERROR_VARIABLE are given the variable named will be
set with the contents of the standard output and standard error pipes
respectively. If the same variable is named for both pipes their
output will be merged in the order produced. If INPUT_FILE,
OUTPUT_FILE, or ERROR_FILE is given the file named will be attached to
the standard input of the first process, standard output of the last
process, or standard error of all processes respectively. If
OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
standard error results will be quietly ignored. If more than one
OUTPUT_* or ERROR_* option is given for the same pipe the precedence
is not specified. If no OUTPUT_* or ERROR_* options are given the
output will be shared with the corresponding pipes of the CMake
process itself.
The execute_process command is a newer more powerful version of Options:
exec_program, but the old command has been kept for compatibility.
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.
TIMEOUT
The child processes will be terminated if they do not finish in the
specified number of seconds (fractions are allowed).
RESULT_VARIABLE
The variable will be set to contain the result of running the processes.
This will be an integer return code from the last child or a string
describing an error condition.
OUTPUT_VARIABLE, ERROR_VARIABLE
The variable named will be set with the contents of the standard output
and standard error pipes, respectively. If the same variable is named
for both pipes their output will be merged in the order produced.
INPUT_FILE, OUTPUT_FILE, ERROR_FILE
The file named will be attached to the standard input of the first
process, standard output of the last process, or standard error of
all processes, respectively.
OUTPUT_QUIET, ERROR_QUIET
The standard output or standard error results will be quietly ignored.
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is not specified.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
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.