From 3801785cc3ccbce6b003ada5b32f859e6b71b543 Mon Sep 17 00:00:00 2001
From: Matthew Woehlke <matthew.woehlke@kitware.com>
Date: Mon, 3 Oct 2022 11:44:58 -0400
Subject: Help: Improve try_compile debug documentation
Update the --debug-trycompile documentation to account for recent
changes to try_compile. Mention where in the build tree to find
artifacts when using said option.
---
Help/command/try_compile.rst | 6 +++---
Help/manual/cmake.1.rst | 22 +++++++++++++---------
2 files changed, 16 insertions(+), 12 deletions(-)
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index 6cb4f99..35ffe92 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
--
cgit v0.12