Merge topic 'patch-exec-program'

7b79c2b39d exec_program: Add example how to upgrade to execute_process()

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !10667

Help/command/exec_program.rst

diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst
index 6010176..7925c21 100644
--- a/Help/command/exec_program.rst
+++ b/Help/command/exec_program.rst
@@ -9,22 +9,55 @@
 
   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 <arguments to executable>]
-               [OUTPUT_VARIABLE <var>]
-               [RETURN_VALUE <var>])
+  exec_program(
+    <executable>
+    [<working-dir>]
+    [ARGS <arguments-to-executable>...]
+    [OUTPUT_VARIABLE <var>]
+    [RETURN_VALUE <var>]
+  )
 
-The executable is run in the optionally specified directory.  The
+The ``<executable>`` is run in the optionally specified directory
+``<working-dir>``.  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 "\"<quoted-arg>\""
+    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 "<quoted-arg>"
+    WORKING_DIRECTORY ${dir}
+    RESULT_VARIABLE result
+    OUTPUT_VARIABLE output
+    ERROR_VARIABLE output
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+  )