如何解决 doxygen 错误：运行 PlantUML 的问题？

Question

我已经成功使用了一段时间的 doxygen。我也使用来自 graphviz 的 DOT。现在我正在尝试集成 PlantUML。我安装了java并下载了plantuml.jar。我在我的一个 doxygen 评论块中添加了一个简单的示例

/*!
    \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
*/

... 并像这样设置 doxygen 配置文件：

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

但是 doxygen 给了我一个错误；这是我的控制台输出（我在 win7 上使用 mingw）

$ 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

问题是因为 JRE 放置的路径中的某些文件夹是符号链接。显然符号链接可以从命令行执行，但不能从另一个程序执行。

在我的系统上，PATH 设置为 C:\ProgramData\Oracle\Java\javapath，它是 C:\ProgramData\Oracle\Java\javapath_target_403710984 的符号链接

用另一个替换一个可以解决问题。

请注意，您可能需要在每次升级 JRE 时重新访问此内容。

Answer 2

您可能在 PATH 中有一个条目，其中包含一个名为 Java 的文件夹。从命令提示符运行此命令将让您知道在哪里：FOR /F %F IN ("java") DO ECHO %~$PATH:F。如果是这种情况，请在 PATH 中的该条目之前插入 Java 的路径。我发现这个是因为我在一台机器上遇到了这个问题，而不是另一台。

这似乎是 ShellExecuteEx() 的另一个错误，除了符号链接的问题 (doxywizard can't run PlantUML)。除了添加 .exe 扩展名以使其与 java 文件夹不匹配之外，我不知道如何修复它。而且我还发现当前工作目录中的 Java 文件夹也会出现同样的问题。在这种情况下，ShellExecuteEx() 似乎在查看 PATH 之前使用了 Java 文件夹。所以修改 PATH 也无济于事。

如果它没有扩展名，或者永远不依赖正确设置的 PATH，则将“.exe”附加到 Windows 上 SHELLEXECUTEINFO 的成员 lpFile 可能是另一个很好的理由。

Answer 3

问题是 PlantUML 无法找到 Dot 可执行文件。

PlantUML 要求：

• Dot 可执行文件位于PATH 环境变量中。
• GRAPHVIZ_DOT 环境变量设置为可执行。

如果不是这样，那就不行了！

工作流程如下：

1. Doxygen 提取 @startuml 和 @enduml 标签之间的内容。
2. 此输出将移交给 PlantUML。
3. PlantUML 使用 Dot 生成图表 - 取决于图表类型（例如，活动图表不需要 Dot）。

解决方案：

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

现在，PlantUML 可以通过使用 GRAPHVIZ_DOT 环境变量来定位 Dot 可执行文件。

我不知道为什么 Doxygen 没有将 Dot 设置正确地移交给 PlantUML。此外，此错误通常仅在 Windows 上弹出。在 GNU/Linux 上，Dot 可执行文件通常位于PATH，并且可以通过 PlantUML 找到。