Help: Revise try_compile and try_run documentation (#15358)

Rewrite the documentation using better reStructuredText markup
constructs.  Clarify interaction of options like LINK_LIBRARIES and
CMAKE_FLAGS.

1 files changed, 77 insertions, 49 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 224c67b..9a70885 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -1,72 +1,100 @@
 try_compile
 -----------
 
+.. only:: html
+
+   .. contents::
+
 Try building some code.
 
+Try Compiling Whole Projects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 ::
 
   try_compile(RESULT_VAR <bindir> <srcdir>
-              <projectName> [targetName] [CMAKE_FLAGS flags...]
+              <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
 
-Try building a project.  In this form, srcdir should contain a
-complete CMake project with a CMakeLists.txt file and all sources.
-The bindir and srcdir will not be deleted after this command is run.
-Specify targetName to build a specific target instead of the 'all' or
-'ALL_BUILD' target.
+Try building a project.  The success or failure of the ``try_compile``,
+i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``.
+
+In this form, ``<srcdir>`` should contain a complete CMake project with a
+``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
+will not be deleted after this command is run.  Specify ``<targetName>`` to
+build a specific target instead of the ``all`` or ``ALL_BUILD`` target.  See
+below for the meaning of other options.
+
+Try Compiling Source Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
   try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
-              [CMAKE_FLAGS flags...]
-              [COMPILE_DEFINITIONS flags...]
-              [LINK_LIBRARIES libs...]
+              [CMAKE_FLAGS <flags>...]
+              [COMPILE_DEFINITIONS <defs>...]
+              [LINK_LIBRARIES <libs>...]
               [OUTPUT_VARIABLE <var>]
               [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
 
-Try building an executable from one or more source files.  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.  Specify COPY_FILE to get a copy
-of the linked executable at the given fileName and optionally
-COPY_FILE_ERROR to capture any error.
-
-In this version all files in bindir/CMakeFiles/CMakeTmp will be
-cleaned automatically.  For debugging, --debug-trycompile can be
-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
-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.
-
-Some extra flags that can be included are, INCLUDE_DIRECTORIES,
-LINK_DIRECTORIES, and LINK_LIBRARIES.  COMPILE_DEFINITIONS are
--Ddefinition that will be passed to the compile line.
-
-The srcfile signature also accepts a LINK_LIBRARIES argument which may
-contain a list of libraries or IMPORTED targets which will be linked
-to in the generated project.  If LINK_LIBRARIES is specified as a
-parameter to try_compile, then any LINK_LIBRARIES passed as
-CMAKE_FLAGS will be ignored.
+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_compile creates a CMakeList.txt file on the fly that looks like
-this:
+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::
 
-::
-
-  add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
+  add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
   include_directories(${INCLUDE_DIRECTORIES})
   link_directories(${LINK_DIRECTORIES})
-  add_executable(cmTryCompileExec sources)
+  add_executable(cmTryCompileExec <srcfile>...)
   target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
 
-In both versions of the command, if OUTPUT_VARIABLE is specified, then
-the output from the build process is stored in the given variable.
-The success or failure of the try_compile, i.e.  TRUE or FALSE
-respectively, is returned in RESULT_VAR.  CMAKE_FLAGS can be used to
-pass -DVAR:TYPE=VALUE flags to the cmake that is run during the build.
-Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
-configuration.
+The options are:
+
+``CMAKE_FLAGS <flags>...``
+  Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
+  the ``cmake`` command-line used to drive the test build.
+  The above example shows how values for variables
+  ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
+  are used.
+
+``COMPILE_DEFINITIONS <defs>...``
+  Specify ``-Ddefinition`` arguments to pass to ``add_definitions``
+  in the generated test project.
+
+``COPY_FILE <fileName>``
+  Copy the linked executable to the given ``<fileName>``.
+
+``COPY_FILE_ERROR <var>``
+  Use after ``COPY_FILE`` to capture into variable ``<var>`` any error
+  message encountered while trying to copy the file.
+
+``LINK_LIBRARIES <libs>...``
+  Specify libraries to be linked in the generated project.
+  The list of libraries may refer to system libraries and to
+  :ref:`Imported Targets <Imported Targets>` from the calling project.
+
+  If this option is specified, any ``-DLINK_LIBRARIES=...`` value
+  given to the ``CMAKE_FLAGS`` option will be ignored.
+
+``OUTPUT_VARIABLE <var>``
+  Store the output from the build process the given variable.
+
+In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
+cleaned automatically.  For debugging, ``--debug-trycompile`` can be
+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
+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``.
+
+Other Behavior Settings
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
+a build configuration.