hoge diary - June 3, 2006

今回は Doxample というものを見つけたので，試しに使ってみたというレポートです．

さて，Doxample とは何かといいますと，ドキュメント生成ソフト Doxygen と，ビルド自動化ツール GNU Autoconf, GNU Automake, GNU Libtool (合わせて GNU Autotools と呼ばれる) の統合サンプルです．

どうやら，Autotools に Doxygen の設定ファイルを生成させてみよう，というもののようです．では試してみます．

Doxample にある doxample-0.1.tar.gz を展開すると，色々なファイルが出てきますので，とりあえず configure を起動してみます．

$ ./configure
checking for gcc... gcc
checking for C compiler default output file name... a.out
(中略)
checking for doxygen... /usr/bin/doxygen
checking for perl... /usr/bin/perl
checking for dot... /usr/bin/dot
checking for pdflatex... /usr/bin/pdflatex
checking for makeindex... /usr/bin/makeindex
(中略)
config.status: creating Makefile
config.status: creating config.h
config.status: executing depfiles commands
$

/usr/bin/doxygen や /usr/bin/dot 等の存在をチェックしてくれています．コマンドがもし見つからなかった場合はどうなるか，試してみました．

$ sudo mv /usr/bin/doxygen /usr/bin/doxygen.bak
Password:
$ sudo mv /usr/bin/dot /usr/bin/dot.bak
$ ./configure
checking for gcc... gcc
checking for C compiler default output file name... a.out
(中略)
checking for doxygen... no
configure: WARNING: doxygen not found - will not generate any doxygen documentation
(中略)
config.status: creating Makefile
config.status: creating config.h
config.status: executing depfiles commands
$

となりました．Doxygen がない環境でもエラーにはならないようです．

/usr/bin/dot がない環境も想定してみます．/usr/bin/dot.bak はそのままにしておき，/usr/bin/doxygen だけを元の名前に戻して configure を実行してみました．

$ sudo mv /usr/bin/doxygen.bak /usr/bin/doxygen
$ ./configure
checking for gcc... gcc
checking for C compiler default output file name... a.out
(中略)
checking for doxygen... /usr/bin/doxygen
checking for perl... /usr/bin/perl
checking for dot... no
configure: WARNING: dot not found - will not generate graphics for doxygen documentation
checking for pdflatex... /usr/bin/pdflatex
checking for makeindex... /usr/bin/makeindex
(中略)
config.status: creating Makefile
config.status: creating config.h
config.status: executing depfiles commands
$

となりました．しっかりした作りになっているようです．

dot も元に戻して，再 configure を行い，今度は make を実行します．

$ make distclean && ./configure
(中略)
(中略)
$ make
make  all-am
make[1]: Entering directory `/tmp/doxample-0.1'
if gcc -DHAVE_CONFIG_H -I. -I. -I.     -g -O2 -MT doxample.o -MD -MP -MF ".deps/doxample.Tpo" -c -o doxample.o doxample.c; \
then mv -f ".deps/doxample.Tpo" ".deps/doxample.Po"; else rm -f ".deps/doxample.Tpo"; exit 1; fi
gcc  -g -O2   -o doxample  doxample.o
rm -rf doxygen-doc
SRCDIR='.' PROJECT='doxample' DOCDIR='doxygen-doc' VERSION='0.1' PERL_PATH='/usr/bin/perl' HAVE_DOT='YES' DOT_PATH='/usr/bin' GENERATE_MAN='YES' GENERATE_RTF='NO' GENERATE_XML='NO' GENERATE_HTMLHELP='NO' GENERATE_CHI='NO' GENERATE_HTML='YES' GENERATE_LATEX='YES' /usr/bin/doxygen ./doxygen.cfg

make 一発で doxygen が起動しました．doxyfile (doxygen.cfg) を書き換えるのかと思っていたら，環境変数を経由してパラメータを渡していました．

make clean を実行すると，生成したドキュメントも消えるようになっています．

Doxample オリジナルの make ターゲットは以下の通りです．

• doxygen-doc : 全てのドキュメントを生成する．
• doxygen-run : Doxygen を実行するだけ．man, ps, pdf 形式のドキュメントに関する後処理は行わない．
• doxygen-man : 生成した man pages の名前を変更する．
• doxygen-ps : PostScript 形式のドキュメントを生成する．
• doxygen-pdf : PDF 形式のドキュメントを生成する．

ではこれをどうやって自作のパッケージに組み込むのかを調べてみると... 簡単に組み込めそうだということがわかりました．

まず，Doxample オリジナルの M4 マクロ定義が入っている acinclude.m4 内の記述を，現在使用している acinclude.m4 に追加．このとき既存の acinclude.m4 が無ければ新たに作成します．

次に，aminclude.am をプロジェクトのトップディレクトリにコピーして，Makefile.am に以下の記述を追加します．

include aminclude.am

MOSTLYCLEANFILES = $(DX_CLEANFILES)

EXTRA_DIST = $(DX_CONFIG)

もし man page 形式のドキュメントを生成するのであれば，Doxample の例に倣って以下の記述も Makefile.am に施しておいた方が良さそうです．ただし，ドキュメントファイル名 doxample.c.1 の名前は適宜書き換える必要があるでしょう．

if DX_COND_man

# You'd probably want to post-process man pages and installed the patched
# versions.
dist_man1_MANS = @DX_DOCDIR@/man/man1/doxample.c.1

$(dist_man1_MANS): doxygen-doc

endif

さらに configure.in に以下の記述を追加します．このとき，Doxample の例に倣って，AM_INIT_AUTOMAKE より前に入れておきます．

DX_HTML_FEATURE(ON)
DX_CHM_FEATURE(OFF)
DX_CHI_FEATURE(OFF)
DX_MAN_FEATURE(OFF)
DX_RTF_FEATURE(OFF)
DX_XML_FEATURE(OFF)
DX_PDF_FEATURE(OFF)
DX_PS_FEATURE(OFF)
DX_INIT_DOXYGEN(Project name, doxygen.cfg)

上記 Project Name の部分は適宜置き換えてください．作成するドキュメントの種類や doxygen.cfg の部分は適宜変更しても問題ないでしょう．

ファイルを書き換え終えたら，aclocal.m4, configure を再作成します．

$ aclocal
$ autoconf

これで完了です．

試しに自作パッケージで ./configure && make を実行してみると，今度は make 一発で自動的に Doxygen が実行されませんでした．何か記述が足りない可能性がありますが，make で毎回 Doxygen を動かすよりは，手動で make doxygen-doc を実行する方が都合が良さそうなので，今回はここまでとしておきます．