diff options
| author | Brad King <brad.king@kitware.com> | 2022-10-04 14:28:03 (GMT) |
|---|---|---|
| committer | Kitware Robot <kwrobot@kitware.com> | 2022-10-04 14:28:32 (GMT) |
| commit | 5e53164acf5b29fec1c34d7a6314f704c51aac9d (patch) | |
| tree | 55f5095ffc02c8781275bf90dc5b1e569465adca | |
| parent | 6755539fca2deaab112cafe25c637618653d7fc7 (diff) | |
| parent | 3801785cc3ccbce6b003ada5b32f859e6b71b543 (diff) | |
| download | CMake-5e53164acf5b29fec1c34d7a6314f704c51aac9d.zip CMake-5e53164acf5b29fec1c34d7a6314f704c51aac9d.tar.gz CMake-5e53164acf5b29fec1c34d7a6314f704c51aac9d.tar.bz2 | |
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
| -rw-r--r-- | Help/command/try_compile.rst | 6 | ||||
| -rw-r--r-- | 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 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 |