真面目に PlantUML (1) : PlantUML のインストール
1年ほど前に ATOM エディタを使って PlantUML を使って UML で遊んだのだが, PlantUML 自体は「とりあえず動かしてみた」というレベルできちんと調べていなかった。 せっかく時間ができたのだから,この機会にちゃんと調べてみることにした。
目次
- PlantUML のインストール ← イマココ
- シーケンス図
- クラス図
- 実体関連図
PlantUML のインストール
PlantUML は UML (Unified Modeling Language; 統一モデリング言語) を記述するための DSL (Domain-Specific Language; ドメイン特化言語) と考えてよい。 UML の構文(に相当するもの)は図形で表されるが,それをテキストで記述できるようにしたのが PlantUML である。 PlantUML では UML 2.0 のうち以下の図(Diagrams)を作成できるようだ。
- 構造図(Structural Diagrams)
- 振る舞い図(Behavioral Diagrams)
PlantUML の実行モジュールは Java の jar ファイルで提供されている。
ダウンロードページから最新の plantuml.jar
ファイルをダウンロードしてそのまま使える。
PlantUML を実行するには Java のランタイム環境を用意する必要がある。 最新の OpenJDK を使って問題ない。 Ubuntu であれば APT で Java ランタイム環境をインストールできる。 たとえば LTS バージョンの Java 11 であれば
$ sudo apt install openjdk-11-jre
でOK。
シーケンス図とアクティビティ図以外は DOT 言語にトランス・コンパイルされるため,別途 Graphviz もインストールする必要がある。 Graphviz はダウンロードページ等から取得できる。 Ubuntu であれば APT でインストールできる。
$ sudo apt install graphviz
全ての用意ができたら plantuml.jar
ファイルのあるフォルダで以下のコマンドを入力し動作確認しておこう(以下は Ubuntu 環境下での例)。
$ java -jar plantuml.jar -version
PlantUML version 1.2019.11 (Sun Sep 22 19:02:15 JST 2019)
(GPL source distribution)
Java Runtime: OpenJDK Runtime Environment
JVM: OpenJDK 64-Bit Server VM
Java Version: 13.0.1+9
Operating System: Linux
Default Encoding: UTF-8
Language: ja
Country: JP
...
Graphviz との連携をテストするには以下のコマンドを実行する。
$ java -jar plantuml.jar -testdot
The environment variable GRAPHVIZ_DOT has not been set
Dot executable is /usr/bin/dot
Dot version: dot - graphviz version 2.40.1 (20161225.0304)
Installation seems OK. File generation OK
コマンドライン・オプション
PlantUML のコマンドライン・オプションは以下の通り。
$ java -jar 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
-tscxml To generate SCXML file for state diagram
-thtml To generate HTML file for class diagram
-ttxt To generate images with ASCII art
-tutxt To generate images with ASCII art using Unicode characters
-tlatex To generate images using LaTeX/Tikz format
-tlatex:nopreamble To generate images using LaTeX/Tikz format without preamble
-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
-I/path/to/file To include file as if '!include file' were used
-I/path/to/*.puml To include files with pattern
-charset xxx To use a specific charset (default is UTF-8)
-e[x]clude pattern To exclude files that match the provided pattern
-metadata To retrieve PlantUML sources from PNG images
-nometadata To NOT export metadata in PNG/SVG generated files
-checkmetadata Skip PNG files that don't need to be regenerated
-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
-debugsvek To generate intermediate svek files
-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
-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 4 threads for processing
-timeout N Processing timeout in (N) seconds. Defaults to 15 minutes (900 seconds).
-author[s] To print information about PlantUML authors
-overwrite To allow to overwrite read only files
-printfonts To print fonts available on your system
-enablestats To enable statistics computation
-disablestats To disable statistics computation (default)
-htmlstats To output general statistics in file plantuml-stats.html
-xmlstats To output general statistics in file plantuml-stats.xml
-realtimestats To generate statistics on the fly rather than at the end
-loopstats To continuously print statistics about usage
-splash To display a splash screen with some progress bar
-progress To display a textual progress bar in console
-pipeimageindex N To generate the Nth image with pipe option
-stdlib To print standard library info
-extractstdlib To extract PlantUML Standard Library into stdlib folder
-filename "example.puml" To override %filename% variable
-preproc To output preprocessor text of diagrams
-cypher To cypher texts of diagrams so that you can share them
If needed, you can setup the environment variable GRAPHVIZ_DOT.
かなりの数のオプションがあるが,よく使うのは以下のものだろうか。
オプション | 内容 |
---|---|
-tpng |
PNG 形式で出力(既定値) |
-tsvg |
SVG 形式で出力 |
-teps |
EPS 形式で出力 |
-tpdf |
PDF 形式で出力 |
-tlatex |
LaTeX/Tikz 形式で出力 |
-tlatex:nopreamble |
LaTeX/Tikz 形式で出力(プリアンブルなし) |
-o[utput] "dir" |
指定したフォルダに出力 |
-charset xxx |
文字エンコーディングの指定 |
-nometadata |
PNG/SVG 出力にメタデータを含めない |
-p[ipe] |
入出力をパイプで行う |
みんな大好き Hello World
では簡単なコードを処理してみよう。
hello.puml
という名前のファイルを用意して以下のように入力する。
@startuml
Alice->Bob : hello
Alice<-Bob : はろー
@enduml
PlantUML ではドキュメントの中にコードを埋め込むことを想定して @startuml ... @enduml
内の記述のみが処理の対象となる。
ではこのファイルを処理してみよう。
$ java -jar plantuml.jar -charset UTF-8 hello.puml
これで hello.puml
と同じフォルダに hello.png
ファイルが出力される。
hello.png
ファイルの内容は以下の通り。
って,ちっちゃ! じゃあ,解像度を調節してもう少し大きくしてみよう。
@startuml
skinparam dpi 300
Alice->Bob : hello
Alice<-Bob : はろー
@enduml
これを処理するとこうなる。
おおっ。 おっきくなった。
見た目の調整
上の例で示したように PlantUML では skinparam
コマンドを使って見た目の調整ができる。
では,もう少し調整を入れて UML っぽい図にしてみる。
@startuml
skinparam shadowing false
skinparam backgroundColor transparent
skinparam dpi 300
skinparam arrow {
FontColor Black
FontName Noto Serif JP
FontSize 10
FontStyle plain
Color Black
Thickness 1
}
skinparam participant {
FontColor Black
FontName Noto Sans
FontSize 14
FontStyle plain
BackgroundColor WhiteSmoke
BorderColor Black
BorderThickness 1
Padding 20
}
skinparam sequence {
LifeLineBackgroundColor transparent
LifeLineBorderColor Black
LifeLineBorderThickness 1
MessageAlignment center
}
hide footbox
skinparam BoxPadding 10
Alice->Bob : hello
Alice<-Bob : はろー
@enduml
フォントの変更と線の色と太さを調節してみた。 またライフラインの間隔も調整している。 以上を処理するとこんな図になる。
見た目の指定を別ファイルに分離する
見た目の指定は別ファイルにして再利用したいところである。
そこで hello.iuml
ファイルを作成して skinparam
コマンドの内容をまるっと移動してみる。
skinparam shadowing false
skinparam backgroundColor transparent
skinparam dpi 300
skinparam arrow {
FontColor Black
FontName Noto Serif JP
FontSize 10
FontStyle plain
Color Black
Thickness 1
}
skinparam participant {
FontColor Black
FontName Noto Sans
FontSize 14
FontStyle plain
BackgroundColor WhiteSmoke
BorderColor Black
BorderThickness 1
Padding 20
}
skinparam sequence {
LifeLineBackgroundColor transparent
LifeLineBorderColor Black
LifeLineBorderThickness 1
MessageAlignment center
}
hide footbox
skinparam BoxPadding 10
このファイルをインクルードする形でコードを修正する。
@startuml
!include hello.iuml
Alice->Bob : hello
Alice<-Bob : はろー
@enduml
これを処理すると
先程と全く同じ結果が得られる。
また最初の
@startuml
Alice->Bob : hello
Alice<-Bob : はろー
@enduml
に対して
$ java -jar plantuml.jar -charset UTF-8 -config hello.iuml hello.puml
と -config
オプションで hello.iuml
ファイルを指定しても同じ結果が得られる。
これで再利用しやすくなっただろう。
【追記】 PlantUML のコメント
PlantUML の @startuml ... @enduml
領域内にコメントを記述する際には以下の2通りの書き方がある。
@startuml
' 一行コメント
/'
複数行に渡る
コメント
'/
@enduml
なお,行の途中からコメントを挿入する
@startuml
skinparam dpi 300 '解像度の設定
@enduml
のような記述はできない(しかも行がまるごと無視されるだけでエラーにもならない)のでご注意を。