プログラマーズ雑記帳

テキストから UML を生成する PlantUML についての解説記事を書いてみました。

• PlantUML の使い方 (今回)
• シーケンス図
• クラス図
  • オブジェクト図
  • パッケージ図
• ユースケース図
• アクティビティ図
• 状態遷移(ステートマシン)図
• コンポーネント図
  • 配置図
• skinparam
• PlantUML 実行用のバッチファイル

---

今回は PlantUML の使い方の説明です。

1. PlantUML とは
2. インストール
3. 日本語
4. コマンドライン
5. Doxygen との連携
6. Doxygen 連携用スクリプト
7. その他のツールとの連携
8. オンラインデモ

PlantUML とは

最近、プログラムの設計書などで UML を使うのが浸透してきていますが、 この UML を書くのはわりと面倒です。
CASE ツール, Doxygen などでは、クラス図を自動生成してくれますが、 ユースケース図やシーケンス図は自分で書く必要があります。

PlantUML はテキストから UML のダイアログを作成するフリーのツールです。 これを使えば UML をテキストでサクサク書けるようになります。 テキスト派としてはうれしいツールです。


例えば、次のようなテキストからシーケンス図が作成できます。

@startuml plantuml_simple.png

Foo -> Bar : メッセージ
Foo <-- Bar

@enduml

PlantUML には次のような利点があります。

• 素早く書ける
  • UML 図の作成がかなり速くなります。
    WYSIWYG のわかりやすさを否定する気はありませんが、 キーボードとマウスの往復はやはり面倒なものです。
    また、ツールと組み合わせれば、図を確認しながら書く事もできます。
    
    
• ソースのコメントに書ける
  • ソースに書けるので、 Doxygen と組み合わせてドキュメントを作成するといったこともできます。
    設計書と実際のソースとの乖離というのはよくあることです。 コメントとの乖離もめずらしくないですが、 比較的乖離の危険性は少なくなります。
    
    
• マージが可能
  • Git など最近 はやりの分散型バージョン管理システムではファイルをロックすることができません。 そのため、バイナリや XML ファイルの管理には不向きです。
    PlantUML はテキストで書くので、分散型バージョン管理システムでも使えます。
    
    
• ツールとの連携
  • コマンドラインプログラムなので、 Doxygen を始め、 Word, Redmine といったいろいろなアプリケーションとの連携もできます。
    
    

いいところばかりではなく、欠点もあります。

• 細かいレイアウトができない
  • レイアウトはある程度、自分で考えて作ってくれるので、 速く書ける分、自由にレイアウトすることができません。
    
    
• 記法を覚える必要がある
  • わりと直感的に書けるようになっているため、 覚えるのはそれほど大変ではありませんが、 WYSIWYG のツールに比べると覚えることは多くなります。
    記法の説明も行っているので、このブログの記事が参考になればと思います。
    
    

対応している UML 図には以下のようなものがあります。 各 UML 図の書き方に関しては次回以降をご覧ください。

• シーケンス図
• クラス図
• オブジェクト図
• ユースケース
• アクティビティ図
• 状態遷移図
• コンポーネント図

出力は PNG, SVG などに対応しています。

シーケンス図の場合は ASCII アートでの出力もできます。 ただ、日本語を使用すると位置がそろいません。

     ,---.          ,---.
     |Foo|          |Bar|
     `-+-'          `-+-'
       |   message    |  
       |------------->|  
       |              |  
       |              |  
       |<- - - - - - -|  
     ,-+-.          ,-+-.
     |Foo|          |Bar|
     `---'          `---'

インストール

PlantUML は Java で書かれたツールで、クロスプラットホームで使えます。

Java

OpenOffice や Eclipse などがインストールされていれば、 Java(JRE) も入っているでしょう。 ない場合は以下のサイトからダウンロードしてインストールしてください。

• Java テクノロジヘルプ - Java のインストール

PlantUML

PlantUML の jar ファイルは PlantUML のダウンロードページからダウンロードし、 好きなところに置いておきます。

• http://plantuml.sourceforge.net/download.html

Graphviz(dot)

シーケンス図以外の UML を使う場合には Graphviz(dot) が必要になります。

• Download | Graphviz - Graph Visualization Software

dot はデフォルトでは以下の実行ファイルが呼び出されます。

OS	実行ファイル
Windows	C:\Program Files\Graphviz X.XX\bin\dot.exe
Unix 系	/usr/bin/dot

別の場所にインストールされている場合などで、上記以外のパスの dot を使いたい時には次の 2 つの方法のどちらかでパスを指定します。

• 環境変数 GRAPHVIZ_DOT
• 起動時のオプション -graphvizdot

dot がちゃんと使えるようになっているかどうかは、以下のコマンドで確認できます。

 $ java -jar "plantuml.jarのパス" -testdot 

