Merge topic 'try_compile-unique-bindir'

aa9220d3a0 try_compile: Add keyword-dispatched signature
d1befe5515 cmSystemTools: Add MakeTempDirectory

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Acked-by: Matthew Woehlke <matthew.woehlke@kitware.com>
Merge-request: !7579

2 files changed, 79 insertions, 46 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index e03ab80..73dd9d3 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -41,7 +41,7 @@ Try Compiling Source Files
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
+  try_compile(<resultVar> SOURCES <srcfile...>
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]
@@ -53,6 +53,8 @@ Try Compiling Source Files
               [<LANG>_EXTENSIONS <bool>]
               )
 
+.. versionadded:: 3.25
+
 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
@@ -76,6 +78,39 @@ contain something like the following:
   target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
   target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
 
+CMake will automatically generate a unique directory for each ``try_compile``
+operation in an unspecified location within the project's binary directory.
+These directories will be cleaned automatically unless
+:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
+Such directories from previous runs are also unconditionally cleaned at the
+beginning of any ``cmake`` execution.
+
+This command also supports an alternate signature
+which was present in older versions of CMake:
+
+.. code-block:: cmake
+
+  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
+              [CMAKE_FLAGS <flags>...]
+              [COMPILE_DEFINITIONS <defs>...]
+              [LINK_OPTIONS <options>...]
+              [LINK_LIBRARIES <libs>...]
+              [OUTPUT_VARIABLE <var>]
+              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+              [<LANG>_STANDARD <std>]
+              [<LANG>_STANDARD_REQUIRED <bool>]
+              [<LANG>_EXTENSIONS <bool>]
+              )
+
+In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
+its operation, and all such files will be cleaned automatically.
+For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
+passed to ``cmake`` to avoid this clean.  However, multiple sequential
+``try_compile`` operations, if given the same ``<bindir>``, will reuse this
+single output directory, such that you can only debug one such ``try_compile``
+call at a time.  Use of the newer signature is recommended to simplify
+debugging of multiple ``try_compile`` operations.
+
 The options are:
 
 ``CMAKE_FLAGS <flags>...``
@@ -136,18 +171,6 @@ The options are:
   :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
   or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
 
-In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
-cleaned automatically.  For debugging,
-:option:`--debug-trycompile <cmake --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
-:option:`--debug-trycompile <cmake --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 <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 :option:`--debug-trycompile <cmake --debug-trycompile>`.
-
 Other Behavior Settings
 ^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst
index 938869b..1dc2355 100644
--- a/Help/command/try_run.rst
+++ b/Help/command/try_run.rst
@@ -12,62 +12,68 @@ Try Compiling and Running Source Files
 
 .. code-block:: cmake
 
-  try_run(<runResultVar> <compileResultVar>
-          <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
+  try_run(<runResultVar> <compileResultVar> SOURCES <srcfile...>
+          [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]
           [LINK_LIBRARIES <libs>...]
           [COMPILE_OUTPUT_VARIABLE <var>]
+          [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+          [<LANG>_STANDARD <std>]
+          [<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>...])
+          [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
-information on how the test project is constructed to build the source file.
+documentation of options common to both commands, and for information on how
+the test project is constructed to build the source file.
 
-The options are:
+This command also supports an alternate signature
+which was present in older versions of CMake:
 
-``CMAKE_FLAGS <flags>...``
-  Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
-  to the :manual:`cmake(1)` command-line used to drive the test build.
-  The example in :command:`try_compile` shows how values for variables
-  ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
-  are used.
+.. code-block:: cmake
+
+  try_run(<runResultVar> <compileResultVar>
+          <bindir> <srcfile|SOURCES srcfile...>
+          [CMAKE_FLAGS <flags>...]
+          [COMPILE_DEFINITIONS <defs>...]
+          [LINK_OPTIONS <options>...]
+          [LINK_LIBRARIES <libs>...]
+          [COMPILE_OUTPUT_VARIABLE <var>]
+          [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+          [<LANG>_STANDARD <std>]
+          [<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>...]
+          )
 
-``COMPILE_DEFINITIONS <defs>...``
-  Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
-  in the generated test project.
+The options specific to ``try_run`` are:
 
 ``COMPILE_OUTPUT_VARIABLE <var>``
   Report the compile step build output in a given variable.
 
-``LINK_LIBRARIES <libs>...``
-  .. versionadded:: 3.2
-
-  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.
-
-``LINK_OPTIONS <options>...``
-  .. versionadded:: 3.14
-
-  Specify link step options to pass to :command:`target_link_options` in the
-  generated project.
-
 ``OUTPUT_VARIABLE <var>``
   Report the compile build output and the output from running the executable
-  in the given variable.  This option exists for legacy reasons.  Prefer
-  ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
+  in the given variable.  This option exists for legacy reasons and is only
+  supported by the old ``try_run`` signature.
+  Prefer ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
 
 ``RUN_OUTPUT_VARIABLE <var>``
   Report the output from running the executable in a given variable.
@@ -86,7 +92,11 @@ The options are:
   .. versionadded:: 3.20
 
   Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is
-  specified, the executable will run in ``<bindir>``.
+  specified, the executable will run in ``<bindir>`` or the current build
+  directory.
+
+``ARGS <args>...``
+  Additional arguments to pass to the executable when running it.
 
 Other Behavior Settings
 ^^^^^^^^^^^^^^^^^^^^^^^