Merge topic 'improve-try_compile-debug-documentation'

3801785cc3 Help: Improve try_compile debug documentation

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: alcroito <alexandru.croitor@qt.io>
Merge-request: !7735

2 files changed, 16 insertions, 12 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 9d587c1..b5fad77 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -102,9 +102,9 @@ 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
+CMake automatically generates, for each ``try_compile`` operation, a
+unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
+with an unspecified name.  These directories are 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.
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index c05f3c8..868dac4 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -278,15 +278,19 @@ Options
 
 .. option:: --debug-trycompile
 
- Do not delete the :command:`try_compile` build tree.
- Only useful on one :command:`try_compile` at a time.
-
- Do not delete the files and directories created for :command:`try_compile`
- calls.  This is useful in debugging failed try_compiles.  It may
- however change the results of the try-compiles as old junk from a
- previous try-compile may cause a different test to either pass or
- fail incorrectly.  This option is best used for one try-compile at a
- time, and only when debugging.
+ Do not delete the the files and directories created for
+ :command:`try_compile` / :command:`try_run` calls.
+ This is useful in debugging failed checks.
+
+ Note that some uses of :command:`try_compile` may use the same build tree,
+ which will limit the usefulness of this option if a project executes more
+ than one :command:`try_compile`.  For example, such uses may change results
+ as artifacts from a previous try-compile may cause a different test to either
+ pass or fail incorrectly.  This option is best used only when debugging.
+
+ (With respect to the preceding, the :command:`try_run` command
+ is effectively a :command:`try_compile`.  Any combination of the two
+ is subject to the potential issues described.)
 
 .. option:: --debug-output