ENH: Added optional component list to the REQUIRED option of the FIND_PACKAGE command. This addresses bug#2771.

Modules/readme.txt

@@ -55,3 +55,21 @@ To have a .cmake file in this directory NOT show up in the
 modules documentation, you should start the file with a blank
 line.
 
+A FindXXX.cmake module will typically be loaded by the command
+
+  FIND_PACKAGE(XXX [QUIET] [REQUIRED [components...]])
+
+If the QUIET option is given to the command it will set the variable
+XXX_FIND_QUIETLY to true before loading the FindXXX.cmake module.  If
+this variable is set the module should not complain about not being
+able to find the package and should never issue a FATAL_ERROR.  If the
+REQUIRED option is given to the command it will set the variable
+XXX_FIND_REQUIRED to true before loading the FindXXX.cmake module.  If
+this variable is set the module should issue a FATAL_ERROR if the
+package cannot be found.  For each package-specific component, say
+YYY, listed after the REQUIRED option a variable XXX_FIND_REQUIRED_YYY
+to true.  This can be used by the FindXXX.cmake module to determine
+which sub-components of the package must be found.  If neither the
+QUIET nor REQUIRED options are given then the FindXXX.cmake module
+should look for the package and complain without error if the module
+is not found.

Source/cmFindPackageCommand.cxx

@@ -75,6 +75,11 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args)
       else if(args[i] == "REQUIRED")
         {
         required = true;
+        while (++i < args.size() && args[i] != "QUIET")
+          {
+          std::string req_var = Name + "_FIND_REQUIRED_" + args[i];
+          m_Makefile->AddDefinition(req_var.c_str(), "1");
+          }
         }
       else
         {

Source/cmFindPackageCommand.h

@@ -65,7 +65,8 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  FIND_PACKAGE(<name> [major.minor] [QUIET] [REQUIRED])\n"
+      "  FIND_PACKAGE(<name> [major.minor] [QUIET]\n"
+      "               [REQUIRED [componets...]])\n"
       "Finds and loads settings from an external project.  <name>_FOUND will "
       "be set to indicate whether the package was found.  Settings that "
       "can be used when <name>_FOUND is true are package-specific.  The "
@@ -83,7 +84,9 @@ public:
       "argument is specified.  If <name>_DIR has been set to a directory "
       "not containing a \"<name>Config.cmake\" file, an error is always "
       "generated.  If REQUIRED is specified and the package is not found, "
-      "a FATAL_ERROR is generated and the configure step stops executing.";
+      "a FATAL_ERROR is generated and the configure step stops executing."
+      "  A package-specific list of components may be listed after the "
+      "REQUIRED option.";
     }
   
   cmTypeMacro(cmFindPackageCommand, cmCommand);