★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

38.18. 拡張構築基盤 #

PostgreSQL拡張モジュールの配布を考えているのであれば、移植可能な構築システムを準備することはかなり難しいものになるかもしれません。 このためPostgreSQLインストレーションは単純な拡張モジュールをすでにインストールされているサーバに対して簡単に構築できるように、PGXSと呼ばれる拡張向けの構築基盤を提供します。 PGXSは主にCコードを含む拡張を意図していますが、SQLのみからなる拡張でも使用できます。 PGXSPostgreSQLと相互に作用する任意のソフトウェアを構築するために使用できるような万能な構築システムを意図したものではないことに注意してください。 これは単に、単純なサーバ拡張用の一般的な構築規則を自動化するものです。 より複雑なパッケージでは、独自の構築システムを作成する必要があるかもしれません。

独自の拡張でPGXS基盤を使用するためには、簡単なmakefileを作成する必要があります。 このmakefileの中で、いくつか変数を設定し、大域的なPGXSmakefileをインクルードする必要があります。 以下にisbn_issnという名称の拡張モジュールを構築する例を示します。 このモジュールはいくつかのCコードを含む共有ライブラリ、拡張の制御ファイル、SQLスクリプト、インクルードファイル(他のモジュールが拡張の関数にSQLを経由せずにアクセスする必要があるかもしれない場合にのみ必要です)、ドキュメントテキストファイルから構成されます。

MODULES = isbn_issn
EXTENSION = isbn_issn
DATA = isbn_issn--1.0.sql
DOCS = README.isbn_issn
HEADERS_isbn_issn = isbn_issn.h

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

最後の3行は常に同じです。 ファイルのこの前に変数の設定と独自のmakeルールを記載してください。

以下の3個の変数の1つを構築対象に指定してください。

MODULES #

同じ家系のソースファイルから構築される共有ライブラリのリストです。 (このリストにはライブラリ接頭辞を含めないでください。)

MODULE_big #

複数のソースファイルから構築される共有ライブラリです。 (OBJSにオブジェクトファイルを列挙します。)

PROGRAM #

構築する実行プログラムです。 (OBJSにオブジェクトファイルを列挙します。)

以下の変数も設定できます。

EXTENSION #

拡張の名前です。 各名前に対して、prefix/share/extensionにインストールされるextension.controlを提供しなければなりません。

MODULEDIR #

DATAおよびDOCSファイルのインストール先となるはずのprefix/shareサブディレクトリです。 (設定がない場合、デフォルトはEXTENSIONが設定されている場合はextensionに、設定されていない場合はcontribになります。)

DATA #

prefix/share/$MODULEDIRにインストールされる様々なファイルです。

DATA_built #

prefix/share/$MODULEDIRにインストールされる、最初に構築しなければならない様々なファイルです。

DATA_TSEARCH #

prefix/share/tsearch_data以下にインストールされる様々なファイルです。

DOCS #

prefix/doc/$MODULEDIR以下にインストールされる様々なファイルです。

HEADERS
HEADERS_built #

(必要に応じてビルドして)prefix/include/server/$MODULEDIR/$MODULE_big以下にインストールをするファイル。

DATA_builtと違って、HEADERS_builtのファイルはcleanターゲットによって削除されません。削除したい場合には、それらをEXTRA_CLEANにも加えるか、削除を行う独自のルールを追加してください。

HEADERS_$MODULE
HEADERS_built_$MODULE #

(指定されていたならビルド後に)prefix/include/server/$MODULEDIR/$MODULEの下にインストールするファイル。ここでの$MODULEMODULESMODULE_bigで使われているモジュール名でなければなりません。

DATA_builtと違って、HEADERS_built_$MODULEのファイルはcleanターゲットによって削除されません。削除したい場合には、これらをEXTRA_CLEANにも加えるか、削除を行う独自のルールを追加してください。

同じモジュールあるいは任意の組み合わせに対して両方の変数を使うことは正当ですが、MODULESリストにプレフィックスbuilt_の有無しか異ならない二つのモジュール名を書く場合を除きます。これは両義解釈をひき起こすでしょう。 このような(おそらくありそうにない)場合、HEADERS_built_$MODULE変数だけを使うべきです。

SCRIPTS #

prefix/binにインストールされるスクリプトファイルです(バイナリファイルではありません)。

SCRIPTS_built #

prefix/binにインストールされる、最初に構築しなければならないスクリプトファイルです(バイナリファイルではありません)。

REGRESS #

リグレッションテストケース(接尾辞がない)のリストです。 後述します。

REGRESS_OPTS #

pg_regressに渡す追加オプションです。

ISOLATION #

分離性試験のリストです。 詳細は後述します。

ISOLATION_OPTS #

pg_isolation_regressに渡す追加オプションです。

TAP_TESTS #

TAPテストを実行する必要があるかどうかを定義するオプションです。 後述します。

