find_package: Document <package>_FIND_* variables (#13142)

When loading a find module or package config file the find_package
command defines several variables to provide information about the
caller's request.  Previously this was documented only in the
Modules/readme.txt file which is not distributed.  Document the
behavior explicitly in the main find_package documentation.

1 files changed, 23 insertions, 0 deletions

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index ef16ce8..0a055a2 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -353,6 +353,29 @@ void cmFindPackageCommand::GenerateDocumentation()
     "variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE. See the "
     "documentation for the CMAKE_DISABLE_FIND_PACKAGE_<package> variable for "
     "more information.\n"
+    "When loading a find module or package configuration file find_package "
+    "defines variables to provide information about the call arguments "
+    "(and restores their original state before returning):\n"
+    " <package>_FIND_REQUIRED      = true if REQUIRED option was given\n"
+    " <package>_FIND_QUIETLY       = true if QUIET option was given\n"
+    " <package>_FIND_VERSION       = full requested version string\n"
+    " <package>_FIND_VERSION_MAJOR = major version if requested, else 0\n"
+    " <package>_FIND_VERSION_MINOR = minor version if requested, else 0\n"
+    " <package>_FIND_VERSION_PATCH = patch version if requested, else 0\n"
+    " <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0\n"
+    " <package>_FIND_VERSION_COUNT = number of version components, 0 to 4\n"
+    " <package>_FIND_VERSION_EXACT = true if EXACT option was given\n"
+    " <package>_FIND_COMPONENTS    = list of requested components\n"
+    " <package>_FIND_REQUIRED_<c>  = true if component <c> is required\n"
+    "                                false if component <c> is optional\n"
+    "In Module mode the loaded find module is responsible to honor the "
+    "request detailed by these variables; see the find module for details.  "
+    "In Config mode find_package handles REQUIRED, QUIET, and version "
+    "options automatically but leaves it to the package configuration file "
+    "to handle components in a way that makes sense for the package.  "
+    "The package configuration file may set <package>_FOUND to false "
+    "to tell find_package that component requirements are not satisfied."
+    "\n"
     "See the cmake_policy() command documentation for discussion of the "
     "NO_POLICY_SCOPE option."
     ;