Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-14 02:08:27 +08:00
Code Issues Projects Releases Wiki Activity

Help: Move Graphviz documentation to --graphviz option

Browse Source 
CMakeGraphVizOptions is not a module to be included in a project, so
to make the Graphviz functionality clearer, this moves all its
documentation under the --graphviz option.

Fixes: #27110
This commit is contained in:
Peter Kokot
2025-08-02 20:38:09 +02:00
parent b85bdbf68d
commit f4d666549a
4 changed files with 145 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Help/manual/cmake-modules.7.rst
View File

@@ -55,7 +55,6 @@ These modules are loaded using the :command:`include` command.
/module/CMakeBackwardCompatibilityCXX
/module/CMakeDependentOption
/module/CMakeFindDependencyMacro
/module/CMakeGraphVizOptions
/module/CMakePackageConfigHelpers
/module/CMakePrintHelpers
/module/CMakePrintSystemInformation
@@ -328,6 +327,7 @@ These internal modules are not intended to be included directly in projects:
:maxdepth: 1
/module/CMakeFindPackageMode
/module/CMakeGraphVizOptions
/module/CTestScriptMode
/module/Findosg_functions
/module/SquishTestScript

4
Help/manual/cmake-presets.7.rst
View File

@@ -270,8 +270,8 @@ that may contain the following fields:
``graphviz``
An optional string representing the path to the graphviz input file,
that will contain all the library and executable dependencies
in the project. See the documentation for :module:`CMakeGraphVizOptions`
for more details.
in the project. See the documentation for :option:`cmake --graphviz` for
more details.
This field supports `macro expansion`_. If a relative path is specified,
it is calculated relative to the current working directory. It is allowed

142
Help/manual/cmake.1.rst
View File

@@ -252,11 +252,145 @@ Options
.. option:: --graphviz=<file>
Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
Generate `Graphviz <https://www.graphviz.org/>`_ of dependencies
Generate a graphviz input file that will contain all the library and
executable dependencies in the project. See the documentation for
:module:`CMakeGraphVizOptions` for more details.
This option generates a graphviz input file that will contain all the
library and executable dependencies in the project showing the
dependencies between the targets in a project, as well as external libraries
which are linked against.
When running CMake with the ``--graphviz=foo.dot`` option, it produces:
* 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
Those .dot files can be converted to images using the *dot* command from the
Graphviz package:
.. code-block:: shell
dot -Tpng -o foo.png foo.dot
.. versionadded:: 3.10
The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE``
are represented as solid, dashed and dotted edges.
.. rubric:: Variables specific to the Graphviz support
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: value of :variable:`CMAKE_PROJECT_NAME`
.. variable:: GRAPHVIZ_GRAPH_HEADER
The header written at the top of the Graphviz files.
* Mandatory: NO
* Default: "node [ fontsize = "12" ];"
.. variable:: GRAPHVIZ_NODE_PREFIX
The prefix for each node in the Graphviz files.
* Mandatory: NO
* Default: "node"
.. variable:: GRAPHVIZ_EXECUTABLES
Set to FALSE to exclude executables from the generated graphs.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_STATIC_LIBS
Set to FALSE to exclude static libraries from the generated graphs.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_SHARED_LIBS
Set to FALSE to exclude shared libraries from the generated graphs.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_MODULE_LIBS
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
.. 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 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: FALSE
.. variable:: GRAPHVIZ_IGNORE_TARGETS
A list of regular expressions for names of targets to exclude from the
generated graphs.
* Mandatory: NO
* Default: empty
.. variable:: GRAPHVIZ_GENERATE_PER_TARGET
Set to FALSE to not generate per-target graphs ``foo.dot.<target>``.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_GENERATE_DEPENDERS
Set to FALSE to not generate depender graphs ``foo.dot.<target>.dependers``.
* Mandatory: NO
* Default: TRUE
.. option:: --system-information [file]

145
Modules/CMakeGraphVizOptions.cmake
View File

@@ -5,146 +5,9 @@
CMakeGraphVizOptions
--------------------
The builtin Graphviz support of CMake.
.. note::
Generating Graphviz files
^^^^^^^^^^^^^^^^^^^^^^^^^
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.
When running CMake with the ``--graphviz=foo.dot`` option, it produces:
* 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
Those .dot files can be converted to images using the *dot* command from the
Graphviz package:
.. code-block:: shell
dot -Tpng -o foo.png foo.dot
.. versionadded:: 3.10
The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE``
are represented as solid, dashed and dotted edges.
Variables specific to the Graphviz support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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: value of :variable:`CMAKE_PROJECT_NAME`
.. variable:: GRAPHVIZ_GRAPH_HEADER
The header written at the top of the Graphviz files.
* Mandatory: NO
* Default: "node [ fontsize = "12" ];"
.. variable:: GRAPHVIZ_NODE_PREFIX
The prefix for each node in the Graphviz files.
* Mandatory: NO
* Default: "node"
.. variable:: GRAPHVIZ_EXECUTABLES
Set to FALSE to exclude executables from the generated graphs.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_STATIC_LIBS
Set to FALSE to exclude static libraries from the generated graphs.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_SHARED_LIBS
Set to FALSE to exclude shared libraries from the generated graphs.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_MODULE_LIBS
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
.. 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 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: FALSE
.. variable:: GRAPHVIZ_IGNORE_TARGETS
A list of regular expressions for names of targets to exclude from the
generated graphs.
* Mandatory: NO
* Default: empty
.. variable:: GRAPHVIZ_GENERATE_PER_TARGET
Set to FALSE to not generate per-target graphs ``foo.dot.<target>``.
* Mandatory: NO
* Default: TRUE
.. variable:: GRAPHVIZ_GENERATE_DEPENDERS
Set to FALSE to not generate depender graphs ``foo.dot.<target>.dependers``.
* Mandatory: NO
* Default: TRUE
This module is not intended to be included in CMake projects directly.
It once contained the information for using Graphviz in CMake. For
Graphviz usage in CMake refer to the :option:`cmake --graphviz`.
#]=======================================================================]