NO_INSTALL #

installターゲットを定義しません。 構築物をインストールする必要のないテストモジュールに有用です。

NO_INSTALLCHECK #

installcheckターゲットを定義しません。 テストの際に特殊な設定が必要、あるいはpg_regressを使用しない場合などに有用です。

EXTRA_CLEAN #

make cleanで削除される追加ファイルです。

PG_CPPFLAGS #

CPPFLAGSの先頭に加えられます。

PG_CFLAGS #

CFLAGSに加えられます。

PG_CXXFLAGS #

CXXFLAGSに加えられます。

PG_LDFLAGS #

LDFLAGSの先頭に加えられます。

PG_LIBS #

PROGRAMのリンク行に追加されます。

MODULE_bigリンク行に追加されます。

PG_CONFIG #

構築対象のPostgreSQLインストレーション用のpg_configプログラムへのパスです。 (通常はPATH内の最初に見つかるpg_configが単純に使用されます)

このmakefileをMakefileとして拡張を保管するディレクトリ内に保管してください。 その後コンパイルするためにmakeを、モジュールをインストールするためにmake installを行うことができます。 デフォルトでは、PATHの中で最初に見つかるpg_configプログラムが対応するPostgreSQLインストレーション用に拡張はコンパイルされ、インストールされます。 makefileまたはmakeのコマンドラインのいずれかでPG_CONFIGを別のpg_configプログラムを指し示すように設定することで、別のインストレーションを使用できます。

構築ディレクトリを別にしておきたいのであれば、拡張のソースツリーの外のディレクトリでmakeを実行することもできます。 この方法はVPATH構築とも呼ばれます。 以下にやり方を示します。

mkdir build_dir
cd build_dir
make -f /path/to/extension/source/tree/Makefile
make -f /path/to/extension/source/tree/Makefile install

あるいは、コアコードと同様な方法でVPATH構築用のディレクトリを設定できます。 そのようにする1つの方法は、コアスクリプトconfig/prep_buildtreeを使うことです。 一度そうすれば、make変数VPATHを以下のように設定することで、構築できます。

make VPATH=/path/to/extension/source/tree
make VPATH=/path/to/extension/source/tree install

この方法はより様々なディレクトリのレイアウトで機能します。

REGRESS変数に列挙されたスクリプトは、make installを実行した後でmake installcheckによって呼び出すことができる、作成したモジュールのリグレッションテストで使用されます。 これが動作するためには、PostgreSQLサーバが実行していなければなりません。 REGRESS変数に列挙されたスクリプトは、拡張のディレクトリ内のsql/という名前のサブディレクトリ内に存在しなければなりません。 これらのファイルは.sqlという拡張子を持たなければなりません。 この拡張子はmakefile内のREGRESSリストには含まれません。 また試験ごとにexpected/という名前のサブディレクトリ内に想定出力を内容として含む、同じステムに.out拡張子を付けた名前のファイルがなければなりません。 make installcheckpsqlを用いて各試験スクリプトを実行し、結果出力が想定ファイルに一致するかどうか比較します。 何らかの差異はdiff -c書式でregression.diffsに書き出されます。 想定ファイルがない試験を実行しようとすると問題として報告されます。 このためすべての想定ファイルがあることを確認してください。

ISOLATION変数に列挙されたスクリプトは、make installを実行した後でmake installcheckによって呼び出すことができるモジュールでの同時実行中のセッションの振舞いの負荷テストで使用されます。 これが動作するためには、PostgreSQLサーバが実行していなければなりません。 ISOLATION変数に列挙されたスクリプトは、拡張のディレクトリ内のspecs/という名前のサブディレクトリ内に存在しなければなりません。 これらのファイルは.specという拡張子を持たなければなりません。 この拡張子はmakefile内のISOLATIONリストには含まれません。 また試験ごとにexpected/という名前のサブディレクトリ内に想定出力を内容として含む、同じステムに.out拡張子を付けた名前のファイルがなければなりません。 make installcheckは各試験スクリプトを実行し、結果出力が想定ファイルに一致するかどうか比較します。 何らかの差異はdiff -c書式でoutput_iso/regression.diffsに書き出されます。 想定ファイルがない試験を実行しようとすると問題として報告されます。 このためすべての想定ファイルがあることを確認してください。

TAP_TESTSはTAPテストの指定を有効にします。 各試験の実行によるデータはtmp_check/という名前のサブディレクトリに含まれます。 詳細は33.4を参照してください。

ヒント

想定ファイルを作成する最も簡単な方法は、空のファイルを作成し、試験を実行する(当然差異が報告されます)ことです。 (REGRESSの試験による)results/ディレクトリまたは(ISOLATIONの試験による)output_iso/results/ディレクトリ内で見つかる実際の結果ファイルを確認し、テストの想定結果と合致するのであれば、expected/にコピーしてください。