GNOME Bugzilla – Bug 753629
PLANTUML_JAR_PATH Environment Variable Needs Documenting
Last modified: 2018-07-30 10:59:32 UTC
Using doxygen 1.8.9.1 and PLANTUML File Doxyfile contains PLANTUML_JAR_PATH = /home/malff/plantuml/plantuml.jar The jar file itself contains jar -xf /home/malff/plantuml/plantuml.jar META-INF/MANIFEST.MF cat META-INF/MANIFEST.MF Manifest-Version: 1.0 Ant-Version: Apache Ant 1.9.4 Created-By: 1.8.0_31-b13 (Oracle Corporation) Main-Class: net.sourceforge.plantuml.Run And doxygen invokes PLANTUML with something similar to java -jar <<value of PLANTUML_JAR_PATH>> pufile Generation of UML diagrams with @startuml @enduml works fine, -- on my local machine only --. Now, working in a distributed team, where different developers or build hosts all look at the same source code (in git), generation of PLANTUML diagrams is broken for other people, because the plantuml.jar file is not installed in the same place. Expectation: The content of Doxyfile should not contain paths that ultimately depends on the platform / machine running doxygen, so that file Doxyfile can be checked in with source control management. Suggestion: Do not invoke java with a -jar file, use this instead: 1) When PLANTUML_JAR_PATH is specified in Doxyfile, java -classpath <<value of PLANTUML_JAR_PATH>> net.sourceforge.plantuml.Run pufile This allows backward compatibility, for people who happen to use a well defined, known, stable, PLANTUML_JAR_PATH. Or consider just dropping PLANTUML_JAR_PATH, see 2) below. 2) When PLANTUML_JAR_PATH is not specified in Doxyfile, Document that users must set their CLASSPATH environment variable before invoking doxygen with plantuml, as in export CLASSPATH=/home/malff/plantuml/plantuml.jar Invoke plantuml with java net.sourceforge.plantuml.Run pufile trusting the classpath to be correct. Note that the previous documented behavior, "PLANTUML_JAR_PATH is empty and therefore @startuml is ignored" can not longer be supported. Thanks for this great tool, and for considering to fix this bug.
I don't think it matters, but adding version info about plantuml just in case: malff@linux-4b1j:doxygen> java -jar /home/malff/plantuml/plantuml.jar -version PlantUML version 8028 (Fri Jul 10 21:00:41 CEST 2015) (GPL source distribution) OpenJDK Runtime Environment OpenJDK 64-Bit Server VM 1.7.0_85-b01 Linux
When working in a team I assume you will have a common setup and there will also be environment variables setup for all members. When you setup e.g. YOUR_PLANTUML_PATH to the the plantuml.jar to be used and in the Doxyfile you specify: PLANTUML_JAR_PATH = $(YOUR_PLANTUML_PATH) it should all work, without paths in the Doxyfile. Please have a look at this.
Thanks Albert. Using an environment variable works well, so there is no bug in the tool itself, as this feature is already supported. Now, the fact that doxygen supports environment variables is new to me. Upon reading the doc again, the only reference I could find is: Section http://www.stack.nl/~dimitri/doxygen/manual/config.html which contains a single line about it: "Environment variables can be expanded using the pattern $(ENV_VARIABLE_NAME)." As other users are likely to miss this also, changing this report to category Documentation. Please consider making environment variables more covered (a dedicated section within config.html, that can be referenced ?), and/or add a reference to env variables from this text: # When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the # path where java can find the plantuml.jar file. If left blank, it is assumed # PlantUML is not used or called during a preprocessing step. Doxygen will # generate a warning when it encounters a \startuml command in this case and # will not generate output for the diagram. because the value of PLANTUML_JAR_PATH is very likely to depend on the environment, unlike other parameters. Regards, -- Marc
As discussed in https://github.com/doxygen/doxygen/pull/734 , Doxygen has moved its issue tracking to https://github.com/doxygen/doxygen/issues All Doxygen tickets in GNOME Bugzilla have been migrated to Github. You can subscribe and participate in the new ticket in Github. You can find the corresponding Github ticket by searching for its Bugzilla ID (number) in Github. Hence I am closing this GNOME Bugzilla ticket. Please use the corresponding ticket in Github instead. Thanks a lot!