Merge topic 'docs_try_commands'

4d55c1f541 Help: Caveat for try_compile() and CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
861dbef4e7 Help: Consistency in try_compile() docs for target type
df8aa3c8ad Help: try_compile() readability and grammar improvements
7975edeac5 Help: User-provided variable names for try_* commands

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

2 files changed, 33 insertions, 25 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 77f42a1..ca8fc77 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -12,12 +12,12 @@ Try Compiling Whole Projects
 
 .. code-block:: cmake
 
-  try_compile(RESULT_VAR <bindir> <srcdir>
+  try_compile(<resultVar> <bindir> <srcdir>
               <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
 
 Try building a project.  The success or failure of the ``try_compile``,
-i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``.
+i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
 
 In this form, ``<srcdir>`` should contain a complete CMake project with a
 ``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
@@ -30,7 +30,7 @@ Try Compiling Source Files
 
 .. code-block:: cmake
 
-  try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
+  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]
@@ -42,13 +42,19 @@ Try Compiling Source Files
               [<LANG>_EXTENSIONS <bool>]
               )
 
-Try building an executable from one or more source files.  The success or
-failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is
-returned in ``RESULT_VAR``.
+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>``.
 
-In this form the user need only supply one or more source files that include a
-definition for ``main``.  CMake will create a ``CMakeLists.txt`` file to build
-the source(s) as an executable that looks something like this:
+In this form, one or more source files must be provided.  If
+:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``,
+the sources must include a definition for ``main`` and CMake will create a
+``CMakeLists.txt`` file to build the source(s) as an executable.
+If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``,
+a static library will be built instead and no definition for ``main`` is
+required.  For an executable, the generated ``CMakeLists.txt`` file would
+contain something like the following:
 
 .. code-block:: cmake
 
@@ -73,7 +79,7 @@ The options are:
   in the generated test project.
 
 ``COPY_FILE <fileName>``
-  Copy the linked executable to the given ``<fileName>``.
+  Copy the built executable or static library to the given ``<fileName>``.
 
 ``COPY_FILE_ERROR <var>``
   Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
@@ -88,12 +94,12 @@ The options are:
   given to the ``CMAKE_FLAGS`` option will be ignored.
 
 ``LINK_OPTIONS <options>...``
-  Specify link step options to pass to :command:`target_link_options` or
-  to :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
-  project, depending of the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
+  Specify link step options to pass to :command:`target_link_options` or to
+  set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
+  project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 
 ``OUTPUT_VARIABLE <var>``
-  Store the output from the build process the given variable.
+  Store the output from the build process in the given variable.
 
 ``<LANG>_STANDARD <std>``
   Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
@@ -114,7 +120,7 @@ passed to ``cmake`` to avoid this clean.  However, multiple sequential
 ``try_compile`` operations reuse this single output directory.  If you use
 ``--debug-trycompile``, you can only debug one ``try_compile`` call at a time.
 The recommended procedure is to protect all ``try_compile`` calls in your
-project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake
+project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake
 all the way through once, then delete the cache entry associated with
 the try_compile call of interest, and then re-run cmake again with
 ``--debug-trycompile``.
@@ -139,8 +145,8 @@ behavior at link time, the ``check_pie_supported()`` command from the
 :module:`CheckPIESupported` module must be called before using the
 :command:`try_compile` command.
 
-The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the
-generated project.
+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.
@@ -150,7 +156,9 @@ the type of target used for the source file signature.
 
 Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify
 variables that must be propagated into the test project.  This variable is
-meant for use only in toolchain files.
+meant for use only in toolchain files and is only honored by the
+``try_compile()`` command for the source files form, not when given a whole
+project.
 
 If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``,
 ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used,
diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst
index 137402f..d401ebe 100644
--- a/Help/command/try_run.rst
+++ b/Help/command/try_run.rst
@@ -12,8 +12,8 @@ Try Compiling and Running Source Files
 
 .. code-block:: cmake
 
-  try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
-          bindir srcfile [CMAKE_FLAGS <flags>...]
+  try_run(<runResultVar> <compileResultVar>
+          <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]
           [LINK_LIBRARIES <libs>...]
@@ -23,9 +23,9 @@ Try Compiling and Running Source Files
           [ARGS <args>...])
 
 Try compiling a ``<srcfile>``.  Returns ``TRUE`` or ``FALSE`` for success
-or failure in ``COMPILE_RESULT_VAR``.  If the compile succeeded, runs the
-executable and returns its exit code in ``RUN_RESULT_VAR``.  If the
-executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be
+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
 information on how the test project is constructed to build the source file.
 
@@ -85,10 +85,10 @@ presetting them in some CMake script file to the values the executable
 would have produced if it had been run on its actual target platform.
 These cache entries are:
 
-``<RUN_RESULT_VAR>``
+``<runResultVar>``
   Exit code if the executable were to be run on the target platform.
 
-``<RUN_RESULT_VAR>__TRYRUN_OUTPUT``
+``<runResultVar>__TRYRUN_OUTPUT``
   Output from stdout and stderr if the executable were to be run on
   the target platform.  This is created only if the
   ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used.