はじめに
Githubなどにあるソースコードを解析する際に、ファイル構成やクラス構成などの概要だけでも分かれば解析のアタリがつけやすいです。本来は一定のルールに従ったコメントを記述したソースコードからドキュメントを自動生成するツールであるDoxygenを解析のために利用します。
解析が目的なので、対象のソースコードは変更しません。また、Doxygenの設定も難しいことは考えずに必要な情報が得られた設定だけメモしておきます。
追記
Graphvizをインストールすると、関数のコールグラフやクラスのUML表現が可能になります。このコールグラフが解析に非常に有用なので、Graphvizの設定も追加します。
環境
macOS 10.12.6
Doxygen 1.8.13_1
Graphviz 2.40.1
インストール
macOSならば、DoxygenとGraphvizをhomebrawによりインストールできます。
ringo@stupiddog $ brew install doxygen
==> Downloading https://homebrew.bintray.com/bottles/doxygen-1.8.13_1.sierra.bottle.1.tar.gz
Already downloaded: /Users/stupiddog/Library/Caches/Homebrew/doxygen-1.8.13_1.sierra.bottle.1.tar.gz
==> Pouring doxygen-1.8.13_1.sierra.bottle.1.tar.gz
🍺 /usr/local/Cellar/doxygen/1.8.13_1: 9 files, 13.1MB
ringo@stupiddog $ brew install graphviz
==> Installing dependencies for graphviz: fontconfig, libtiff, webp, gd
==> Installing graphviz dependency: fontconfig
...
==> Pouring graphviz-2.40.1.sierra.bottle.1.tar.gz
🍺 /usr/local/Cellar/graphviz/2.40.1: 536 files, 12.9MB
利用方法
Github – Adafruit-ST7735-Libraryから取得したコードを例にします。
対象のプロジェクト内にファイルを作成しない方法でドキュメントを生成します。
ringo@stupiddog $ pwd
/Users/stupiddog/src
ringo@stupiddog $ git clone https://github.com/adafruit/Adafruit-ST7735-Library
Cloning into 'Adafruit-ST7735-Library'...
remote: Counting objects: 461, done.
remote: Total 461 (delta 0), reused 0 (delta 0), pack-reused 461
Receiving objects: 100% (461/461), 146.80 KiB | 269.00 KiB/s, done.
Resolving deltas: 100% (198/198), done.
ringo@stupiddog $ ls -l ./Adafruit-ST7735-Library/
total 80
-rwxr-xr-x 1 stupiddog staff 24382 12 21 12:38 Adafruit_ST7735.cpp
-rwxr-xr-x 1 stupiddog staff 5565 12 21 12:38 Adafruit_ST7735.h
-rw-r--r-- 1 stupiddog staff 1260 12 21 12:38 README.txt
drwxr-xr-x 7 stupiddog staff 238 12 21 12:38 examples
-rw-r--r-- 1 stupiddog staff 319 12 21 12:38 library.properties
設定ファイルの作成
まずdoxygen -gコマンドにより設定ファイルの雛形を作成します。カレントディレクトリにDoxyfileとして作成されます。
ringo@stupiddog $ doxygen -g
Configuration file `Doxyfile' created.
Now edit the configuration file and enter
doxygen Doxyfile
to generate the documentation for your project
ringo@stupiddog $ ls -lF
total 216
drwxr-xr-x 9 stupiddog staff 306 12 21 12:38 Adafruit-ST7735-Library/
-rw-r--r-- 1 stupiddog staff 107461 12 21 12:42 Doxyfile
設定ファイルの変更
デフォルト設定ではカレントディレクトリにあるソースを対象としサブディレクトリは対象としません。今回はカレントディレクトリのサブディレクトリに対象のプロジェクトがあります。
また、html形式とLaTeX形式のドキュメントが作成されますが、LaTeX形式は不要です。
ringo@stupiddog $ tree ~/src
/Users/stupiddog/src
├── Adafruit-ST7735-Library
│ ├── Adafruit_ST7735.cpp
│ ├── Adafruit_ST7735.h
│ ├── README.txt
│ ├── examples
│ │ ├── graphicstest
│ │ │ └── graphicstest.ino
│ │ ├── rotationtest
│ │ │ └── rotationtest.ino
│ │ ├── shieldtest
│ │ │ └── shieldtest.ino
│ │ ├── soft_spitftbitmap
│ │ │ └── soft_spitftbitmap.ino
│ │ └── spitftbitmap
│ │ └── spitftbitmap.ino
│ └── library.properties
└── Doxyfile
7 directories, 10 files
ほとんど設定を変更せずにドキュメント生成できますが、以下の設定を変更します。
- サブディレクトリまで検索対象とする（RECURSIVE = YES）
- LaTeX形式の出力はしない（GENERATE_LATEX = NO）
- 解析なのでプライベートメンバーなど全て抜き出す（EXTRACT_ALL = YES）
- ソースコードのクロスリファレンスを生成（SOURCE_BROWSER = YES）
- インクルードファイルのコードもドキュメント化（INLINE_SOURCES = YES）
- Graphviz(dotコマンド)がある（HAVE_DOT = YES）
- クラス継承図とコールグラフをUML形式で表す（UML_LOOK = YES）
- 呼び出し側、呼び出し元のグラフを作成する（CALL_GRAPH = YES, CALLER_GRAPH = YES）
以下がdoxygen -gで作成したDoxyfileをDoxyfile.defaultとして複製し変更箇所を確認した結果です。(左が変更後、右が変更前)
ringo@stupiddog $ diff -y --suppress-common-lines -W80 Doxyfile Doxyfile.default
EXTRACT_ALL = YES | EXTRACT_ALL = NO
RECURSIVE = YES | RECURSIVE = NO
SOURCE_BROWSER = YES | SOURCE_BROWSER = NO
INLINE_SOURCES = YES | INLINE_SOURCES = NO
GENERATE_LATEX = NO | GENERATE_LATEX = YES
HAVE_DOT = YES | HAVE_DOT = NO
UML_LOOK = YES | UML_LOOK = NO
CALL_GRAPH = YES | CALL_GRAPH = NO
CALLER_GRAPH = YES | CALLER_GRAPH = NO
実行
doxygenコマンド実行時に Doxyfileを指定しなければカレントディレクトリにあるDoxyfileが読み込まれます。
ringo@stupiddog $ ls -lF
total 216
drwxr-xr-x 9 stupiddog staff 306 12 21 12:38 Adafruit-ST7735-Library/
-rw-r--r-- 1 stupiddog staff 107463 12 21 13:06 Doxyfile
ringo@stupiddog $ doxygen
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
Searching for files to exclude
Searching INPUT for files to process...
Searching for files in directory /Users/stupiddog/src
Searching for files in directory /Users/stupiddog/src/Adafruit-GFX-Library
Searching for files in directory /Users/stupiddog/src/Adafruit-GFX-Library/fontconvert
Searching for files in directory /Users/stupiddog/src/Adafruit-GFX-Library/Fonts
...
finished...
結果の確認
結果はhtmlディレクトリに出力されます。
ringo@stupiddog $ ls -lF
total 216
drwxr-xr-x 9 stupiddog staff 306 12 21 12:38 Adafruit-ST7735-Library/
-rw-r--r-- 1 stupiddog staff 107463 12 21 13:06 Doxyfile
drwxr-xr-x 44 stupiddog staff 1496 12 21 13:13 html/
html/index.htmlをブラウザで開くと生成されたドキュメントを確認できます。
ringo@stupiddog $ open html/index.html
まとめ
クラスのリストや継承階層、ソースコードのクロスリファレンスなどをhtml形式で取得でき、関数の呼び出し関係もグラフ化できるので解析には十分です。一定のルールに従ったコメントを付けていれば、自動生成の対象になるので、自分のコードもDoxygenに対応させるのがよさそうです。