Graphviz: added test suite, fixes, enhancements

* Added a fairly comprehensive test suite
* Separated the graph traversal logic from the Graphviz generation
  code by introducing a new class, cmLinkItemsGraphVisitor{.h,cxx}
* Made the graph traversal logic less ad-hoc by using existing
  methods in the GlobalGenerator; this fixed a few bugs
* Added support for new target types: custom targets, object
  and unknown libraries
* Improved support for ALIAS libraries by showing the alias(es)
  in the graph
* Introduced new flags to control those new libraries (consistent
  with existing flags)
* Updated the documentation
* Removed useless setting to set graph type in dot file
* Improved the node/edge shapes (nicer, more consistent)
* Added a legend to the graph
* Some refactoring and cleanup of the Graphviz generation code
* Added test and fix for issue 19746

1 files changed, 86 insertions, 60 deletions

diff --git a/Modules/CMakeGraphVizOptions.cmake b/Modules/CMakeGraphVizOptions.cmake
index 1911e73..be4a3be 100644
--- a/Modules/CMakeGraphVizOptions.cmake
+++ b/Modules/CMakeGraphVizOptions.cmake
@@ -5,119 +5,145 @@
 CMakeGraphVizOptions
 --------------------
 
-The builtin graphviz support of CMake.
+The builtin Graphviz support of CMake.
 
-Variables specific to the graphviz support
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Generating Graphviz files
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-CMake
-can generate `graphviz <http://www.graphviz.org/>`_ files, showing the dependencies between the
-targets in a project and also external libraries which are linked
-against.  When CMake is run with the ``--graphviz=foo.dot`` option, it will
-produce:
+CMake can generate `Graphviz <https://www.graphviz.org/>`_ files showing the
+dependencies between the targets in a project, as well as external libraries
+which are linked against.
 
-* a ``foo.dot`` file showing all dependencies in the project
-* a ``foo.dot.<target>`` file for each target, file showing on which other targets the respective target depends
-* a ``foo.dot.<target>.dependers`` file, showing which other targets depend on the respective target
+When running CMake with the ``--graphviz=foo.dot`` option, it produces:
 
-The different dependency types ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
-are represented as solid, dashed and dotted edges.
+* a ``foo.dot`` file, showing all dependencies in the project
+* a ``foo.dot.<target>`` file for each target, showing on which other targets
+  it depends
+* a ``foo.dot.<target>.dependers`` file for each target, showing which other
+  targets depend on it
 
-This can result in huge graphs.  Using the file
-``CMakeGraphVizOptions.cmake`` the look and content of the generated
-graphs can be influenced.  This file is searched first in
-:variable:`CMAKE_BINARY_DIR` and then in :variable:`CMAKE_SOURCE_DIR`.  If found, it is
-read and the variables set in it are used to adjust options for the
-generated graphviz files.
+Those .dot files can be converted to images using the *dot* command from the
+Graphviz package:
 
-.. variable:: GRAPHVIZ_GRAPH_TYPE
+.. code-block:: shell
 
- The graph type.
+  dot -Tpng -o foo.png foo.dot
 
- * Mandatory : NO
- * Default   : "digraph"
+The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE``
+are represented as solid, dashed and dotted edges.
 
- Valid graph types are:
+Variables specific to the Graphviz support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
- * "graph" : Nodes are joined with lines
- * "digraph" : Nodes are joined with arrows showing direction
- * "strict graph" : Like "graph" but max one line between each node
- * "strict digraph" : Like "graph" but max one line between each node in each direction
+The resulting graphs can be huge.  The look and content of the generated graphs
+can be controlled using the file ``CMakeGraphVizOptions.cmake``.  This file is
+first searched in :variable:`CMAKE_BINARY_DIR`, and then in
+:variable:`CMAKE_SOURCE_DIR`.  If found, the variables set in it are used to
+adjust options for the generated Graphviz files.
 
 .. variable:: GRAPHVIZ_GRAPH_NAME
 
  The graph name.
 
- * Mandatory : NO
- * Default   : "GG"
+ * Mandatory: NO
+ * Default: value of :variable:`CMAKE_PROJECT_NAME`
 
 .. variable:: GRAPHVIZ_GRAPH_HEADER
 
