From 6c12e820b84a1a509dced0efe8118eca2a141473 Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Wed, 18 Apr 2012 08:57:29 -0400
Subject: [PATCH 1/2] 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.
---
 Source/cmFindPackageCommand.cxx | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index ef16ce85f..0a055a293 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."
     ;

From 5ed93db4cf6408c245d58a1bfaa63048bc54fc00 Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Wed, 18 Apr 2012 13:28:45 -0400
Subject: [PATCH 2/2] find_package: Fix components signature documentation
 (#13142)

Update the signature notation to show that "REQUIRED COMPONENTS ..." is
allowed and that REQUIRED is an option on its own.
---
 Source/cmFindPackageCommand.cxx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index 0a055a293..4f9ba7eb2 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"