oranges_add_graphviz_target¶
include (OrangesGraphviz)
View the full docs for this module
.
oranges_add_graphviz_target ([TARGET <targetName>] [ALL] [OUTPUT_DIR <outputDirectory>] [SOURCE_DIR <srcDir>] [BINARY_DIR <binDir>] [EXTRA_CMAKE_OPTIONS <options...>] [GRAPHVIZ_CONFIG_FILE <configFile>] [COPY_GRAPH_TO <filename>])
Note
Graphviz’s dot
tool is required to generate the output images. A path to its executable can manually be set using the PROGRAM_DOT
cache variable.
Creates a target that, when built, generates an image representing CMake’s build graph.
Because CMake only outputs one dependency graph for its whole build graph, the way this function works is that its TARGET
invokes another configuration of CMake in a child process, just to generate the build graph for this function’s output graph image.
In the child CMake invocation, the variable ORANGES_IN_GRAPHVIZ_CONFIG
will be defined to ON
.
All arguments are optional.
Options:
TARGET
Name of the custom target to create that, when built, will generate the dependency graph image. Defaults to
${PROJECT_NAME}DependencyGraph
.ALL
If specified, the custom target created will be built with CMake’s
All
target.OUTPUT_DIR
The directory in which the generated .dot file and image will be placed. The image itself will be at
<outputDirectory>/deps_graph.png
. Defaults to${CMAKE_CURRENT_BINARY_DIR}
.SOURCE_DIR
The top-level source directory used for the child invocation of CMake executed when the custom target is built. If you wish to only generate a graph of a subproject that may be contained within a superproject, then you should pass the subproject’s
${PROJECT_SOURCE_DIR}
as this parameter. Defaults to${CMAKE_SOURCE_DIR}
.BINARY_DIR
The top-level build directory used for the child invocation of CMake executed when the custom target is built. Defaults to
${CMAKE_CURRENT_BINARY_DIR}/Graphviz
.EXTRA_CMAKE_OPTIONS
Extra command-line options that will be passed to the child invocation of CMake verbatim. This should rarely need to be used. If there is any custom logic you need to do when preparing the build tree for the dependency graph image generation, your scripts can check the value of the variable
ORANGES_IN_GRAPHVIZ_CONFIG
to see if you are in a child CMake invoked by a custom target created by this function.GRAPHVIZ_CONFIG_FILE
You can use this parameter to specify your own
CMakeGraphVizOptions
file. CMake searches for this file in both the source and binary directories (which will beSOURCE_DIR
andBINARY_DIR
in the child invocation of CMake), and it simply sets some variables that CMake uses to configure Graphviz’s output. If this parameter is not given, this function will check if aCMakeGraphVizOptions.cmake
file already exists inSOURCE_DIR
orBINARY_DIR
, and if not, will generate a default one for you and copy it toBINARY_DIR
so that the child CMake finds it. In the default generated config file, the graph is named${PROJECT_NAME}
, custom targets are shown, and the per-target and dependers information is not generated. The generated file will be placed at<binDir>/CMakeGraphVizOptions.cmake
. If you do specify aGRAPHVIZ_CONFIG_FILE
, if you don’t provide an absolute path, it will be interpreted relative to the current directory (${CMAKE_CURRENT_LIST_DIR}
). If your custom config file is not already inSOURCE_DIR
orBINARY_DIR
, it will be copied to<binDir>/CMakeGraphVizOptions.cmake
.COPY_GRAPH_TO
An absolute filepath where the generated image will be copied to once built. The use case for this is to add the generated graph to your source tree, or to documentation, etc.