gradle-graphviz-plugin

A Gradle plugin to make builds using Graphviz portable. The plugin will download all necessary files and run Graphviz on your sources - on Windows, Mac and Linux.

Uses viz.js via viz.js-cli-wrapper installed via gradle-node-plugin.
Compared to the original Graphviz, viz.js has a few limitations. See here for details.

Installation

You can retrieve the plugin from the jitpack.io repository. The gradle plugin repository is additionally required for transitive dependencies. Add the following buildscript repositories and dependency to your Gradle build config.

Note that specifying the version master-SNAPSHOT will get you the artifact based on the current commit on branch master.
You can specify any release number, the latest one available is

Only Gradle 3+ is supported, the plugin may or may not work for Gradle 2.

Gradle

buildscript {
    repositories {
        maven { url 'https://plugins.gradle.org/m2' }
        maven { url 'https://jitpack.io' }
    }
    dependencies {
        classpath 'com.github.jeysal:gradle-graphviz-plugin:master-SNAPSHOT'
    }
}

apply plugin: 'com.github.jeysal.graphviz'

Usage

After applying the plugin, Graphviz will convert files in src/main/graphviz ending with .gv or .dot to xdot format and place the outputs in build/graphviz.

Configuration example

/* Do not download a Graphviz executable.
The plugin will try to find Graphviz on your PATH instead.
Note that using a regular Graphviz may cause problems
such as failing to write files in subdirectories of the outputDir.
For this reason and to preserve build portability,
disabling this is not recommended. */
vizSetup.enabled = false

graphviz {
    /* Path of the Graphviz executable to use.
    If not set, viz provided by :vizSetup or Graphviz from PATH environment variable is used. */
    executablePath = '/usr/bin/dot'

    // Graphviz layout engine to use. Defaults to the Graphviz executable's default layout (usually dot).
    layout = 'neato'

    /* Graphviz output formats to produce. Defaults to the Graphviz executable's default format (usually xdot).
    Note that if you specify a format twice or set formatSuffix to false,
    the formats overwrite each other and only the last one remains. */
    formats = ['svg']

    /* If true, the chosen format will be appended to every output file name. Defaults to true.
    The default format will not be appended since Graphviz itself decides what to generate in that case. */
    formatSuffix = false

    // Directory to scan for source files. Defaults to src/main/graphviz.
    sourceDir = file('graphvizSrc')
    
    // Directory to generate Graphviz output into. Defaults to build/graphviz.
    outputDir = file('graphvizOut')

    /* Configures the sources to use via ant-style patterns.
    If not configured, sources default to the example below. */
    sources {
        include '**/*.gv', '**/*.dot'
    }
}

Keep in mind the limitations from not using a real graphviz regarding layout and format support.

asciidoctor-diagram integration

If you configured your build to use asciidoctor-diagram via the asciidoctor-gradle-plugin (for example like this),
gradle-graphviz-plugin will automatically tell asciidoctor-diagram where to find the Graphviz dot executable without any further configuration.

This way, your asciidoc html files generated by asciidoctor-gradle-plugin will include diagrams rendered by Graphviz without the need for installing it manually.

If you do not want this behavior for some reason, you can disable it in you build config:

graphvizHooks.asciidoctor = false

Troubleshooting

npm

In the background, the vizSetup task uses Node.js and npm to fetch viz.js as a portable Graphviz replacement.

If you are getting error related to npm, you can run gradle with the --debug option to get the full npm output, hopefully containing meaningful error messages.

If you are behind a proxy, npm will most likely fail to download any packages. Check out the documentation on npm's config files and proxy settings (sections proxy & https-proxy) for hints on how to fix this.

Credits

A huge thanks to Mike Daines for making GraphViz to some extent portable with viz.js
and Sten Roger Sandvik for creating gradle-node-plugin, which is used for setting up viz.js!

License

gradle-graphviz-plugin is MIT-licensed.