Merge topic 'outdir-CMAKE_USER_MAKE_RULES_OVERRIDE'

5792d3a Always place try_compile executables predictably (#11724)
a5300f1 Clarify CMAKE_USER_MAKE_RULES_OVERRIDE documentation (#11724)

Source/cmCoreTryCompile.cxx

@@ -283,6 +283,10 @@ int cmCoreTryCompile::TryCompileCode(std::vector<std::string> const& argv)
       cmakeFlags.push_back(flag);
       }
 
+    /* Put the executable at a known location (for COPY_FILE).  */
+    fprintf(fout, "SET(CMAKE_RUNTIME_OUTPUT_DIRECTORY \"%s\")\n",
+            this->BinaryDirectory.c_str());
+    /* Create the actual executable.  */
     fprintf(fout, "ADD_EXECUTABLE(cmTryCompileExec \"%s\")\n",source.c_str());
     fprintf(fout, 
             "TARGET_LINK_LIBRARIES(cmTryCompileExec ${LINK_LIBRARIES})\n");

Source/cmDocumentVariables.cxx

@@ -696,13 +696,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
@@ -1138,13 +1154,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