Merge topic 'try-doc'

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

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

2 files changed, 37 insertions, 39 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 21b063f..8abb6e0 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -14,7 +14,7 @@ Try Compiling Whole Projects
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> PROJECT <projectName>
+  try_compile(<compileResultVar> PROJECT <projectName>
               SOURCE_DIR <srcdir>
               [BINARY_DIR <bindir>]
               [TARGET <targetName>]
@@ -26,8 +26,8 @@ Try Compiling Whole Projects
 
 .. versionadded:: 3.25
 
-Try building a project.  The success or failure of the ``try_compile``,
-i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
+Try building a project.  Build success returns ``TRUE`` and build failure
+returns ``FALSE`` in ``<compileResultVar>``.
 
 In this form, ``<srcdir>`` should contain a complete CMake project with a
 ``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
@@ -47,16 +47,13 @@ below for the meaning of other options.
   :ref:`configure-log try_compile event <try_compile 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_compile(<resultVar> <bindir> <srcdir>
+  try_compile(<compileResultVar> <bindir> <srcdir>
               <projectName> [<targetName>]
-              [LOG_DESCRIPTION <text>]
-              [NO_CACHE]
-              [NO_LOG]
               [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
 
@@ -67,7 +64,7 @@ Try Compiling Source Files
 
 .. code-block:: cmake
 
-  try_compile(<resultVar>
+  try_compile(<compileResultVar>
               <SOURCES <srcfile...>                 |
                SOURCE_FROM_CONTENT <name> <content> |
                SOURCE_FROM_VAR <name> <var>         |
@@ -90,8 +87,8 @@ Try Compiling Source Files
 
 Try building an executable or static library from one or more source files
 (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
-variable).  The success or failure of the ``try_compile``, i.e. ``TRUE`` or
-``FALSE`` respectively, is returned in ``<resultVar>``.
+variable). Build success returns ``TRUE`` and build failure returns ``FALSE``
+in ``<compileResultVar>``.
 
 In this form, one or more source files must be provided. Additionally, one of
 ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.
@@ -120,15 +117,12 @@ with an unspecified name.  These directories are cleaned automatically unless
 Such directories from previous runs are also unconditionally cleaned at the
 beginning of any :program:`cmake` execution.
 
-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_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
-              [LOG_DESCRIPTION <text>]
-              [NO_CACHE]
-              [NO_LOG]
+  try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]
@@ -300,8 +294,13 @@ Other Behavior Settings
 The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
 through to the generated test project.
 
-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.
 
 .. versionadded:: 3.6
   Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
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