A Guide to Setting Up and Using PlantUML

Requirements

To get started with PlantUML, you'll need the following:

• Java Runtime Environment (JRE): PlantUML is a Java-based tool. We recommend installing the latest LTS release of Eclipse Temurin (formerly AdoptOpenJDK). You can download it from the Adoptium website.
• Graphviz: This is a graph visualization software required by PlantUML to render many diagram types. Download it from the official Graphviz website.
• Visual Studio Code (VSCode): A powerful and popular code editor. Download it from the VSCode website.
• PlantUML VSCode Extension: This extension provides syntax highlighting, live previews, and exporting capabilities within VSCode. You can find it on the VSCode Marketplace.

Setup

1. Installation

Windows

For a streamlined installation on Windows, you can use the Chocolatey package manager. Open PowerShell as an administrator and run the following command:

choco install plantuml

This will install PlantUML and its dependencies, including Java and Graphviz.

Alternatively, you can install each component manually:

1. Install the Eclipse Temurin JRE using the .msi installer from the Adoptium website.
2. Install Graphviz using the installer from the Graphviz website.
3. Install VSCode.
4. Install the PlantUML extension from within VSCode.

macOS

For macOS, Homebrew is the recommended package manager. Open your terminal and run:

brew install --cask temurin
brew install graphviz
brew install plantuml

Then, install the PlantUML extension in VSCode.

Linux (Debian/Ubuntu)

Use the apt package manager:

sudo apt-get update
sudo apt-get install default-jre graphviz

Then, install the PlantUML extension in VSCode. You will also need to download the plantuml.jar file from the PlantUML website.

2. Environment Variables

For the command-line interface to work correctly, you may need to set the following environment variables:

• JAVA_HOME: This should point to the installation directory of your JRE.
• GRAPHVIZ_DOT: This should point to the dot.exe executable within your Graphviz installation directory (e.g., C:\Program Files\Graphviz\bin\dot.exe).

3. VSCode Configuration

Open your VSCode settings.json file (Ctrl+Shift+P and search for "Preferences: Open User Settings (JSON)") and add the following configurations:

{
    "plantuml.jar": "PATH_TO_YOUR_PLANTUML.JAR",
    "plantuml.commandArgs": [
        "-DPLANTUML_LIMIT_SIZE=8192"
    ],
    "plantuml.jarArgs": [
        "-config PATH_TO_YOUR_CONFIG_FILE"
    ]
}

• plantuml.jar: Specify the path to your plantuml.jar file. This is especially important if you are not using a package manager.
• plantuml.commandArgs: Allows for larger diagram generation.
• plantuml.jarArgs: Lets you specify a custom configuration file for styling your diagrams.

Creating and Generating Diagrams

Creating Diagram Files

1. Create a new file with one of the following extensions: .plantuml, .puml, .pu, or .txt.
2. Add your PlantUML code to the file. You can find examples and documentation on the PlantUML website and at PlantText.

Generating Diagrams in VSCode

1. Open your PlantUML file in VSCode.
2. To see a live preview of your diagram, press Alt+D (Option+D on macOS).
3. To export your diagram, press Ctrl+Shift+P and search for ">PlantUML: Export Current Diagram".
4. Select your desired output format (e.g., PNG, SVG, PDF).

The exported files will be saved in an out folder in the same directory as your source file.

Generating Diagrams from the Command Line

For more control over the output, you can use the command line.

Creating a Command-Line Shortcut (Alias) for macOS & Linux

To avoid typing the full java -jar ... command every time, you can create a simple command-line alias.

1. Find the path to your plantuml.jar file. If you installed it with Homebrew, you can find the path by running brew --prefix plantuml.

2. Identify your shell by running echo $SHELL.

   • For zsh (default on modern macOS), your configuration file is ~/.zshrc.
   • For bash, your configuration file is ~/.bash_profile or ~/.bashrc.

3. Add the alias to your configuration file. Open it with a text editor (e.g., nano ~/.zshrc) and add the following line at the end. Remember to replace the path with the actual path to your JAR file.

   # PlantUML Alias
   alias plantuml='java -jar /path/to/your/plantuml.jar'

4. Apply the changes by restarting your terminal or running source ~/.zshrc (or your respective config file).

Command-Line Usage

With the alias set up, your command becomes much simpler.

Standard Command (Windows or without alias):

java -jar "C:\\path\\to\\plantuml.jar" diagram.puml -o output -progress -tpdf

Simplified Command (macOS/Linux with alias):

plantuml diagram.puml -o output -progress -tpdf

A more complete command with all options would look like this:

plantuml diagram.puml -o output -progress -config "C:\\path\\to\\plantuml.config" -DPLANTUML_LIMIT_SIZE=8192 -tpdf

Notes

• This guide provides instructions for different operating systems. Please adapt the paths and commands to your specific setup.
• It's always a good idea to use the latest version of the plantuml.jar file from the official website to ensure compatibility and access to the latest features.