拡張モジュールの config.m4 ファイルは、 UNIX のビルドシステムに対して「その拡張モジュールがサポートしている configure オプション」「依存する外部ライブラリ」 「コンパイル対象となるソースファイル」などの情報を伝えるものです。 一般的に用いられる autoconf マクロ (PHP 固有のものおよび autoconf 組み込みのもの) については Zend Engine 2 API リファレンス を参照ください。
PHP の拡張モジュールを開発する際には、autoconf のバージョン 2.13 を使用することを 強く 推奨します (もっと新しいバージョンもありますが、それでもあえて 2.13 です)。 バージョン 2.13 は、(機能や使い勝手、利用者数など) いろんな意味で最も一般的な autoconf です。 これより新しいバージョンを使用すると、configure の内容が期待とは多少異なるものになるかもしれません。
例1 config.m4 ファイルの例
dnl $Id$ dnl config.m4 for extension example
PHP_ARG_WITH(example, for example support,
[ --with-example[=FILE] Include example support. File is the optional path to example-config])
PHP_ARG_ENABLE(example-debug, whether to enable debugging support in example,
[ --enable-example-debug example: Enable debugging support in example], no, no)
PHP_ARG_WITH(example-extra, for extra libraries for example,
[ --with-example-extra=DIR example: Location of extra libraries for example], no, no)
dnl Check whether the extension is enabled at all
if test "$PHP_EXAMPLE" != "no"; then
dnl Check for example-config. First try any path that was given to us, then look in $PATH
AC_MSG_CHECKING([for example-config])
EXAMPLE_CONFIG="example-config"
if test "$PHP_EXAMPLE" != "yes"; then
EXAMPLE_PATH=$PHP_EXAMPLE
else
EXAMPLE_PATH=`$php_shtool path $EXAMPLE_CONFIG`
fi
dnl If a usable example-config was found, use it
if test -f "$EXAMPLE_PATH" && test -x "$EXAMPLE_PATH" && $EXAMPLE_PATH --version > /dev/null 2>&1; then
AC_MSG_RESULT([$EXAMPLE_PATH])
EXAMPLE_LIB_NAME=`$EXAMPLE_PATH --libname`
EXAMPLE_INCDIRS=`$EXAMPLE_PATH --incdirs`
EXAMPLE_LIBS=`$EXAMPLE_PATH --libs`
dnl Check that the library works properly
PHP_CHECK_LIBRARY($EXAMPLE_LIB_NAME, example_critical_function,
[
dnl Add the necessary include dirs
PHP_EVAL_INCLINE($EXAMPLE_INCDIRS)
dnl Add the necessary libraries and library dirs
PHP_EVAL_LIBLINE($EXAMPLE_LIBS, EXAMPLE_SHARED_LIBADD)
],[
dnl Bail out
AC_MSG_ERROR([example library not found. Check config.log for more information.])
],[$EXAMPLE_LIBS]
)
else
dnl No usable example-config, bail
AC_MSG_RESULT([not found])
AC_MSG_ERROR([Please check your example installation.])
fi
dnl Check whether to enable debugging
if test "$PHP_EXAMPLE_DEBUG" != "no"; then
dnl Yes, so set the C macro
AC_DEFINE(USE_EXAMPLE_DEBUG,1,[Include debugging support in example])
fi
dnl Check for the extra support
if test "$PHP_EXAMPLE_EXTRA" != "no"; then
if test "$PHP_EXAMPLE_EXTRA" == "yes"; then
AC_MSG_ERROR([You must specify a path when using --with-example-extra])
fi
PHP_CHECK_LIBRARY(example-extra, example_critical_extra_function,
[
dnl Add the neccessary paths
PHP_ADD_INCLUDE($PHP_EXAMPLE_EXTRA/include)
PHP_ADD_LIBRARY_WITH_PATH(example-extra, $PHP_EXAMPLE_EXTRA/lib, EXAMPLE_SHARED_LIBADD)
AC_DEFINE(HAVE_EXAMPLEEXTRALIB,1,[Whether example-extra support is present and requested])
EXAMPLE_SOURCES="$EXAMPLE_SOURCES example_extra.c"
],[
AC_MSG_ERROR([example-extra lib not found. See config.log for more information.])
],[-L$PHP_EXAMPLE_EXTRA/lib]
)
fi
dnl Finally, tell the build system about the extension and what files are needed
PHP_NEW_EXTENSION(example, example.c $EXAMPLE_SOURCES, $ext_shared)
PHP_SUBST(EXAMPLE_SHARED_LIBADD)
fi
config.m4 は、GNU autoconf の構文で書かれています。簡単にいうと、 これはシェルスクリプトに強力なマクロ言語を追加したようなものです。 コメントを記述する際には文字列 dnl を使用し、文字列のクォートには角括弧 ([ および ]) を使用します。文字列のクォートは、 必要に応じて何段階でもネストすることができます。この構文の完全な解説は、 » http://www.gnu.org/software/autoconf/manual/ にある autoconf のマニュアルを参照ください。
先ほどの config.m4 のサンプルで、 ちょっとしたコメントを除いていちばん最初にあるのは PHP_ARG_WITH() および PHP_ARG_ENABLE() を使用した 3 行です。これらは、configure コマンドで ./configure --help を実行したときに表示される オプションとその説明文を指定するものです。 その名が示すように、両者の違いはそれぞれ --with-* 系のオプションを作成するか --enable-* 系のオプションを作成するかです。 すべての拡張モジュールは、 このどちらかに拡張モジュール名とつけたオプションを提供する必要があります。 これにより、その拡張モジュールを PHP に組み込むかどうかを選択できるようになります。 規約上では、何らかのパラメータ (その拡張モジュールが必要とするライブラリやプログラムの場所など) を指定させる場合には PHP_ARG_WITH() を使うことになっています。 一方、単なるフラグとして使用するオプションの場合は PHP_ARG_ENABLE() を使用します。
例2 configure の出力例
$ ./configure --help ... --with-example[=FILE] Include example support. FILE is the optional path to example-config --enable-example-debug example: Enable debugging support in example --with-example-extra=DIR example: Location of extra libraries for example ... $ ./configure --with-example=/some/library/path/example-config --disable-example-debug --with-example-extra=/another/library/path ... checking for example support... yes checking whether to enable debugging support in example... no checking for extra libraries for example... /another/library/path ...
注意:
configure のコール時にどんな順でオプションを指定したかにかかわらず、 内部では config.m4 で指定した順にチェックを行います。
ここまでで、config.m4 を使ってユーザに対して選択肢を提供できるようになりました。 次は、選択内容に応じて実際の処理を行う番です。 上の例で、3 つのオプションすべてのデフォルト、つまり何も指定しなかったときの値は "no" です。拡張モジュールを有効にするオプションでは、 デフォルトを no にしておくのがおすすめです。 phpize で個別にビルドするときにはこれは上書きされますし、 PHP に組み込む際にデフォルトで拡張モジュールの空間を乱してはいけないからです。 これらの 3 つのオプションを処理するコードは、より複雑なものとなります。
最初のチェック、つまり --with-example[=FILE] オプションのチェックは、それが設定されているかどうかを調べます。 このオプションは拡張モジュールそのものを組み込むかどうかを決めるものです。 省略されていたり否定形式 (--without-example ) で指定されていたり、あるいは値として "no" が指定されていたりした場合は、それ以降は何も行いません。 上の例では、値として /some/library/path/example-config が指定されているので、このチェックは成功します。
次に、このコードは AC_MSG_CHECKING() をコールします。 これは autoconf のマクロで、標準的な "checking for something" の行を出力してユーザが example-config にパスを明示したかどうかを調べます。 この例では PHP_EXAMPLE は値 /some/library/path/example-config を受け取り、 それが変数 EXAMPLE_PATH にコピーされます。ユーザが --with-example だけしか指定しなかった場合は、 このコードは $php_shtool path $EXAMPLE_CONFIG を実行します。これは、そのユーザの現在の PATH を使用して example-config の場所を探します。 どちらにしても、次に行うのは EXAMPLE_PATH が通常の実行可能ファイルであるかどうか、 そして正常に実行できるかどうかの調査となります。 実行できた場合は AC_MSG_RESULT() がコールされ、 AC_MSG_CHECKING() で始まる出力行を補完します。 それ以外の場合は AC_MSG_ERROR() がコールされ、 指定されたメッセージを表示して configure を即時に終了させます。
次に、このコードは example-config を何度か実行してサイト固有の設定情報を取得します。 その次にコールするのは PHP_CHECK_LIBRARY() です。これは PHP のビルドシステムが autoconf の AC_CHECK_LIB() のラッパーとして用意しているマクロです。 PHP_CHECK_LIBRARY() は、 最初のパラメータで指定したライブラリの 2 番目のパラメータで指定したシンボルをコールするプログラムを コンパイル、リンクして実行します。 成功すると、3 番目のパラメータで指定したスクリプトを実行します。 このスクリプトは PHP ビルドシステムに対して インクルードパスやライブラリパス、ライブラリ名を example-config が返す文字列から通知します。 失敗すると、かわりに 4 番目のパラメータで指定したスクリプトを実行します。 この場合は、AC_MSG_ERROR() がコールされて処理を停止します。
--enable-example-debug の処理はずっと単純です。真値が設定されているかどうかだけを調べます。 チェックに成功すると、AC_DEFINE() をコールして C のマクロ USE_EXAMPLE_DEBUG を作成し、拡張モジュールのソースで使用できるようにします。 3 番目のパラメータは config.h 用のコメント文字列です。 これを空のままにしておいても問題はありません。たいていは空のままにします。
このサンプルでの説明用に用意した架空の機能 "extra" は --with-example-extra=DIR オプションで要求されるもので、架空のプログラム example-config とは別のものであり、 デフォルトのサーチパスもありません。 そのためユーザは、必要なライブラリのインストール先を指定する必要があります。 このような設定は実際の拡張モジュールではあまりないかもしれませんが、 説明用として用意しました。
このコードは、あまりなじみのない方法で PHP_EXAMPLE_EXTRA が真値であるかどうかを調べます。 否定形が指定された場合は、それ以降の処理を行いません。 これは、そのユーザが追加機能を必要としなかったことを表します。 パラメータなしで肯定形が指定された場合は、 AC_MSG_ERROR() がコールされて処理を停止します。 その次に、また PHP_CHECK_LIBRARY() を実行します。 今度は、定義済みのコンパイラオプションはないので、 PHP_ADD_INCLUDE() と PHP_ADD_LIBRARY_WITH_PATH() を使用して必要なインクルードパスやライブラリパス、 追加機能のためのライブラリのフラグを作成します。 AC_DEFINE() もコールされ、 追加機能が要求されていてそれが使用可能であることを通知します。 また、ビルドすべきファイルが別に存在することを示す変数も設定します。 チェックに失敗すると、おなじみの AC_MSG_ERROR() がコールされます。 失敗時のもうひとつの処理法は、次のように AC_MSG_WARNING() をコールすることです。
AC_MSG_WARNING([example-extra lib not found. example will be built without extra functionality.])
この場合は、configure はエラーではなく警告メッセージを表示し、処理を続行します。 いずれにせよ、失敗をどう処理するのかは拡張モジュールの開発者が決めることです。
必要なインクルードファイルやライブラリはすべて指定しました。 必要なオプションやマクロもすべて定義しました。 でも、あとひとつ残っていることがあります。 ビルドシステムに対して、拡張モジュール自身をビルドすることと そのために使用するファイル群を教えてやらなければならないのです。 そのためには PHP_NEW_EXTENSION() マクロをコールします。 このマクロの最初のパラメータは拡張モジュールの名前で、 これはディレクトリ名と一致します。2 番目のパラメータは、 その拡張モジュールを構成するすべてのソースファイルのリストです。 サブディレクトリ内のソースファイルをビルド処理に追加する方法については PHP_ADD_BUILD_DIR() を参照ください。 3 番目のパラメータは、常に $ext_shared でなければなりません。この値は、 configure の際に --with-example[=FILE] 用に PHP_ARG_WITH() がコールされたときに決まります。 4 番目のパラメータでは "SAPI クラス" を指定します。 これは CGI SAPI や CLI SAPI を必要とする場合にのみ有用です。 その他のクラスでは、ここは空のままにしておかなければなりません。 5 番目のパラメータには、拡張モジュールのビルド時の CFLAGS に追加するフラグのリストを指定します。 6 番目のパラメータは boolean 値です。"yes" を指定すると、 拡張モジュール全体のビルドを $CC ではなく $CXX を用いて行います。 3 番目以降のパラメータは、すべてオプションです。 最後に PHP_SUBST() をコールして、 拡張モジュールの共有ビルドを有効にします。 共有モードでの拡張モジュールのビルドをサポートしないようにする方法についての詳細は 拡張モジュールに関する FAQ を参照ください。
先ほど説明した counter 拡張モジュールの config.m4 ファイルは、上で説明したよりずっとシンプルです。 これは、ビルドシステムのさまざまな機能を使用していないからです。 外部のライブラリや同梱されているライブラリを使わない場合は、 このようにしておくことをお勧めします。
例3 counter の config.m4 ファイル
dnl
$
Id$ dnl config.m4 for extension counter PHP_ARG_ENABLE(counter, for counter support, [ --enable-counter Include counter support]) dnl Check whether the extension is enabled at all if test "$PHP_COUNTER" != "no"; then dnl Finally, tell the build system about the extension and what files are needed PHP_NEW_EXTENSION(counter, counter.c counter_util.c, $ext_shared) PHP_SUBST(COUNTER_SHARED_LIBADD) fi