ENH: Make find_* command search order more intuitive.

  - The CMAKE_PREFIX_PATH and similar variables have both
    environment and CMake cache versions.
  - Previously the environment value was checked before the
    cache value.
  - Now the cache value is favored because it is more specific.

Source/cmFindBase.cxx

@@ -66,18 +66,15 @@ cmFindBase::cmFindBase()
     "If NO_DEFAULT_PATH is specified, then no additional paths are "
     "added to the search. "
     "If NO_DEFAULT_PATH is not specified, the search process is as follows:\n"
-    "1. Search cmake specific environment variables.  This "
-    "can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.\n"
-    ""
+    "1. Search paths specified in cmake-specific cache variables.  "
+    "These are intended to be used on the command line with a -DVAR=value.  "
+    "This can be skipped if NO_CMAKE_PATH is passed.\n"
     "   <prefix>/XXX_SUBDIR for each <prefix> in CMAKE_PREFIX_PATH\n"
     "   CMAKE_XXX_PATH\n"
     "   CMAKE_XXX_MAC_PATH\n"
-    "2. Search cmake variables with the same names as "
-    "the cmake specific environment variables.  These "
-    "are intended to be used on the command line with a "
-    "-DVAR=value.  This can be skipped if NO_CMAKE_PATH "
-    "is passed.\n"
-    ""
+    "2. Search paths specified in cmake-specific environment variables.  "
+    "These are intended to be set in the user's shell configuration.  "
+    "This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.\n"
     "   <prefix>/XXX_SUBDIR for each <prefix> in CMAKE_PREFIX_PATH\n"
     "   CMAKE_XXX_PATH\n"
     "   CMAKE_XXX_MAC_PATH\n"
@@ -282,8 +279,8 @@ bool cmFindBase::ParseArguments(std::vector<std::string> const& argsIn)
 
 void cmFindBase::ExpandPaths()
 {
-  this->AddCMakeEnvironmentPath();
   this->AddCMakeVariablePath();
+  this->AddCMakeEnvironmentPath();
   this->AddUserHintsPath();
   this->AddSystemEnvironmentPath();
   this->AddCMakeSystemVariablePath();

Source/cmFindPackageCommand.cxx

@@ -239,16 +239,16 @@ cmFindPackageCommand::cmFindPackageCommand()
     "CMAKE_FIND_APPBUNDLE determine the order of preference "
     "as specified below.\n"
     "The set of installation prefixes is constructed using the following "
-    "steps.  If NO_DEFAULT_PATH is specified steps 1-5 are skipped.\n"
-    "1. Search cmake specific environment variables.  This "
-    "can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.\n"
+    "steps.  If NO_DEFAULT_PATH is specified all NO_* options are enabled.\n"
+    "1. Search paths specified in cmake-specific cache variables.  "
+    "These are intended to be used on the command line with a -DVAR=value.  "
+    "This can be skipped if NO_CMAKE_PATH is passed.\n"
     "   CMAKE_PREFIX_PATH\n"
     "   CMAKE_FRAMEWORK_PATH\n"
     "   CMAKE_APPBUNDLE_PATH\n"
-    "2. Search cmake variables with the same names as the cmake specific "
-    "environment variables.  These are intended to be used on the command "
-    "line with a -DVAR=value.  This can be skipped if NO_CMAKE_PATH "
-    "is passed.\n"
+    "2. Search paths specified in cmake-specific environment variables.  "
+    "These are intended to be set in the user's shell configuration.  "
+    "This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.\n"
     "   CMAKE_PREFIX_PATH\n"
     "   CMAKE_FRAMEWORK_PATH\n"
     "   CMAKE_APPBUNDLE_PATH\n"
@@ -960,8 +960,8 @@ void cmFindPackageCommand::AppendSuccessInformation()
 //----------------------------------------------------------------------------
 void cmFindPackageCommand::ComputePrefixes()
 {
-  this->AddPrefixesCMakeEnvironment();
   this->AddPrefixesCMakeVariable();
+  this->AddPrefixesCMakeEnvironment();
   this->AddPrefixesUserHints();
   this->AddPrefixesSystemEnvironment();
   this->AddPrefixesBuilds();