1execute_process
2---------------
3
4Execute one or more child processes.
5
6.. code-block:: cmake
7
8  execute_process(COMMAND <cmd1> [<arguments>]
9                  [COMMAND <cmd2> [<arguments>]]...
10                  [WORKING_DIRECTORY <directory>]
11                  [TIMEOUT <seconds>]
12                  [RESULT_VARIABLE <variable>]
13                  [RESULTS_VARIABLE <variable>]
14                  [OUTPUT_VARIABLE <variable>]
15                  [ERROR_VARIABLE <variable>]
16                  [INPUT_FILE <file>]
17                  [OUTPUT_FILE <file>]
18                  [ERROR_FILE <file>]
19                  [OUTPUT_QUIET]
20                  [ERROR_QUIET]
21                  [COMMAND_ECHO <where>]
22                  [OUTPUT_STRIP_TRAILING_WHITESPACE]
23                  [ERROR_STRIP_TRAILING_WHITESPACE]
24                  [ENCODING <name>]
25                  [ECHO_OUTPUT_VARIABLE]
26                  [ECHO_ERROR_VARIABLE]
27                  [COMMAND_ERROR_IS_FATAL <ANY|LAST>])
28
29Runs the given sequence of one or more commands.
30
31Commands are executed concurrently as a pipeline, with the standard
32output of each process piped to the standard input of the next.
33A single standard error pipe is used for all processes.
34
35Options:
36
37``COMMAND``
38 A child process command line.
39
40 CMake executes the child process using operating system APIs directly.
41 All arguments are passed VERBATIM to the child process.
42 No intermediate shell is used, so shell operators such as ``>``
43 are treated as normal arguments.
44 (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
45 redirect stdin, stdout, and stderr.)
46
47 If a sequential execution of multiple commands is required, use multiple
48 :command:`execute_process` calls with a single ``COMMAND`` argument.
49
50``WORKING_DIRECTORY``
51 The named directory will be set as the current working directory of
52 the child processes.
53
54``TIMEOUT``
55 After the specified number of seconds (fractions allowed), all unfinished
56 child processes will be terminated, and the ``RESULT_VARIABLE`` will be
57 set to a string mentioning the "timeout".
58
59``RESULT_VARIABLE``
60 The variable will be set to contain the result of last child process.
61 This will be an integer return code from the last child or a string
62 describing an error condition.
63
64``RESULTS_VARIABLE <variable>``
65 .. versionadded:: 3.10
66
67 The variable will be set to contain the result of all processes as a
68 :ref:`semicolon-separated list <CMake Language Lists>`, in order of the
69 given ``COMMAND`` arguments.  Each entry will be an integer return code
70 from the corresponding child or a string describing an error condition.
71
72``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
73 The variable named will be set with the contents of the standard output
74 and standard error pipes, respectively.  If the same variable is named
75 for both pipes their output will be merged in the order produced.
76
77``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE``
78 The file named will be attached to the standard input of the first
79 process, standard output of the last process, or standard error of
80 all processes, respectively.
81
82 .. versionadded:: 3.3
83  If the same file is named for both output and error then it will be used
84  for both.
85
86``OUTPUT_QUIET``, ``ERROR_QUIET``
87 The standard output or standard error results will be quietly ignored.
88
89``COMMAND_ECHO <where>``
90 .. versionadded:: 3.15
91
92 The command being run will be echo'ed to ``<where>`` with ``<where>``
93 being set to one of ``STDERR``, ``STDOUT`` or ``NONE``.
94 See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way
95 to control the default behavior when this option is not present.
96
97``ENCODING <name>``
98 .. versionadded:: 3.8
99
100 On Windows, the encoding that is used to decode output from the process.
101 Ignored on other platforms.
102 Valid encoding names are:
103
104 ``NONE``
105   Perform no decoding.  This assumes that the process output is encoded
106   in the same way as CMake's internal encoding (UTF-8).
107   This is the default.
108 ``AUTO``
109   Use the current active console's codepage or if that isn't
110   available then use ANSI.
111 ``ANSI``
112   Use the ANSI codepage.
113 ``OEM``
114   Use the original equipment manufacturer (OEM) code page.
115 ``UTF8`` or ``UTF-8``
116   Use the UTF-8 codepage.
117
118   .. versionadded:: 3.11
119     Accept ``UTF-8`` spelling for consistency with the
120     `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
121
122``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
123  .. versionadded:: 3.18
124
125  The standard output or standard error will not be exclusively redirected to
126  the configured variables.
127
128  The output will be duplicated, it will be sent into the configured variables
129  and also on standard output or standard error.
130
131  This is analogous to the ``tee`` Unix command.
132
133``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
134  .. versionadded:: 3.19
135
136  The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when
137  an error is encountered:
138
139    ``ANY``
140    If any of the commands in the list of commands fail, the
141    ``execute_process()`` command halts with an error.
142
143    ``LAST``
144    If the last command in the list of commands fails, the
145    ``execute_process()`` command halts with an error.  Commands earlier in the
146    list will not cause a fatal error.
147
148If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
149same pipe the precedence is not specified.
150If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
151be shared with the corresponding pipes of the CMake process itself.
152
153The :command:`execute_process` command is a newer more powerful version of
154:command:`exec_program`, but the old command has been kept for compatibility.
155Both commands run while CMake is processing the project prior to build
156system generation.  Use :command:`add_custom_target` and
157:command:`add_custom_command` to create custom commands that run at
158build time.
159