ENH: Mention cycles in target_link_libraries docs

This documents CMake's support for cycles in the dependency graph of
STATIC libraries.

1 files changed, 22 insertions, 0 deletions

diff --git a/Source/cmTargetLinkLibrariesCommand.h b/Source/cmTargetLinkLibrariesCommand.h
index d4c0ec2c2f..ed0d904275 100644
--- a/Source/cmTargetLinkLibrariesCommand.h
+++ b/Source/cmTargetLinkLibrariesCommand.h
@@ -107,6 +107,28 @@ public:
       "the LINK_INTERFACE_LIBRARIES property.  "
       "Libraries specified as \"general\" (or without any keyword) are "
       "treated as if specified for both \"debug\" and \"optimized\"."
+      "\n"
+      "The library dependency graph is normally acyclic (a DAG), but in the "
+      "case of mutually-dependent STATIC libraries CMake allows the graph "
+      "to contain cycles (strongly connected components).  "
+      "When another target links to one of the libraries CMake repeats "
+      "the entire connected component.  "
+      "For example, the code\n"
+      "  add_library(A STATIC a.c)\n"
+      "  add_library(B STATIC b.c)\n"
+      "  target_link_libraries(A B)\n"
+      "  target_link_libraries(B A)\n"
+      "  add_executable(main main.c)\n"
+      "  target_link_libraries(main A)\n"
+      "links 'main' to 'A B A B'.  "
+      "("
+      "While one repetition is usually sufficient, pathological object "
+      "file and symbol arrangements can require more.  "
+      "One may handle such cases by manually repeating the component in "
+      "the last target_link_libraries call.  "
+      "However, if two archives are really so interdependent they should "
+      "probably be combined into a single archive."
+      ")"
       ;
     }