You can also run PlantUML using the following command :
java -jar plantuml.jar file1 file2 file3
This will look for @startXYZ into file1, file2 and file3. For each diagram, a .png file will be created.
For processing a whole directory, you can use:
This command will search for @startXYZ and @endXYZ into .c, .h, .cpp, .txt, .pu, .tex, .html, .htm or .java files of the c:/directory1 and c:/directory2 directories.
Wildcards
You can also use wildcards :
For a single character, use ?
For zero or more characters, use *
For zero or more characters, (including / or \), use a double **
So to process any .cpp files in all directories starting by dummy :
java -jar plantuml.jar "dummy*/*.cpp"
And to process any .cpp files in all directories starting by dummy, and theirs subdirectories :
java -jar plantuml.jar "dummy*/**.cpp"
Excluded files
You can exlude some files from the process using the -x option:
If you recurse into several directory, there is a slight difference if you provide an absolute or a relative path for this output directory:
An absolute path will ensure that all images are output to a single, specific, directory.
If you provide a relative path then the images is placed in that directory relative to the location of the input file, not the current directory (note: this applies even if the path begins with a .). When Plantuml processes files from multiple directores then the corresponding directory structure is created under the computed output directory.
Types of Output File
Images for your diagrams can be exported in a variety of different formats. By default the format will be a PNG file but another type can be selected using the following extensions:
After all preprocessing (includes etc), PlantUML saves the diagram's source code in the generated PNG Metadata in the form of encoded text.
It is possible to retrieve this source with the -metadata option. This means that the PNG is almost "editable": you can post it on a corporate wiki where you cannot install plugins, and someone in the future can update the diagram by getting the metadata, editing and re-uploading again. Also, the diagram is stand-alone.
Conversely, the -checkmetadata option checks whether the target PNG has the same source and if there are no changes, doesn't regenerate the PNG, thus saving all processing time. This allows you to run PlantUML on a whole folder (or tree with the -recursive option) incrementally.
Sounds like magic! No, merely clever engineering :-)
Example:
Unfortunately this option works only with local files. It doesn't work with -pipe so you cannot fetch a URL with eg curl and feed the PNG to PlantUML.
However, the Plantuml server has a similar feature, where it can get a PNG from a URL and extract its metadata.
Exit code
When there are some errors in diagrams the command returns an error (-1) exit code. But even if some diagrams contain some errors, all diagrams are generated, which can be time consuming for large project.
You can use the -failfast flag to change this behavior to stop diagram generations as soon as one error occurs. In that case, some diagrams will be generated, and some will not.
There is also a -failfast2 flag that does a first checking pass. If some error is present, no diagram will be generated at all. In case of error, -failfast2 runs even faster than -failfast, which may be useful for huge project.
Standard Input & Output
Using the -pipe option, you can easily use PlantUML in your scripts.
With this option, a diagram description is received through standard input and the png file is generated to standard output. No file is written on the local file system.
Example:
Note: Also take a look at -pipedelimitor and -pipeNoStderr to implement proper multiplexing of several PNG in a stream (in case the puml file contains multiple diagrams), and error handling.
Help
You can have a help message by launching :
java -jar plantuml.jar -help
This will output:
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:
-DVAR1=value Set a preprocessing variable as if '!define VAR1 value' were used
-I/path/to/file Include file as if '!include file' was used
-I/path/to/*.puml Include files with pattern
-Sparam1=value Set a skin parameter as if 'skinparam param1 value' were used
-author[s] Print information about PlantUML authors
-charset xyz Use a specific charset (default is windows-1252).
Use "utf-8" for extra international chars
-checkmetadata Skip PNG files that don't need to be regenerated
-checkonly Check the syntax of files without generating images
-checkversion Check if a newer version is available for download
-computeurl|-encodeurl Compute the encoded URL of a PlantUML source file
-config "file" Include a file before each diagram (same as -I ??)
-cypher Cypher texts of diagrams so that you can share them
-decodeurl Retrieve the PlantUML source from an encoded URL
-disablestats Disable statistics computation (default)
-duration Print the duration of complete diagrams processing
-[exclude|x] pattern Exclude files that match the provided pattern
-enablestats Enable statistics computation
-encodesprite 4|8|16[z] "file" Encode a sprite at gray level (z for compression) from an image
-extractstdlib Extract PlantUML Standard Library into stdlib folder
-failfast Stop processing as soon as a syntax error in diagram occurs
-failfast2 Do a first syntax check before processing files, to fail even faster
-filename \"example.puml\" Override %filename% variable
-graphvizdot "exe" Specify the graphviz "dot" executable.
If needed, you can setup the environment variable GRAPHVIZ_DOT.
-gui Run the graphical user interface
-h[elp] Display this help message
-htmlstats Output general statistics in file plantuml-stats.html
-keepfiles Do NOT delete temporary files after processing
-language Print the list of PlantUML keywords
-loopstats Continuously print statistics about usage
-metadata Retrieve PlantUML sources from PNG images
-nbthread N Use N threads for processing
-nbthread auto Use 4 threads for processing
-o[utput] "dir" Generate images in the specified directory
-overwrite Allow overwriting of read-only files
-p[ipe] Use stdin for PlantUML source and stdout for PNG/SVG/EPS generation
-pattern Print the list of Regular Expression used by PlantUML
-pipeNoStderr When used with -pipe, print errors to stdout (no image is generated in that case).
The first line is "ERROR" and it respects -pipedelimitor
-pipedelimitor "xyz" When used with -pipe, append "xyz" after every image
-pipeimageindex N Generate only the N-th image when used with -pipe
-pipemap Generate PNG map data of hyperlink rectangles, for use in HTML
-preproc Output the preprocessed text of diagrams
-printfonts Print fonts available on your system
-progress Display a textual progress bar at the console
-quiet Do NOT print error messages to the console
-r[ecurse] Recurse through directories
-realtimestats Generate statistics on the fly rather than at the end
-splash Display a splash screen with some progress bar
-stdlib Print standard library info
-syntax Report any syntax error from standard input without generating images
-teps Generate images using EPS format
-testdot Test the installation of graphviz
-thtml Generate HTML file for class diagram
-tlatex Generate images using LaTeX/Tikz format
-tlatex:nopreamble Generate images using LaTeX/Tikz format without preamble
-tpdf Generate images using PDF format
-tpng Generate images using PNG format (default)
-tscxml Generate SCXML file for state diagram
-tsvg Generate images using SVG format
-ttxt Generate images with ASCII art
-tutxt Generate images with ASCII art using Unicode characters
-tvdx Generate images using VDX format
-txmi Generate XMI file for class diagram
-v[erbose] Have log information
-version Display information about PlantUML and Java versions
-xmlstats Output general statistics in file plantuml-stats.xml
