Cutter導入事例: Senna (1)

Sennaの単体テストフレームワークとしてCutterを導入したときの手順です。自分のプロジェクトに Cutterを導入するときの参考になるかもしれません。全体としてそこそこ長くなってしまったので、何回かに分割して紹介することにします。

内容はSennaのリポジトリでやったことの一部です。リポジトリは公開されているので、試行錯誤の後などをみたい場合はコミットを追いかけるとよいでしょう。また、ここでは断片としてしか出てこないコードについても、リポジトリの中には完全な形で入っています。

もし、まだCutterについて知らない場合は、はじめにチュートリアルを読んでください。

はじめに

まず、Sennaについて簡単に説明します。

Sennaは組み込み型の全文検索エンジンで、その機能をライブラリとして提供します。SennaのAPIはbasic APIやadvanced APIなどいくつかのグループにわかれています。

今回はSennaの単体テストフレームワークとしてCutterを導入し、 utility APIのひとつ、snippet¹のテストを作成するまでを示します。このためには以下の作業が必要になります。

SennaのビルドシステムにCutterを組み込む
Cutterでsnippet APIのテストを記述する

作業に入る前にSennaのビルドシステムについて確認します。

Sennaのビルドシステム

SennaではGNU Automakeや GNU LibtoolなどGNUビルドシステムを利用したビルドシステムを採用しています。

CutterはGNUビルドシステムサポート用の機能をいくつか提供しています。そのため、GNUビルドシステムを用いているプロジェクトへはCutterを容易に導入することができます。

もし、これからプロジェクトを始める場合でGNUビルドシステムを採用する場合はCutterのチュートリアルが参考になるでしょう。

ビルドシステムへのCutterの組み込み

Sennaの単体テストフレームワークとしてCutterを採用するにあたって、以下のような条件を満たすこととします。

Cutterがない場合でもユーザがSennaをビルドできること
Cutterがない場合でも開発者がSennaをビルドできること
configure時にCutterを使用するかどうかを指定できること
Cutterで作成したテストはtest/unit/以下に配置すること
テストではテストを簡潔・容易に記述するためにGLibを利用する

上記の中でのユーザと開発者の違いは、autogen.shを用いて自分で configureを作成するかどうかです。ユーザは開発者が作成した configureを利用するため、自分でconfigureを作成しません。一方、開発者はSubversionリポジトリ内にはconfigureは入っていないのでautogen.shを使ってconfigure.acからconfigureを作成し、利用します。つまり、違いは以下の通りになります。

ユーザ: configureのみ実行
開発者: autogen.shとconfigureを実行

それでは、まずは、開発者はすべてCutterをインストールしているものとしてCutter対応のconfigureを生成できるようにします。

cutter.m4

Cutterはconfigure.ac内で利用できるCutter検出用のM4マクロを cutter.m4として提供しています。このファイルは ${PREFIX}/share/aclocal/cutter.m4としてインストールされます。 ${PREFIX}/share/aclocal/以下に他の.m4ファイルがインストールされているような環境ではおそらくそのままで大丈夫ですが、そうでない場合はautogen.shの中でaclocalを呼び出しているところを編集して${PREFIX}/share/aclocal/以下を.m4ファイルの検索パスに加える必要があります。

もし、Cutterのconfigureに--prefix=/tmp/localオプションをつけてビルド・インストールした場合はautogen.shを以下のように変更する必要があります。

Index: autogen.sh
===================================================================
--- autogen.sh	(リビジョン 820)
+++ autogen.sh	(作業コピー)
@@ -105,7 +105,7 @@
 echo "Running libtoolize ..."
 $LIBTOOLIZE --force --copy
 echo "Running aclocal ..."
-$ACLOCAL ${ACLOCAL_ARGS} -I .
+$ACLOCAL ${ACLOCAL_ARGS} -I . -I /tmp/local/share/aclocal
 echo "Running autoheader..."
 $AUTOHEADER
 echo "Running automake ..."

あるいはautogen.shを実行する時に環境変数ACLOCAL_ARGSを指定します。

% ACLOCAL_ARGS="-I /tmp/local/share/aclocal" ./autogen.sh

これでconfigure.ac内でCutterが提供する便利M4マクロを利用する準備が整いました。

テスト作成用パッケージ

Cutterはパッケージを pkg-configのパッケージとしてインストールします。パッケージをpkg-configのパッケージとして作成しているのは、pkg-configが広く普及していて、 GNUビルドツールなどpkg-configに対応しているビルドシステムが多いからです。

Cutterは、テスト作成用に以下の2つのパッケージを用意しています。

cutter: Cutterを利用してテストを作成する場合に利用
gcutter: cutterパッケージにGLibサポート機能を追加したパッケージ。GLibを利用してもっと簡潔・容易にテストを書きたい場合に利用

