Merge topic 'try-doc'

b6cfbe7b17 Help:try_{compile,run}: clarify, encourage new syntax

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

1 files changed, 18 insertions, 19 deletions

diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst
index 7566264..3a4e203 100644
--- a/Help/command/try_run.rst
+++ b/Help/command/try_run.rst
@@ -32,20 +32,20 @@ Try Compiling and Running Source Files
           [RUN_OUTPUT_VARIABLE <var>]
           [RUN_OUTPUT_STDOUT_VARIABLE <var>]
           [RUN_OUTPUT_STDERR_VARIABLE <var>]
-          [OUTPUT_VARIABLE <var>]
           [WORKING_DIRECTORY <var>]
           [ARGS <args>...]
           )
 
 .. versionadded:: 3.25
 
-Try compiling a ``<srcfile>``.  Returns ``TRUE`` or ``FALSE`` for success
-or failure in ``<compileResultVar>``.  If the compile succeeded, runs the
-executable and returns its exit code in ``<runResultVar>``.  If the
-executable was built, but failed to run, then ``<runResultVar>`` will be
-set to ``FAILED_TO_RUN``.  See the :command:`try_compile` command for
-documentation of options common to both commands, and for information on how
-the test project is constructed to build the source file.
+Try building an executable from one or more source files.  Build success
+returns ``TRUE`` and build failure returns ``FALSE`` in ``<compileResultVar>``.
+If the build succeeds, this runs the executable and stores the exit code in
+``<runResultVar>``.  If the executable was built, but failed to run, then
+``<runResultVar>`` will be set to ``FAILED_TO_RUN``.  See command
+:command:`try_compile` for documentation of options common to both commands,
+and for information on how the test project is constructed to build the source
+file.
 
 One or more source files must be provided. Additionally, one of ``SOURCES``
 and/or ``SOURCE_FROM_*`` must precede other keywords.
@@ -55,16 +55,13 @@ and/or ``SOURCE_FROM_*`` must precede other keywords.
   :ref:`configure-log try_run event <try_run configure-log event>`
   if the ``NO_LOG`` option is not specified.
 
-This command also supports an alternate signature
-which was present in older versions of CMake:
+This command supports an alternate signature for CMake older than 3.25.
+The signature above is recommended for clarity.
 
 .. code-block:: cmake
 
   try_run(<runResultVar> <compileResultVar>
           <bindir> <srcfile|SOURCES srcfile...>
-          [LOG_DESCRIPTION <text>]
-          [NO_CACHE]
-          [NO_LOG]
           [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]
@@ -75,8 +72,6 @@ which was present in older versions of CMake:
           [<LANG>_STANDARD_REQUIRED <bool>]
           [<LANG>_EXTENSIONS <bool>]
           [RUN_OUTPUT_VARIABLE <var>]
-          [RUN_OUTPUT_STDOUT_VARIABLE <var>]
-          [RUN_OUTPUT_STDERR_VARIABLE <var>]
           [OUTPUT_VARIABLE <var>]
           [WORKING_DIRECTORY <var>]
           [ARGS <args>...]
@@ -119,15 +114,19 @@ The options specific to ``try_run`` are:
 Other Behavior Settings
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
-a build configuration.
+Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
+configuration:
+
+* For multi-config generators, this selects which configuration to build.
+
+* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
+  the test project.
 
 Behavior when Cross Compiling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.3
-  Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled
-  binaries.
+  Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled binaries.
 
 When cross compiling, the executable compiled in the first step
 usually cannot be run on the build host.  The ``try_run`` command checks