Merge topic 'doc-find_package-variables'

5ed93db find_package: Fix components signature documentation (#13142)
6c12e82 find_package: Document <package>_FIND_* variables (#13142)

1 files changed, 26 insertions, 3 deletions

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index ef16ce8..4f9ba7e 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -89,7 +89,7 @@ void cmFindPackageCommand::GenerateDocumentation()
                                "FIND_XXX", "find_package");
   this->CommandDocumentation =
     "  find_package(<package> [version] [EXACT] [QUIET] [MODULE]\n"
-    "               [[REQUIRED|COMPONENTS] [components...]]\n"
+    "               [REQUIRED] [[COMPONENTS] [components...]]\n"
     "               [OPTIONAL_COMPONENTS components...]\n"
     "               [NO_POLICY_SCOPE])\n"
     "Finds and loads settings from an external project.  "
@@ -102,7 +102,7 @@ void cmFindPackageCommand::GenerateDocumentation()
     "package cannot be found."
     "\n"
     "A package-specific list of required components may be listed after the "
-    "COMPONENTS option or directly after the REQUIRED option.  "
+    "COMPONENTS option (or after the REQUIRED option if present).  "
     "Additional optional components may be listed after OPTIONAL_COMPONENTS.  "
     "Available components and their influence on whether a package is "
     "considered to be found are defined by the target package."
@@ -136,7 +136,7 @@ void cmFindPackageCommand::GenerateDocumentation()
     "proceeds to Config mode.\n"
     "The complete Config mode command signature is:\n"
     "  find_package(<package> [version] [EXACT] [QUIET]\n"
-    "               [[REQUIRED|COMPONENTS] [components...]]\n"
+    "               [REQUIRED] [[COMPONENTS] [components...]]\n"
     "               [CONFIG|NO_MODULE]\n"
     "               [NO_POLICY_SCOPE]\n"
     "               [NAMES name1 [name2 ...]]\n"
@@ -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."
     ;