- The header written at the top of the graphviz file.
+ The header written at the top of the Graphviz files.
 
- * Mandatory : NO
- * Default   : "node [n  fontsize = "12"];"
+ * Mandatory: NO
+ * Default: "node [ fontsize = "12" ];"
 
 .. variable:: GRAPHVIZ_NODE_PREFIX
 
- The prefix for each node in the graphviz file.
+ The prefix for each node in the Graphviz files.
 
- * Mandatory : NO
- * Default   : "node"
+ * Mandatory: NO
+ * Default: "node"
 
 .. variable:: GRAPHVIZ_EXECUTABLES
 
- Set this to FALSE to exclude executables from the generated graphs.
+ Set to FALSE to exclude executables from the generated graphs.
 
- * Mandatory : NO
- * Default   : TRUE
+ * Mandatory: NO
+ * Default: TRUE
 
 .. variable:: GRAPHVIZ_STATIC_LIBS
 
- Set this to FALSE to exclude static libraries from the generated graphs.
+ Set to FALSE to exclude static libraries from the generated graphs.
 
- * Mandatory : NO
- * Default   : TRUE
+ * Mandatory: NO
+ * Default: TRUE
 
 .. variable:: GRAPHVIZ_SHARED_LIBS
 
- Set this to FALSE to exclude shared libraries from the generated graphs.
+ Set to FALSE to exclude shared libraries from the generated graphs.
 
- * Mandatory : NO
- * Default   : TRUE
+ * Mandatory: NO
+ * Default: TRUE
 
 .. variable:: GRAPHVIZ_MODULE_LIBS
 
- Set this to FALSE to exclude module libraries from the generated graphs.
+ Set to FALSE to exclude module libraries from the generated graphs.
+
+ * Mandatory: NO
+ * Default: TRUE
+
+.. variable:: GRAPHVIZ_INTERFACE_LIBS
+
+ Set to FALSE to exclude interface libraries from the generated graphs.
+
+ * Mandatory: NO
+ * Default: TRUE
 
- * Mandatory : NO
- * Default   : TRUE
+.. variable:: GRAPHVIZ_OBJECT_LIBS
+
+ Set to FALSE to exclude object libraries from the generated graphs.
+
+ * Mandatory: NO
+ * Default: TRUE
+
+.. variable:: GRAPHVIZ_UNKNOWN_LIBS
+
+ Set to FALSE to exclude unknown libraries from the generated graphs.
+
+ * Mandatory: NO
+ * Default: TRUE
 
 .. variable:: GRAPHVIZ_EXTERNAL_LIBS
 
- Set this to FALSE to exclude external libraries from the generated graphs.
+ Set to FALSE to exclude external libraries from the generated graphs.
+
+ * Mandatory: NO
+ * Default: TRUE
+
+.. variable:: GRAPHVIZ_CUSTOM_TARGETS
+
+ Set to TRUE to include custom targets in the generated graphs.
 
- * Mandatory : NO
- * Default   : TRUE
+ * Mandatory: NO
+ * Default: FALSE
 
 .. variable:: GRAPHVIZ_IGNORE_TARGETS
 
- A list of regular expressions for ignoring targets.
+ A list of regular expressions for names of targets to exclude from the
+ generated graphs.
 
- * Mandatory : NO
- * Default   : empty
+ * Mandatory: NO
+ * Default: empty
 
 .. variable:: GRAPHVIZ_GENERATE_PER_TARGET
 
- Set this to FALSE to exclude per target graphs ``foo.dot.<target>``.
+ Set to FALSE to not generate per-target graphs ``foo.dot.<target>``.
 
- * Mandatory : NO
- * Default   : TRUE
+ * Mandatory: NO
+ * Default: TRUE
 
 .. variable:: GRAPHVIZ_GENERATE_DEPENDERS
 
- Set this to FALSE to exclude depender graphs ``foo.dot.<target>.dependers``.
+ Set to FALSE to not generate depender graphs ``foo.dot.<target>.dependers``.
 
- * Mandatory : NO
- * Default   : TRUE
+ * Mandatory: NO
+ * Default: TRUE
 #]=======================================================================]