Document caveat of custom commands in multiple targets (#12311)

A common mistake when using custom commands is to list the output of a
command in multiple targets that may build in parallel.  Warn against
this case in the documentation and suggest a better approach.

1 files changed, 4 insertions, 0 deletions

diff --git a/Source/cmAddCustomCommandCommand.h b/Source/cmAddCustomCommandCommand.h
index 47b542c..05e7dc2 100644
--- a/Source/cmAddCustomCommandCommand.h
+++ b/Source/cmAddCustomCommandCommand.h
@@ -75,6 +75,10 @@ public:
       "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.  "
+      "Do not list the output in more than one independent target that may "
+      "build in parallel or the two instances of the rule may conflict "
+      "(instead use add_custom_target to drive the command and make the "
+      "other targets depend on that one).  "
       "If an output name is a relative path it will be interpreted "
       "relative to the build tree directory corresponding to the current "
       "source directory. "