From 7b79c2b39d1762cf2fb74fab0eb6fbb23814484f Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Thu, 17 Apr 2025 00:42:15 +0200
Subject: [PATCH] exec_program: Add example how to upgrade to execute_process()

This hopefully helps a bit when upgrading CMake code that uses
`exec_program()` command.

Changes:
- Used third-person phrasing for the command description.
- The `exec_program()` command arguments in signature updated a bit.
- Mention of CMakeLists.txt file removed as this command also worked in
  CMake scripts and other modes.
- Added examples section.
---
 Help/command/exec_program.rst | 51 ++++++++++++++++++++++++++++-------
 1 file changed, 42 insertions(+), 9 deletions(-)

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 <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
+  )