BUG: Fix documentation of CMAKE_CFG_INTDIR

The documentation of this variable was out-dated and misleading.
See issue #9219.

1 files changed, 36 insertions, 21 deletions

diff --git a/Source/cmDocumentVariables.cxx b/Source/cmDocumentVariables.cxx
index bcc67d6..2af0ad3 100644
--- a/Source/cmDocumentVariables.cxx
+++ b/Source/cmDocumentVariables.cxx
@@ -120,27 +120,42 @@ void cmDocumentVariables::DefineVariables(cmake* cm)
   
   cm->DefineProperty
     ("CMAKE_CFG_INTDIR", cmProperty::VARIABLE,
-     "Build time configuration directory for project.",
-     "This is a variable that is used to provide developers"
-     " access to the intermediate directory used by Visual "
-     "Studio IDE projects.   For example, if building "
-     "Debug all executables and libraries end up in a "
-     "Debug directory.   On UNIX systems this variable "
-     "is set to \".\".  However, with Visual Studio this "
-     "variable is set to $(IntDir).   $(IntDir) is expanded "
-     "by the IDE only.  So this variable should only be "
-     "used in custom commands that will be run during "
-     "the build process.   This variable should not be "
-     "used directly in a CMake command.  CMake has no "
-     "way of knowing if Debug or Release will be picked "
-     "by the IDE for a build type. If a program needs to "
-     "know the directory it was built in, it can use "
-     "CMAKE_INTDIR. CMAKE_INTDIR is a C/C++ preprocessor "
-     "macro that is defined on the command line of the "
-     "compiler.   If it has a value, it will be the "
-     "intermediate directory used to build the file.   "
-     "This way an executable or a library can find files "
-     "that are located in the build directory.",false,
+     "Build-time reference to per-configuration output subdirectory.",
+     "For native build systems supporting multiple configurations "
+     "in the build tree (such as Visual Studio and Xcode), "
+     "the value is a reference to a build-time variable specifying "
+     "the name of the per-configuration output subdirectory.  "
+     "On Makefile generators this evaluates to \".\" because there "
+     "is only one configuration in a build tree.  "
+     "Example values:\n"
+     "  $(IntDir)        = Visual Studio 6\n"
+     "  $(OutDir)        = Visual Studio 7, 8, 9\n"
+     "  $(Configuration) = Visual Studio 10\n"
+     "  $(CONFIGURATION) = Xcode\n"
+     "  .                = Make-based tools\n"
+     "Since these values are evaluated by the native build system, this "
+     "variable is suitable only for use in command lines that will be "
+     "evaluated at build time.  "
+     "Example of intended usage:\n"
+     "  add_executable(mytool mytool.c)\n"
+     "  add_custom_command(\n"
+     "    OUTPUT out.txt\n"
+     "    COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool\n"
+     "            ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt\n"
+     "    DEPENDS mytool in.txt\n"
+     "    )\n"
+     "  add_custom_target(drive ALL DEPENDS out.txt)\n"
+     "Note that CMAKE_CFG_INTDIR is no longer necessary for this purpose "
+     "but has been left for compatibility with existing projects.  "
+     "Instead add_custom_command() recognizes executable target names in "
+     "its COMMAND option, so "
+     "\"${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool\" can be "
+     "replaced by just \"mytool\"."
+     "\n"
+     "This variable is read-only.  Setting it is undefined behavior.  "
+     "In multi-configuration build systems the value of this variable "
+     "is passed as the value of preprocessor symbol \"CMAKE_INTDIR\" to "
+     "the compilation of all source files.",false,
      "Variables that Provide Information");
   
   cm->DefineProperty