mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-12-31 19:00:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Note ways CMAKE_..._FIND_PACKAGE_... vars can break projects

Browse Source 
Issue: #23779
This commit is contained in:
Craig Scott
2023-11-07 21:37:23 +08:00
parent 768690ee9a
commit 6341267780
2 changed files with 41 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
View File

@@ -15,4 +15,14 @@ variables which have been stored in the cache will still be there. In
that case it is recommended to remove the cache variables for this
package from the cache using the cache editor or :option:`cmake -U`.
Note that this variable can lead to inconsistent results within the project.
Consider the case where a dependency is requested via :command:`find_package`
from two different places within the project. If the first call does not
have the ``REQUIRED`` keyword, it will not find the dependency when
``CMAKE_DISABLE_FIND_PACKAGE_<PackageName>`` is set to true for that
dependency. The project will proceed under the assumption that the dependency
isn't available. If the second call elsewhere in the project *does* have the
``REQUIRED`` keyword, it can succeed. Two different parts of the same project
have then seen opposite results for the same dependency.
See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable.

31
Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst
View File

@@ -11,4 +11,35 @@ turned into ``REQUIRED`` by setting the variable
This can be used to assert assumptions about build environment and to
ensure the build will fail early if they do not hold.
Note that setting this variable to true breaks some commonly used patterns.
Multiple calls to :command:`find_package` are sometimes used to obtain a
different search order to the default.
For example, projects can force checking a known path for a particular
package first before searching any of the other default search paths:
.. code:: cmake
find_package(something PATHS /some/local/path NO_DEFAULT_PATH)
find_package(something)
In the above, the first call looks for the ``something`` package in a specific
directory. If ``CMAKE_REQUIRE_FIND_PACKAGE_something`` is set to true, then
this first call must succeed, otherwise a fatal error occurs. The second call
never gets a chance to provide a fall-back to using the default search
locations.
A similar pattern is used even by some of CMake's own Find modules to search
for a config package first:
.. code:: cmake
find_package(something CONFIG QUIET)
if(NOT something_FOUND)
# Fall back to searching using typical Find module logic...
endif()
Again, if ``CMAKE_REQUIRE_FIND_PACKAGE_something`` is true, the first call
must succeed. It effectively means a config package must be found for the
dependency, and the Find module logic is never used.
See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable.