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 be SOURCE_DIR and BINARY_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 a CMakeGraphVizOptions.cmake file already exists in SOURCE_DIR or BINARY_DIR, and if not, will generate a default one for you and copy it to BINARY_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 a GRAPHVIZ_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 in SOURCE_DIR or BINARY_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.