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

Issue: #23779

2 files changed, 41 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
index 58818f4..b375b77 100644
--- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
+++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst
@@ -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.
diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst
index 893f1ae..52bf30a 100644
--- a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst
+++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst
@@ -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.