From 41f4e1c45761c107a0a59cf7c16d34ef569301fc Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sun, 14 Apr 2024 18:07:41 +1000 Subject: CMakePackageConfigHelpers: Document PACKAGE_PREFIX_DIR for public use This variable has long been provided by `configure_package_config_file` in the `@PACKAGE_INIT@` part of the package configuration file it generates. Although not publicly documented, projects have come to use it. Now that we preserve the value across nested `find_package` calls, it has a stable meaning. Issue: #25827 --- Modules/CMakePackageConfigHelpers.cmake | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake index 9fa30b6..7d038d4 100644 --- a/Modules/CMakePackageConfigHelpers.cmake +++ b/Modules/CMakePackageConfigHelpers.cmake @@ -76,6 +76,23 @@ always relative to the installed location of the package. This works both for relative and also for absolute locations. For absolute locations, it works only if the absolute location is a subdirectory of ``INSTALL_PREFIX``. +.. versionadded:: 3.30 + The variable ``PACKAGE_PREFIX_DIR`` will always be defined after the + ``@PACKAGE_INIT@`` line. It will hold the value of the base install + location. In general, variables defined via the ``PATH_VARS`` mechanism + should be used instead, but ``PACKAGE_PREFIX_DIR`` can be used for those + cases not easily handled by ``PATH_VARS``, such as for files installed + directly to the base install location rather than a subdirectory of it. + + .. note:: + When consumers of the generated file use CMake 3.29 or older, the value + of ``PACKAGE_PREFIX_DIR`` can be changed by a call to + :command:`find_dependency` or :command:`find_package`. + If a project relies on ``PACKAGE_PREFIX_DIR``, it is the project's + responsibility to ensure that the value of ``PACKAGE_PREFIX_DIR`` is + preserved across any such calls, or any other calls which might include + another file generated by ``configure_package_config_file()``. + .. versionadded:: 3.1 If the ``INSTALL_PREFIX`` argument is passed, this is used as the base path to calculate all the relative paths. The ```` argument must be an absolute -- cgit v0.12