From f4d666549a93ea6cc02813d8fe0373d6219acb76 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sat, 2 Aug 2025 20:38:09 +0200 Subject: [PATCH] Help: Move Graphviz documentation to --graphviz option 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 --- Help/manual/cmake-modules.7.rst | 2 +- Help/manual/cmake-presets.7.rst | 4 +- Help/manual/cmake.1.rst | 142 +++++++++++++++++++++++++++- Modules/CMakeGraphVizOptions.cmake | 145 +---------------------------- 4 files changed, 145 insertions(+), 148 deletions(-) diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 52a5026df5..265a12878e 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -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 diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index d354c25ee0..b0f8e031f8 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -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 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 78b81f95b6..316ba25ac3 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -252,11 +252,145 @@ Options .. option:: --graphviz= - Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. + Generate `Graphviz `_ 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.`` file for each target, showing on which other targets + it depends + * a ``foo.dot..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.``. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_GENERATE_DEPENDERS + + Set to FALSE to not generate depender graphs ``foo.dot..dependers``. + + * Mandatory: NO + * Default: TRUE .. option:: --system-information [file] diff --git a/Modules/CMakeGraphVizOptions.cmake b/Modules/CMakeGraphVizOptions.cmake index 1d7dc0fd68..ee1c55afe1 100644 --- a/Modules/CMakeGraphVizOptions.cmake +++ b/Modules/CMakeGraphVizOptions.cmake @@ -5,146 +5,9 @@ CMakeGraphVizOptions -------------------- -The builtin Graphviz support of CMake. +.. note:: -Generating Graphviz files -^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake can generate `Graphviz `_ 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.`` file for each target, showing on which other targets - it depends -* a ``foo.dot..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.``. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_GENERATE_DEPENDERS - - Set to FALSE to not generate depender graphs ``foo.dot..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`. #]=======================================================================]