日本語

シーケンス図では日本語もそのまま使えます。
ただし、テキスト形式(ASCII アート)で出力したい場合には使えません。

シーケンス図以外では dot を使用します。 Windows であればほぼ問題ないと思いますが、 Graphviz(dot) のフォントが日本語を表示できるものに設定されてある必要があります。
ただし、 SVG で出力する場合にはフォントの設定に関係なく日本語も OK です。

コマンドライン

PlantUML はソースコードのコメント内やテキストファイルに書かれた定義を元に画像ファイルを生成します。コマンドは以下の形式です。

 $ java -jar "plantuml.jarのパス" [option] 入力ファイル [...] 

なお、あまり使い勝手がいいとは言えませんが、 GUI もあります。
-gui オプションを指定して起動するか、 Windows で jar ファイルをクリックすると起動します。

入力ファイル

入力ファイルにはファイルまたはディレクトリー(フォルダー)を指定します。
ディレクトリーを指定した場合にはディレクトリー内の以下の拡張子のファイルが対象となります。

• txt
• c, cpp, h
• java
• tex
• html, htm

ファイルのフィルターには通常の ?, * だけではなく、 パス区切りまで任意の文字とする(サブディレクトリ以下まで探す) ** も使えます。

$ java -jar plantuml.jar "dummy/**.cpp"
  dummy のフォルダー、サブフォルダー内の cpp ファイルが対象

出力ファイル

出力ファイルは UML の定義に書かれたファイル名で、 入力ファイルからの相対パス の位置に出力されます。

入力ファイル: sample.txt

@startuml images/sample.png
Foo -> Bar : メッセージ
Foo <-- Bar
@enduml

コマンド:

 $ java -jar plantuml.jar d:\home\foo\src\sample.txt
  d:\home\foo\src\images\sample.png ファイルが生成 

ソースファイルなどに定義を記述する場合は、 階層構造を持っていると出力先がバラバラになってしまいます。
こういった場合には -o オプションを使って出力先をフルパスで指定します。

コマンド:

 $ java -jar plantuml.jar -o d:\home\foo\doc d:\home\foo\src\sample.txt
  d:\home\foo\doc\images\sample.png ファイルが生成 

出力フォーマット

出力フォーマットはデフォルトでは PNG の画像ファイルです。 これを変更する場合には -tformat のオプションを使用します。

オプション	出力フォーマット
-tsvg	SVG 画像
-teps	EPS(Encapsulated PostScript) 画像 (Doxygen の latex 出力などで使用)
-ttxt	ASCII アート [シーケンス図]
-tutxt	罫線などに Unicode を使った文字アート [シーケンス図]
-txmi	XMI [クラス図]
-thtml	html ファイル [クラス図]

ただし、出力ファイル名は出力フォーマットに関係なく、定義に書いた名前で決まってしまいます。
例えば、定義で sample.png というファイル名にして、-tsvg を指定すると sample.png という名前の SVG ファイルが出力されます。

その他オプション

その他の役に立ちそうなオプションを紹介しておきます。

オプション	説明
-h[elp]	ヘルプを表示
-v[erbose]	verbose モード。処理中の内容を出力します。
-config FILE	各ダイアグラムで共通して読み込むファイルの指定。 配色、フォントなどを共通して変更したい場合(skinparam)に使用します。
-version	バージョンの出力。
-checkversion	PlantUML の更新チェック。 新しいバージョンが出ているかサイトにチェックしに行きます。
-p[ipe]	入力を標準入力、出力を標準出力に変更。 他のツールと連携時に役に立ちます。
-language	PlantUML のキーワードの一覧を出力。 Emacs などで PlantUML 用のモードを作る場合に使われます。

Doxygen との連携

Doxygen と連携して使用するためには、以下の手順となります。

1. コメント内に UML 定義を記述
   • 定義部分は Doxygen 用のコメントとならないようにする
   • PlantUML の出力画像を表示するように指定
2. PlantUML で画像ファイルを作成
3. Doxygen を実行

説明に使うサンプルは次のようなフォルダー構成としています。

(プロジェクトルート)/
 ├ src/            ソースフォルダー
 └ doc/            ドキュメントフォルダー
     ├ images/	    画像フォルダー
     └ Doxyfile    Doxygen の設定ファイル

コードの記述

Doxygen のコメント外で UML 定義をし、 それから作成される画像を @image で指定して、表示させます。

/// @image html plantuml_simple.png "UML のサンプル"
///

// @startuml plantuml_simple.png
//   Foo -> Bar : メッセージ
//   Foo <-- Bar
// @enduml

次は Doxygen の条件コマンド(@if, @endif) を使った例です。 DontIgnorePlantUMLCode が定義されていないので、 @if の中身が無視されてるようになっています。

