Merge topic 'FetchContent_find_package_integration'

29e31e2825 Packages: Integrate FetchContent and find_package()

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Acked-by: huangqinjin <huangqinjin@gmail.com>
Merge-request: !5688

1 files changed, 27 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
new file mode 100644
index 0000000000..fa414e4044
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst
@@ -0,0 +1,27 @@
+CMAKE_FIND_PACKAGE_REDIRECTS_DIR
+--------------------------------
+
+.. versionadded:: 3.24
+
+This read-only variable specifies a directory that the :command:`find_package`
+command will check first before searching anywhere else for a module or config
+package file.  A config package file in this directory will always be found in
+preference to any other Find module file or config package file.
+
+The primary purpose of this variable is to facilitate integration between
+:command:`find_package` and :command:`FetchContent_MakeAvailable`.  The latter
+command may create files in the ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` directory
+when it populates a dependency.  This allows subsequent calls to
+:command:`find_package` for the same dependency to re-use the populated
+contents instead of trying to satisfy the dependency from somewhere external
+to the build.  Projects may also want to write files into this directory in
+some situations (see :ref:`FetchContent-find_package-integration` for examples).
+
+The directory that ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` points to will always
+be erased and recreated empty at the start of every CMake run.  Any files
+written into this directory during the CMake run will be lost the next time
+CMake configures the project.
+
+``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode.
+It is not set when CMake is run in script mode
+(i.e. :manual:`cmake -P ... <cmake(1)>`).