Prefer files from CMAKE_ROOT when including from CMAKE_ROOT

This patch makes include() and find_package() prefer cmake files
located in CMAKE_ROOT over those in CMAKE_MODULE_PATH.
This makes sure that the including file gets that file included
which it expects, i.e. the one from cmake with which it was tested.
It only changes behaviour when such an included file exists both
in CMAKE_MODULE_PATH and in CMAKE_ROOT.
This comes together with a new policy CMP0017, with default
behaviour it behaves as it always did, but warns.
With NEW behaviour it includes the file from CMAKE_ROOT
instead from CMAKE_MODULE_PATH. This fixes (if CMP0017 is set)
building KDE 4.5 with cmake >= 2.8.3.
Also a basic test for this policy in included.

1 files changed, 6 insertions, 1 deletions

diff --git a/Source/cmIncludeCommand.h b/Source/cmIncludeCommand.h
index 8704750..a6d43ba 100644
--- a/Source/cmIncludeCommand.h
+++ b/Source/cmIncludeCommand.h
@@ -73,7 +73,12 @@ public:
       "the variable will be set to the full filename which "
       "has been included or NOTFOUND if it failed.\n"
       "If a module is specified instead of a file, the file with name "
-      "<modulename>.cmake is searched in the CMAKE_MODULE_PATH."
+      "<modulename>.cmake is searched first in CMAKE_MODULE_PATH, then in the "
+      "CMake module directory. There is one exception to this: if the file "
+      "which calls include() is located itself in the CMake module directory, "
+      "then first the CMake module directory is searched and "
+      "CMAKE_MODULE_PATH afterwards. This behaviour is controlled by policy "
+      "CMP0017."
       "\n"
       "See the cmake_policy() command documentation for discussion of the "
       "NO_POLICY_SCOPE option."