Drawing diagrams with PlantUML
Picture This

© Lead Image © David Castillo Dominici, 123RF.com
With PlantUML, you can quickly create all kinds of diagrams using human-readable text and reuse them anywhere.
Sooner or later, almost everybody needs to draw a diagram, whether to manage large amounts of information or organize group activities. For software developers and administrators (as well as business managers), diagrams based on the Unified Modeling Language (UML) make it easy to visualize complex systems, from software platforms to quality control departments, to see how they function.
UML stores drawings as plain text files, with a relatively intuitive syntax. If you are familiar with mind maps, you can often guess how to manually draw a diagram described by a UML file just by looking at it – even if you don't know UML! Because it is text-based, UML is extremely simple to generate with any software. You can produce hundreds of similar diagrams, with different parameters, by passing code generated on the fly by a simple shell script (or any other program) to a UML interpreter.
Additionally, UML is useful for efficiency, consistency, and version control. In a large project, UML interpreters can automatically find all the diagram descriptions in all of the project's files and generate the corresponding images in one fell swoop. The UML statements for a software algorithm or protocol's visual representation can be written as comments right above the code it visualizes in the software source file. Thanks to this integration, version control systems can store and track changes between different versions of many diagrams, just as they do with software code. The same feature makes it easy to quickly check if a diagram is consistent with the code it represents. All of this makes UML really reusable.
PlantUML [1], an open source UML diagram tool, lets you quickly create many different types of UML diagrams from text-based descriptions. In addition, you can also generate several diagram types not included in the UML standard (Gantt, mind map, WBS). While some types of PlantUML diagrams, like timing and interface mock-ups, may only be interesting to software and hardware designers, the diagram styles shown here can benefit all users.
PlantUML is perfect for beginners and intermediate users. It runs everywhere Java runs, and it is easily included in scripts. While it offers a very basic graphical interface, I prefer to write diagrams in my favorite text editor and then launch PlantUML from the command line.
Installation
The fastest way to use PlantUML is via the official web server [2], but you also can easily install it on your computer. The only prerequisite is a working java
command, which is the core part of any Java Runtime Environment (JRE). For testing some diagram types, you may also need the Graphviz utility, but that is available as a binary package for most Linux distributions. On Linux, you can check if you have a working JRE by typing the following at the prompt:
#> java -version
On Ubuntu, if JRE is not installed, you will get a notification that "the program 'java' can be found in the following packages":
* default-jre ... other Java packages...
In that case, just install the default JRE with:
#> sudo apt install default-jre
After installation (which consumed about 100MB of disk space on my computer), you can just download the Java container file, plantuml.jar
, from the website and save it in a folder of your choice.
Getting Started
To create a diagram from instructions saved into a plain text file called myumldiagram.puml
(.puml
is PlantUML's default file extension), enter the following at the prompt or in a shell script:
java -jar /path/to/plantuml.jar myumldiagram.puml
This command produces a PNG version of the diagram with the same name as the source file (in this case myumldiagram.png
) in the same folder. Other supported output formats are SVG and LaTeX. You can assign a different name and location to a diagram if desired. With the -pipe
option, PlantUML reads from standard input and "prints" the diagram on the standard output, which you can redirect wherever you want:
cat somefile.puml | java -jar plantuml.jar-pipe > /path/to/somefile.png
It is possible to process multiple UML source files with one call. If you give PlantUML a folder instead of a file, all the text files in that folder will be processed. Alternatively, you can use shell wildcards to only parse files with certain names or extensions:
java -jar /path/to/plantuml.jar "source/*/*.c"
To put all the generated images into a common folder, pass its absolute path to PlantUML with the -o
switch.
Even the simple examples shown in this article can take two to three seconds to run. If you plan to simultaneously process many UML files, take advantage of the -failfast2
and -failfast
options. -failfast2
checks if there are any errors in any of the files passed to the program and stops it without generating a diagram. -failfast
parses the code, but stops as soon as it finds one error. You must decide which option best fits your needs.
By default, PlantUML saves each diagram's full UML code inside the PNG file's metadata section, making it very easy to retrieve. The following command
java -jar /path/to/plantuml.jar -metadata statediagram.png >statediagram.puml
will save all the UML statements that generated statediagram.png
into a text file with the same base name, which allows quick changes to complex diagrams even if you did not write the code or have their UML description! A similar option, -checkmetadata
, regenerates a diagram only if the source code it contains does not match the corresponding .puml
file.
While the command-line switches mentioned here will be enough for most of your diagramming needs, you can learn about PlantUML's other command-line options in the documentation [3] or launch PlantUML with the -help
switch. You can also use the -language
switch to list all the UML keywords supported by PlantUML.
Sequence Diagrams
Sequence diagrams are frequently used in software and telecom documentation to describe exchanges between programs or communication protocols. However, as Listing 1 shows, they can describe any type of structured transaction (Figure 1). Listing 1 shows the UML source code for Figure 1.
Listing 1
Sequence Diagram
01 @startuml 02 Alice -> Bob : Hello, is the store open? 03 Bob -> Alice: Yes, it is. What do you want to buy? 04 Alice -> Bob : I want to buy some jeans 05 Alice <- Bob : Please tell me the color 06 Alice -> Bob : Black 07 Alice <- Bob : Now please tell me the size 08 Alice -> Bob : 42 09 @enduml

You can see UML's intuitiveness in Listing 1: Diagrams (with the exceptions discussed below) are enclosed between @startuml
and @enduml
statements; each line defines one element (in Figure 1, one transaction step). The direction of each step (i.e., if Alice is speaking to Bob, or vice versa) is given by the name order (line 2) or the arrow orientation (line 7). You can also draw sequencing exchanges among more than two entities.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs
News
-
MNT Seeks Financial Backing for New Seven-Inch Linux Laptop
MNT Pocket Reform is a tiny laptop that is modular, upgradable, recyclable, reusable, and ships with Debian Linux.
-
Ubuntu Flatpak Remix Adds Flatpak Support Preinstalled
If you're looking for a version of Ubuntu that includes Flatpak support out of the box, there's one clear option.
-
Gnome 44 Release Candidate Now Available
The Gnome 44 release candidate has officially arrived and adds a few changes into the mix.
-
Flathub Vying to Become the Standard Linux App Store
If the Flathub team has any say in the matter, their product will become the default tool for installing Linux apps in 2023.
-
Debian 12 to Ship with KDE Plasma 5.27
The Debian development team has shifted to the latest version of KDE for their testing branch.
-
Planet Computers Launches ARM-based Linux Desktop PCs
The firm that originally released a line of mobile keyboards has taken a different direction and has developed a new line of out-of-the-box mini Linux desktop computers.
-
Ubuntu No Longer Shipping with Flatpak
In a move that probably won’t come as a shock to many, Ubuntu and all of its official spins will no longer ship with Flatpak installed.
-
openSUSE Leap 15.5 Beta Now Available
The final version of the Leap 15 series of openSUSE is available for beta testing and offers only new software versions.
-
Linux Kernel 6.2 Released with New Hardware Support
Find out what's new in the most recent release from Linus Torvalds and the Linux kernel team.
-
Kubuntu Focus Team Releases New Mini Desktop
The team behind Kubuntu Focus has released a new NX GEN 2 mini desktop PC powered by Linux.