How can I resolve doxygen error: problems running PlantUML?

Question

I've been using doxygen for a while successfully. I also use DOT from graphviz. Now I am trying to integrate PlantUML. I installed java and downloaded plantuml.jar. I added a simple example to one of my doxygen comment blocks

/*!
    \brief      get the server's response to our upload
    \returns    a \ref ServerResponse
    \startuml{getServerUploadResponse.png} "getting the server response"
                device -> server: test1
                server --> device: test2
    \enduml
*/

... and set the doxygen config file like so:

HAVE_DOT               = YES
PLANTUML_JAR_PATH      = "Z:\Kane\softwareDev\tools\plantuml.jar"

but doxygen gives me an error; here is my console output (I'm using mingw on win7)

$ doxygen doxyconfig
error: Problems running PlantUML. Verify that the command 'java -jar "Z:/Kane/softwareDev/tools\plantuml.jar" -h' works from the command line. Exit code: 1

$ java -jar "Z:/Kane/softwareDev/tools\plantuml.jar" -h
Usage: java -jar plantuml.jar [options] -gui
        (to execute the GUI)
    or java -jar plantuml.jar [options] [file/dir] [file/dir] [file/dir]
        (to process files or directories)

You can use the following wildcards in files/dirs:
        *       means any characters but '\'
        ?       one and only one character but '\'
        **      means any characters (used to recurse through directories)

where options include:
    -gui                To run the graphical user interface
    -tpng               To generate images using PNG format (default)
    -tsvg               To generate images using SVG format
    -teps               To generate images using EPS format
    -tpdf               To generate images using PDF format
    -tvdx               To generate images using VDX format
    -txmi               To generate XMI file for class diagram
    -thtml              To generate HTML files for class diagram
    -ttxt               To generate images with ASCII art
    -tutxt              To generate images with ASCII art using Unicode characters
    -o[utput] "dir"     To generate images in the specified directory
    -DVAR1=value        To set a preprocessing variable as if '!define VAR1 value' were used
    -Sparam1=value      To set a skin parameter as if 'skinparam param1 value' were used
    -r[ecurse]          recurse through directories
    -config "file"      To read the provided config file before each diagram
    -charset xxx        To use a specific charset (default is windows-1252)
    -e[x]clude pattern  To exclude files that match the provided pattern
    -metadata           To retrieve PlantUML sources from PNG images
    -version            To display information about PlantUML and Java versions
    -checkversion       To check if a newer version is available for download
    -v[erbose]          To have log information
    -quiet              To NOT print error message into the console
    -keepfiles          To NOT delete temporary files after process
    -h[elp]             To display this help message
    -testdot            To test the installation of graphviz
    -graphvizdot "exe"  To specify dot executable
    -p[ipe]             To use stdin for PlantUML source and stdout for PNG/SVG/EPS generation
    -encodesprite 4|8|16[z] "file"      To encode a sprite at gray level (z for compression) from an image
    -computeurl|-encodeurl      To compute the encoded URL of a PlantUML source file
    -decodeurl          To retrieve the PlantUML source from an encoded URL
    -syntax             To report any syntax error from standard input without generating images
    -language           To print the list of PlantUML keywords
    -nosuggestengine    To disable the suggest engine when errors in diagrams
    -checkonly          To check the syntax of files without generating images
    -failfast           To stop processing as soon as a syntax error in diagram occurs
    -failfast2          To do a first syntax check before processing files, to fail even faster
    -pattern            To print the list of Regular Expression used by PlantUML
    -duration           To print the duration of complete diagrams processing
    -nbthread N         To use (N) threads for processing
    -nbthread auto      To use 2 threads for processing
    -author[s]          To print information about PlantUML authors
    -overwrite          To allow to overwrite read only files
    -printfonts         To print fonts available on your system

If needed, you can setup the environment variable GRAPHVIZ_DOT.

$ echo $?
0

$ java -jar "Z:/Kane/softwareDev/tools\plantuml.jar" -version
PlantUML version 8026 (Sun Jun 07 04:19:09 CDT 2015)
(GPL source distribution)
Java(TM) SE Runtime Environment
Java HotSpot(TM) Client VM
1.8.0_45-b15
Windows 7

The environment variable GRAPHVIZ_DOT has not been set
Dot executable is c:\Program Files (x86)\Graphviz2.38\bin\dot.exe
Dot version: dot - graphviz version 2.38.0 (20140413.2041)
Installation seems OK. File generation OK

$ doxygen --version
1.8.9.1

$ java -version
java version "1.8.0_45"
Java(TM) SE Runtime Environment (build 1.8.0_45-b15)
Java HotSpot(TM) Client VM (build 25.45-b02, mixed mode)

$ doxygen doxyconfig
error: Problems running PlantUML. Verify that the command 'java -jar "Z:/Kane/softwareDev/tools\plantuml.jar" -h' works from the command line. Exit code: 1

$

Answer 1

The problem is that PlantUML is not able to locate Dot executable.

PlantUML requires that either:

• Dot executable is located in PATH environment variable.
• GRAPHVIZ_DOT environment variable is set to executable.

If it is not the case, it does not work!

The workflow is as following:

1. Doxygen extracts content between @startuml and @enduml tags.
2. This output is handed over to PlantUML.
3. PlantUML generates diagrams using Dot - depending on diagram type (e.g., activity diagrams do not need Dot).

Solution:

1. set "GRAPHVIZ_DOT=c:\path\to\graphviz\bin\dot.exe"
2. doxygen doxyconfig

Now, PlantUML is able to locate Dot executable by using GRAPHVIZ_DOT environment variable.

I do not know why Doxygen does not hand over Dot settings properly to PlantUML. Furthermore, this error usually only pops up on Windows. On GNU/Linux Dot executable is usually located in PATH and can be found by PlantUML.

Answer 2

You may have one entry in the PATH that contains a folder named Java. This command to run from a command prompt will let you know where: FOR /F %F IN ("java") DO ECHO %~$PATH:F. If that the case, insert the path to Java before that entry in the PATH. I found this because I had this problem on one machine, not another.

It seems to be another bug of ShellExecuteEx(), beside a problem with symlink (doxywizard can't run PlantUML). I couldn't figure out how to fix it other than adding the .exe extension so that it would not match the java folder. And I also found out that the same problem happens with a Java folder in the current working directory. In this case, ShellExecuteEx() seems to use the Java folder before looking at the PATH. So modifying the PATH doesn't help.

It could be a another good reason to append the ".exe" to the member lpFile of SHELLEXECUTEINFO on Windows if it doesn't have an extension, or to never rely on PATH being set correctly.

Answer 3

The issue is because some of the folders in the path placed by the JRE are symlinks. And apparently symlinks are fine to execute from the command line, but not from another program.

On my system the PATH is set to C:\ProgramData\Oracle\Java\javapath that's a symlink to C:\ProgramData\Oracle\Java\javapath_target_403710984

Replacing one with the other fixes the issue.

Note that you might need to revisit this every time you upgrade the JRE.