今回はGLibを利用してテストを作成するので、cutterパッケージではなくgcutterパッケージを利用します。

Cutterはconfigure.acで簡単にcutter/gcutterパッケージの設定を行えるように以下のM4マクロを提供しています。

AC_CHECK_CUTTER

cutterパッケージ検出マクロです。以下の変数をAC_SUBSTします。

CUTTER: cutterコマンドのパス
CUTTER_CFLAGS: cutterパッケージを用いたテストをビルドするためのCFLAGS
CUTTER_LIBS: cutterパッケージを用いたテストをビルドするためのLIBS

また、cutterパッケージが利用不可能な場合は ac_cv_use_cutterが"no"になります。

AC_CHECK_GCUTTER

gcutterパッケージ検出マクロです。上述のAC_CHECK_CUTTERマクロがAC_SUBSTする変数に加えて、以下の変数もAC_SUBSTします。

GCUTTER_CFLAGS: gcutterパッケージを用いたテストをビルドするためのCFLAGS
GCUTTER_LIBS: gcutterパッケージを用いたテストをビルドするためのLIBS

今回はGLibサポートがついたgcutterパッケージを利用するので、 AC_CHECK_GCUTTERマクロを利用します。よってconfigure.acには以下を追加することになります。

configure.ac:

AC_CHECK_GCUTTER

AM_CONDITIONAL([WITH_CUTTER], [test "$ac_cv_use_cutter" != "no"])
if test "$ac_cv_use_cutter" != "no"; then
  AC_DEFINE(WITH_CUTTER, 1, [Define to 1 if you use Cutter])
fi

これで、Makefile.amではCutterが利用できるかどうかはif WITH_CUTTER ... endifで判断できます。Makefile.amではCutterが利用できない場合はテストプログラムをビルドしないようにします。こうすることにより、ユーザがCutterをインストールしていなくても、Sennaをビルドできます。

cutter.m4がない場合への対応

cutter.m4がない場合は./autogen.shの実行が失敗します。つまり、開発者がconfigureを正常に生成できなくなります。

残念ながら、Cutterはそれほど有名なフリーソフトウェアではないため、開発者がCutterをインストールしていることはほとんどありません。そこで、開発者がCutterをインストールしていなくても configureを生成できるようにします。²

cutter.m4がインストールされているかどうかはAC_CHECK_GCUTTER 関数が定義されているかどうかでわかります。そのため、以下のように書くことにより、Cutterがインストールされてない環境でも configureを生成できます。もちろん、生成されたconfigureには Cutterの検出機能などはありません。

configure.ac:

m4_ifdef([AC_CHECK_GCUTTER], [
AC_CHECK_GCUTTER
],
[ac_cv_use_cutter="no"])

AM_CONDITIONAL([WITH_CUTTER], [test "$ac_cv_use_cutter" != "no"])
if test "$ac_cv_use_cutter" != "no"; then
  AC_DEFINE(WITH_CUTTER, 1, [Define to 1 if you use Cutter])
fi

このようにAC_CHECK_GCUTTERの呼び出し部分をm4_ifdefの中に入れるだけです。AC_CHECK_GCUTTERが定義されていない場合は ac_cv_use_cutterを"no"にしているのでWITH_CUTTERが真になることはありません。

ビルドシステムへtest/unit/以下を追加

Cutterを用いたテストプログラムはtest/unit/以下に配置します。このディレクトリは新規に作成するため、以下の作業が必要になります。

test/Makefile.amのSUBDIRSにunitを追加
configureでtest/unit/Makefileを生成する設定を追加
test/unit/Makefile.amの作成

まずは、test/Makefile.amのSUBDIRSにunitを追加し、test/unit/ 以下もビルド対象とします。

test/Makefile.am:

SUBDIRS = unit

続いて、configure.acのAC_CONFIG_FILESにtest/unit/Makefileを追加し、configureがtest/unit/Makefileを生成するようにします。

configure.ac:

AC_CONFIG_FILES([... test/unit/Makefile ...])

最後に、test/unit/Makefile.amを作成し、test/unit/以下のビルド方法を設定します。とりあえず、今は空っぽでかまいません。

% touch test/unit/Makefile.am

これで、test/unit/以下をSennaのビルドシステムに加えることができました。再度./autogen.sh, ./configureを実行してからmakeすれば、test/unit/以下もビルド対象になっていることがわかります。

