echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Improve try_compile debug documentation

Browse Source 
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.
This commit is contained in:
Matthew Woehlke 2022-10-03 11:44:58 -04:00
parent cadcb6a5f0
commit 3801785cc3
2 changed files with 15 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Help/command/try_compile.rst
View File

@ -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.

20
Help/manual/cmake.1.rst
View File

@ -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 the files and directories created for
:command:`try_compile` / :command:`try_run` calls.
This is useful in debugging failed checks.
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.
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