Clarify CMAKE_USER_MAKE_RULES_OVERRIDE documentation (#11724)

This variable was introduced to help authors override CMake's default
platform information before any of it is cached.  State this clearly in
the documentation.  Explicitly discourage use for other purposes.

1 files changed, 27 insertions, 14 deletions

diff --git a/Source/cmDocumentVariables.cxx b/Source/cmDocumentVariables.cxx
index 2ed959f..40d416f 100644
--- a/Source/cmDocumentVariables.cxx
+++ b/Source/cmDocumentVariables.cxx
@@ -625,13 +625,29 @@ void cmDocumentVariables::DefineVariables(cmake* cm)
 
   cm->DefineProperty
     ("CMAKE_USER_MAKE_RULES_OVERRIDE", cmProperty::VARIABLE,
-     "Specify a file that can change the build rule variables.",
-     "If this variable is set, it should to point to a "
-     "CMakeLists.txt file that will be read in by CMake "
-     "after all the system settings have been set, but "
-     "before they have been used.  This would allow you "
-     "to override any variables that need to be changed "
-     "for some special project. ",false,
+     "Specify a CMake file that overrides platform information.",
+     "CMake loads the specified file while enabling support for each "
+     "language from either the project() or enable_language() commands.  "
+     "It is loaded after CMake's builtin compiler and platform information "
+     "modules have been loaded but before the information is used.  "
+     "The file may set platform information variables to override CMake's "
+     "defaults."
+     "\n"
+     "This feature is intended for use only in overriding information "
+     "variables that must be set before CMake builds its first test "
+     "project to check that the compiler for a language works.  "
+     "It should not be used to load a file in cases that a normal include() "
+     "will work.  "
+     "Use it only as a last resort for behavior that cannot be achieved "
+     "any other way.  "
+     "For example, one may set CMAKE_C_FLAGS_INIT to change the default "
+     "value used to initialize CMAKE_C_FLAGS before it is cached.  "
+     "The override file should NOT be used to set anything that could "
+     "be set after languages are enabled, such as variables like "
+     "CMAKE_RUNTIME_OUTPUT_DIRECTORY that affect the placement of binaries.  "
+     "Information set in the file will be used for try_compile and try_run "
+     "builds too."
+     ,false,
      "Variables That Change Behavior");
   
   cm->DefineProperty
@@ -1059,13 +1075,10 @@ void cmDocumentVariables::DefineVariables(cmake* cm)
 
   cm->DefineProperty
     ("CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>", cmProperty::VARIABLE,
-     "Specify a file that can change the build rule variables.",
-     "If this variable is set, it should to point to a "
-     "CMakeLists.txt file that will be read in by CMake "
-     "after all the system settings have been set, but "
-     "before they have been used.  This would allow you "
-     "to override any variables that need to be changed "
-     "for some language. ",false,
+     "Specify a CMake file that overrides platform information for <LANG>.",
+     "This is a language-specific version of "
+     "CMAKE_USER_MAKE_RULES_OVERRIDE loaded only when enabling "
+     "language <LANG>.",false,
      "Variables for Languages");
 
   cm->DefineProperty