Warn in find(GLOB) docs about bad use case (#11617)

The first instinct of a lot of users is to use file(GLOB) to assemble
lists of sources.  Add a warning to the help text stating that it should
not be used for this purpose and briefly explain why.

Suggested-By: Ryan Pavlik

1 files changed, 6 insertions, 1 deletions

diff --git a/Source/cmFileCommand.h b/Source/cmFileCommand.h
index e771092..b11dcde 100644
--- a/Source/cmFileCommand.h
+++ b/Source/cmFileCommand.h
@@ -116,7 +116,12 @@ public:
       "expressions and store it into the variable. Globbing expressions "
       "are similar to regular expressions, but much simpler. If RELATIVE "
       "flag is specified for an expression, the results will be returned "
-      "as a relative path to the given path.\n"
+      "as a relative path to the given path.  "
+      "(We do not recommend using GLOB to collect a list of source files "
+      "from your source tree.  If no CMakeLists.txt file changes when a "
+      "source is added or removed then the generated build system cannot "
+      "know when to ask CMake to regenerate.)"
+      "\n"
       "Examples of globbing expressions include:\n"
       "   *.cxx      - match all files with extension cxx\n"
       "   *.vt?      - match all files with extension vta,...,vtz\n"