1# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
2# file Copyright.txt or https://cmake.org/licensing for details.
3
4#[=======================================================================[.rst:
5CMakeGraphVizOptions
6--------------------
7
8The builtin Graphviz support of CMake.
9
10Generating Graphviz files
11^^^^^^^^^^^^^^^^^^^^^^^^^
12
13CMake can generate `Graphviz <https://www.graphviz.org/>`_ files showing the
14dependencies between the targets in a project, as well as external libraries
15which are linked against.
16
17When running CMake with the ``--graphviz=foo.dot`` option, it produces:
18
19* a ``foo.dot`` file, showing all dependencies in the project
20* a ``foo.dot.<target>`` file for each target, showing on which other targets
21  it depends
22* a ``foo.dot.<target>.dependers`` file for each target, showing which other
23  targets depend on it
24
25Those .dot files can be converted to images using the *dot* command from the
26Graphviz package:
27
28.. code-block:: shell
29
30  dot -Tpng -o foo.png foo.dot
31
32.. versionadded:: 3.10
33  The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE``
34  are represented as solid, dashed and dotted edges.
35
36Variables specific to the Graphviz support
37^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38
39The resulting graphs can be huge.  The look and content of the generated graphs
40can be controlled using the file ``CMakeGraphVizOptions.cmake``.  This file is
41first searched in :variable:`CMAKE_BINARY_DIR`, and then in
42:variable:`CMAKE_SOURCE_DIR`.  If found, the variables set in it are used to
43adjust options for the generated Graphviz files.
44
45.. variable:: GRAPHVIZ_GRAPH_NAME
46
47 The graph name.
48
49 * Mandatory: NO
50 * Default: value of :variable:`CMAKE_PROJECT_NAME`
51
52.. variable:: GRAPHVIZ_GRAPH_HEADER
53
54 The header written at the top of the Graphviz files.
55
56 * Mandatory: NO
57 * Default: "node [ fontsize = "12" ];"
58
59.. variable:: GRAPHVIZ_NODE_PREFIX
60
61 The prefix for each node in the Graphviz files.
62
63 * Mandatory: NO
64 * Default: "node"
65
66.. variable:: GRAPHVIZ_EXECUTABLES
67
68 Set to FALSE to exclude executables from the generated graphs.
69
70 * Mandatory: NO
71 * Default: TRUE
72
73.. variable:: GRAPHVIZ_STATIC_LIBS
74
75 Set to FALSE to exclude static libraries from the generated graphs.
76
77 * Mandatory: NO
78 * Default: TRUE
79
80.. variable:: GRAPHVIZ_SHARED_LIBS
81
82 Set to FALSE to exclude shared libraries from the generated graphs.
83
84 * Mandatory: NO
85 * Default: TRUE
86
87.. variable:: GRAPHVIZ_MODULE_LIBS
88
89 Set to FALSE to exclude module libraries from the generated graphs.
90
91 * Mandatory: NO
92 * Default: TRUE
93
94.. variable:: GRAPHVIZ_INTERFACE_LIBS
95
96 Set to FALSE to exclude interface libraries from the generated graphs.
97
98 * Mandatory: NO
99 * Default: TRUE
100
101.. variable:: GRAPHVIZ_OBJECT_LIBS
102
103 Set to FALSE to exclude object libraries from the generated graphs.
104
105 * Mandatory: NO
106 * Default: TRUE
107
108.. variable:: GRAPHVIZ_UNKNOWN_LIBS
109
110 Set to FALSE to exclude unknown libraries from the generated graphs.
111
112 * Mandatory: NO
113 * Default: TRUE
114
115.. variable:: GRAPHVIZ_EXTERNAL_LIBS
116
117 Set to FALSE to exclude external libraries from the generated graphs.
118
119 * Mandatory: NO
120 * Default: TRUE
121
122.. variable:: GRAPHVIZ_CUSTOM_TARGETS
123
124 Set to TRUE to include custom targets in the generated graphs.
125
126 * Mandatory: NO
127 * Default: FALSE
128
129.. variable:: GRAPHVIZ_IGNORE_TARGETS
130
131 A list of regular expressions for names of targets to exclude from the
132 generated graphs.
133
134 * Mandatory: NO
135 * Default: empty
136
137.. variable:: GRAPHVIZ_GENERATE_PER_TARGET
138
139 Set to FALSE to not generate per-target graphs ``foo.dot.<target>``.
140
141 * Mandatory: NO
142 * Default: TRUE
143
144.. variable:: GRAPHVIZ_GENERATE_DEPENDERS
145
146 Set to FALSE to not generate depender graphs ``foo.dot.<target>.dependers``.
147
148 * Mandatory: NO
149 * Default: TRUE
150#]=======================================================================]
151