% ./autogen.sh
% ./configure
% make
...
make[3]: ディレクトリ `.../test/unit' に入ります
...

テスト起動コマンド

test/unit/以下がビルド対象に加わったので、test/unit/以下に作成するテストプログラムを起動するコマンドを作成します。このテスト起動コマンドはmake checkから呼び出されることになります。

テスト起動コマンドは伝統的にrun-test.shというシェルスクリプトになっています。このシェルスクリプトからcutterコマンドを呼び出してテストを実行します。

cutterを実行するときはいくつかオプションを指定する必要があります。例えば、テストプログラムがあるディレクトリなどがそれです。ここでrun-test.shを作成する理由は、cutterへ渡すオプションなどを指定しなくてもよいようにするなど、より簡単にテストを実行できるようにするためです。

テストが簡単に実行できるということはとても重要なことです。テストを実行することが面倒だと、だんだんテストを実行しなくなってしまうからです。テストが実行されないと、新しくテストを作成することも面倒になってくるでしょう。これは悪い循環といえます。これを防ぐためにも最初のうちから簡単にテストを実行できる仕組みを用意しておくことが重要です。

また、引数なしでも動くrun-test.shを用意することにはもう一つ理由があります。それは、GNU Automakeが提供するテスト起動の仕組みであるmake checkからも利用できるようにすることです。make checkでは指定されたテスト起動スクリプトが引数なしでテストを実行できる必要があります。³

前置きが長くなりましたがテストをもっと簡単に走らせるためのスクリプト、run-test.shは以下のようになります。

test/unit/run-test.sh:

#!/bin/sh

export BASE_DIR="`dirname $0`"

if test x"$NO_MAKE" != x"yes"; then
    make -C $BASE_DIR/../../ > /dev/null || exit 1
fi

if test -z "$CUTTER"; then
    CUTTER="`make -s -C $BASE_DIR echo-cutter`"
fi

if test x"$CUTTER_DEBUG" = x"yes"; then
    CUTTER="$BASE_DIR/../../libtool --mode=execute gdb --args $CUTTER"
fi

CUTTER_ARGS="-s $BASE_DIR"
$CUTTER $CUTTER_ARGS "$@" $BASE_DIR

このスクリプトではmake check以外からも便利に利用できるようになっています。make check以外から起動された場合（つまり直接 test/unit/run-test.shを軌道した場合）は必要なビルドを行ってからテストを起動します。つまり、run-test.shからテストを起動した場合はビルド忘れがなくなります。

実は、上記のrun-test.shを直接起動できるようにするためには、 test/unit/Makefile.amにも一工夫する必要があります。それは、 configureで検出したcutterコマンドのパスをrun-test.shに伝えるためのターゲットを用意するということです。

test/unit/Makefile.am:

echo-cutter:
	@echo $(CUTTER)

これで、run-test.shを直接起動しても、必要に応じてビルドしたり、情報を集めたりしてテストを起動してくれます。

また、make checkではテスト結果とビルド結果が混ざりそこそこの出力になりますが、run-test.sh経由でビルド・テストを行うと必要最小限の出力になり、問題の発見が簡単になります。実際の開発は以下のようなサイクルになります。

ソース変更
test/unit/run-test.shを実行

テスト失敗→(1)に戻る
コミット→(1)に戻る

手順が少ないため開発のリズムが崩れにくくなります。このサイクルをより簡単に行うための方法もあるのですが、それはまた別の機会にします。

run-test.shができたので、make checkでrun-test.shを起動するようにMakefile.amを変更します。

test/unit/Makefile.am:

if WITH_CUTTER
TESTS = run-test.sh
TESTS_ENVIRONMENT = NO_MAKE=yes
...
endif

TESTS_ENVIRONMENTにNO_MAKE=yesを指定することにより、make check経由の場合はテスト実行前のmake実行を抑制します。

これでテストを実行するための環境は整いました。きりがよいので今回はここまでにします。

まとめ

ここまでで、以下のことについて説明しました。

GNUビルドシステムを採用した既存のプロジェクトへのCutter の組み込み方法
- cutter.m4で提供するM4マクロの使用方法
- Cutterをインストールしていないユーザへの対応
- Cutterをインストールしていない開発者への対応
Cutterを用いたテスト環境の構築方法
- 便利なテスト起動スクリプトrun-test.shの作成方法

続きではテストを作成します。

検索キーワードの周辺テキストのこと。ここではそれを取得するSennaの機能のこと。 ↩
本当は開発者には頻繁にテストを走らせて欲しいのでCutterを必須にしたいところです。 ↩
テスト起動スクリプトにオプションを指定する場合は環境変数を利用します。 ↩

ククログ

はじめに

Sennaのビルドシステム

ビルドシステムへのCutterの組み込み

cutter.m4

テスト作成用パッケージ

cutter.m4がない場合への対応

ビルドシステムへtest/unit/以下を追加

テスト起動コマンド

まとめ

関連情報