ENH: Document scope of add_custom_command outputs

This explicitly states the scope of add_custom_command rules in
the documentation of add_custom_command and add_custom_target.
See issue #8815.

2 files changed, 10 insertions, 4 deletions

diff --git a/Source/cmAddCustomCommandCommand.h b/Source/cmAddCustomCommandCommand.h
index 7829b61753..8add9708ec 100644
--- a/Source/cmAddCustomCommandCommand.h
+++ b/Source/cmAddCustomCommandCommand.h
@@ -75,9 +75,10 @@ public:
       "                     [IMPLICIT_DEPENDS <lang1> depend1 ...]\n"
       "                     [WORKING_DIRECTORY dir]\n"
       "                     [COMMENT comment] [VERBATIM] [APPEND])\n"
-      "This defines a new command that can be executed during the build "
-      "process. The outputs named should be listed as source files in the "
-      "target for which they are to be generated. "
+      "This defines a command to generate specified OUTPUT file(s).  "
+      "A target created in the same directory (CMakeLists.txt file) that "
+      "specifies any output of the custom command as a source file is given "
+      "a rule to generate the file using the command at build time.  "
       "If an output name is a relative path it will be interpreted "
       "relative to the build tree directory corresponding to the current "
       "source directory. "
@@ -151,6 +152,10 @@ public:
       "this does NOT add a file-level dependency that would cause the "
       "custom command to re-run whenever the executable is recompiled.\n"
 
+      "The DEPENDS option specifies files on which the command depends.  "
+      "If any dependency is an OUTPUT of another custom command in the "
+      "same directory (CMakeLists.txt file) CMake automatically brings the "
+      "other custom command into the target in which this command is built.  "
       "If DEPENDS specifies any target (created by an ADD_* command) "
       "a target-level dependency is created to make sure the target is "
       "built before any target using this custom command.  Additionally, "
diff --git a/Source/cmAddCustomTargetCommand.h b/Source/cmAddCustomTargetCommand.h
index 9eef4447fa..c4895c02fe 100644
--- a/Source/cmAddCustomTargetCommand.h
+++ b/Source/cmAddCustomTargetCommand.h
@@ -87,7 +87,8 @@ public:
       "If COMMENT is set, the value will be displayed as a "
       "message before the commands are executed at build time. "
       "Dependencies listed with the DEPENDS argument may reference files "
-      "and outputs of custom commands created with ADD_CUSTOM_COMMAND.\n"
+      "and outputs of custom commands created with add_custom_command() in "
+      "the same directory (CMakeLists.txt file).\n"
       "If VERBATIM is given then all the arguments to the commands will be "
       "passed exactly as specified no matter the build tool used. "
       "Note that one level of escapes is still used by the CMake language "