diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst index 6010176411..7925c21060 100644 --- a/Help/command/exec_program.rst +++ b/Help/command/exec_program.rst @@ -9,22 +9,55 @@ exec_program Use the :command:`execute_process` command instead. -Run an executable program during the processing of the CMakeList.txt -file. +Runs an executable program during the processing of a CMake file or script: .. code-block:: cmake - exec_program(Executable [directory in which to run] - [ARGS ] - [OUTPUT_VARIABLE ] - [RETURN_VALUE ]) + exec_program( + + [] + [ARGS ...] + [OUTPUT_VARIABLE ] + [RETURN_VALUE ] + ) -The executable is run in the optionally specified directory. The +The ```` is run in the optionally specified directory +````. The executable can include arguments if it is double quoted, but it is better to use the optional ``ARGS`` argument to specify arguments to the -program. This is because cmake will then be able to escape spaces in +executable program. This is because CMake will then be able to escape spaces in the executable path. An optional argument ``OUTPUT_VARIABLE`` specifies a variable in which to store the output. To capture the return value of the execution, provide a ``RETURN_VALUE``. If ``OUTPUT_VARIABLE`` is specified, then no output will go to the stdout/stderr of the console -running cmake. +running CMake. + +Examples +^^^^^^^^ + +Example of the legacy ``exec_program()`` command used in earlier versions of +CMake: + +.. code-block:: cmake + + exec_program( + some_command + ${dir} + ARGS arg_1 arg_2 args "\"\"" + OUTPUT_VARIABLE output + RETURN_VALUE result + ) + +A direct equivalent replacement of the previous example using the +:command:`execute_process` command in new code: + +.. code-block:: cmake + + execute_process( + COMMAND some_command arg_1 arg_2 args "" + WORKING_DIRECTORY ${dir} + RESULT_VARIABLE result + OUTPUT_VARIABLE output + ERROR_VARIABLE output + OUTPUT_STRIP_TRAILING_WHITESPACE + )