/// @image html plantuml_simple.png "UML のサンプル"
///
/// @if DontIgnorePlantUMLCode
/// @startuml plantuml_simple.png
///   Foo -> Bar : メッセージ
///   Foo <-- Bar
/// @enduml
/// @endif

さらに Doxygen のエイリアス(ALIASES)の機能を使うと、もう少し簡単にコードを書けます。

Doxyfile への追加行 :

ALIASES = "startuml{1}=@image html \1\n@image rtf \1\n@image latex \1\n@if DontIgnorePlantUMLCode"
ALIASES += "enduml=@endif"

ソースコードでの記述 :

/// @startuml{plantuml_simple.png}
///   Foo -> Bar : メッセージ
///   Foo <-- Bar
/// @enduml

(注) @startuml と { の間にはスペースは入れない。

PlantUML の実行

doxygen の画像用フォルダーは Doxyfile の IMAGE_PATH で指定します。 これを出力先フォルダーとして PlantUML を実行し、画像を作成します。

 $ java -jar "plantuml.jar のパス" -o "Doxygen の Image フォルダー" 入力ファイル [...] 

例:

 $ java -jar plantuml.jar -o doc\image src\**.h src\**.cpp 

Doxygen の実行

画像を準備したあとは通常通り Doxygen を実行します。

 $ cd doc
 $ doxygen Doxyfile 

Doxygen, PlantUML 連携スクリプト

Doxygen との連携ってややこしいと思った方もいるのではないでしょうか。
実際めんどくさいので、 PlantUML 、 Doxygen の実行を一発でできるような Ruby スクリプトを作成しました。 ALIASES の設定などもスクリプト内で自動で行っています。

• run_umldoxy.rb
• run_umldoxy.bat

スクリプトの引数に plantuml.jar と Doxyfile を渡して実行します。

ruby run_umldoxy.rb "plantuml.jar のパス" [Doxyfile]

このスクリプトを使う場合は以下の点に注意してください。

• Doxyfile に書く各パスは絶対パスか Doxyfile からの相対パス
• コードの記述はエイリアスを使った形式
• java, doxygen に PATH を通す(通常インストール時に設定されます)

また、この Ruby スクリプトを Windows でも使いやすくするようにバッチファイル(run_umldoxy.bat) も作成しています。
使用する場合は plantuml.jar, run_umldoxy.rb, run_umldoxy.bat を同じフォルダーに置いてください。

次のような使い方ができます。

1. ショートカットをディスクトップに作成し、 Doxyfile をドラッグ &ドロップ
2. Doxyfile を .doxy のような拡張子で作成し、関連付け
3. Doxyfile のあるフォルダーにコピーして、ダブルクリック

2, 3 番目の場合はバッチファイル内の plantuml.jar と run_umldoxy.rb のパスをフルパスに書き直してください。

REM Tool settings
SET PLANTUML_JAR=c:\jar\plantuml.jar
SET RUN_UMLDOXY_RB=c:\jar\run_umldoxy.rb

skinparam の記述などで config ファイルを使いたい場合は config.txt の名前で、 run_umldoxy.rb と同じフォルダーに置いてください。

なお、スクリプト内部で行っている処理を詳しく書くと次のようなものです。

1. Doxyfile の解析
2. Doxyfile の一時ファイルを作成
   • PlantUML 用の AREAS を設定
   • IMAGE_PATH が指定されていない場合は Doxyfile のフォルダー直下の images フォルダーを指定
3. PlantUML を実行
   • Graphviz(dot) のパスが DOT_PATH で指定されていれば、そちらを使用
   • IMAGE_PATH を出力フォルダーに指定
   • INPUT, FILE_PATTERNS から入力ファイルを指定
4. Doxygen を実行

その他のツールとの連携

doxygen 以外にも Word や Redmine など連携できるアプリがあります。

• MS Word
  • http://plantuml.sourceforge.net/word.html
• Eclipse
  • http://plantuml.sourceforge.net/eclipse.html
• Emacs
  • http://plantuml.sourceforge.net/emacs.html
• Redmine
  • Redmine wiki external filter plugin | ndl@home
• PlantUML 編集用エディター
  • PlantUMLを記述する専用エディタ「PlantUML Editor」 - MOONGIFT|オープンソース・ソフトウェア紹介を軸としたITエンジニア、Webデザイナー向けブログ
  • PlantUML QEditor 日本語情報 - SourceForge.JP
• その他
  • http://plantuml.sourceforge.net/running.html

オンラインデモ

ネット上で確認できるオンラインデモサーバーが用意されています。

• PlantUMLServer

日本語にも対応していて、 ちょっと UML の記述を試して見るのに便利です。

関連記事

• PlantUML の使い方
• PlantUML - シーケンス図
• PlantUML - クラス図
• PlantUML - ユースケース図
• PlantUML - アクティビティ図