Postgresql 中文操作指南

38.18. Extension Building Infrastructure #

如果您考虑分发 PostgreSQL 延伸模块，为它们设置一个可移植的构建系统可能相当困难。因此，PostgreSQL 安装提供了一个用于扩展的构建基础结构，称为 PGXS，以便能够基于已经安装的服务器轻松地构建简单扩展模块。PGXS 主要适用于包含 C 代码的扩展，尽管它也可用于纯 SQL 扩展。请注意，PGXS 并不是一个可以用来构建任何与 PostgreSQL 接口的软件的通用构建系统框架；它只是自动执行简单服务器扩展模块的常见构建规则。对于更为复杂的软件包，您可能需要编写自己的构建系统。

If you are thinking about distributing your PostgreSQL extension modules, setting up a portable build system for them can be fairly difficult. Therefore the PostgreSQL installation provides a build infrastructure for extensions, called PGXS, so that simple extension modules can be built simply against an already installed server. PGXS is mainly intended for extensions that include C code, although it can be used for pure-SQL extensions too. Note that PGXS is not intended to be a universal build system framework that can be used to build any software interfacing to PostgreSQL; it simply automates common build rules for simple server extension modules. For more complicated packages, you might need to write your own build system.

若要为扩展使用 PGXS 基础结构，您必须编写一个简单的 makefile。在 makefile 中，您需要设置一些变量并包括全局 PGXS makefile。下面是一个示例，它构建名为 isbn_issn 的扩展模块，该模块包含一个包含一些 C 代码的共享库、一个扩展控制文件、一个 SQL 脚本、一个包含文件（仅在其他模块可能需要访问扩展函数而不通过 SQL 进行的情况下需要）和一个文档文本文件：

To use the PGXS infrastructure for your extension, you must write a simple makefile. In the makefile, you need to set some variables and include the global PGXS makefile. Here is an example that builds an extension module named isbn_issn, consisting of a shared library containing some C code, an extension control file, an SQL script, an include file (only needed if other modules might need to access the extension functions without going via SQL), and a documentation text file:

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)

最后三行应始终相同。在文件前面，您分配变量或添加自定义 make 规则。

The last three lines should always be the same. Earlier in the file, you assign variables or add custom make rules.

设置这三个变量中的一个以指定要构建的内容：

Set one of these three variables to specify what is built:

  • MODULES #

    • list of shared-library objects to be built from source files with same stem (do not include library suffixes in this list)

  • MODULE_big #

    • a shared library to build from multiple source files (list object files in OBJS)

  • PROGRAM #

    • an executable program to build (list object files in OBJS)

下列变量也可设置：

The following variables can also be set:

  • EXTENSION #

    • extension name(s); for each name you must provide an extension_.control_ file, which will be installed into prefix_/share/extension_

  • MODULEDIR #

    • subdirectory of _prefix/share_ into which DATA and DOCS files should be installed (if not set, default is extension if EXTENSION is set, or contrib if not)

  • DATA #

    • random files to install into _prefix/share/$MODULEDIR_

  • DATA_built #

    • random files to install into _prefix/share/$MODULEDIR_, which need to be built first

  • DATA_TSEARCH #

    • random files to install under _prefix/share/tsearch_data_

  • DOCS #

    • random files to install under _prefix/doc/$MODULEDIR_

  • HEADERS__HEADERS_built #

    • Files to (optionally build and) install under _prefix/include/server/$MODULEDIR/$MODULE_big_.

    • Unlike DATA_built, files in HEADERS_built are not removed by the clean target; if you want them removed, also add them to EXTRA_CLEAN or add your own rules to do it.

  • HEADERS$MODULE__HEADERS_built_$MODULE_ #

    • Files to install (after building if specified) under _prefix/include/server/$MODULEDIR/$MODULE_, where $MODULE must be a module name used in MODULES or MODULE_big.

    • Unlike DATA_built, files in HEADERS_built$MODULE_ are not removed by the clean target; if you want them removed, also add them to EXTRA_CLEAN or add your own rules to do it.

    • It is legal to use both variables for the same module, or any combination, unless you have two module names in the MODULES list that differ only by the presence of a prefix built_, which would cause ambiguity. In that (hopefully unlikely) case, you should use only the HEADERS_built$MODULE_ variables.

  • SCRIPTS #

    • script files (not binaries) to install into _prefix/bin_

  • SCRIPTS_built #

    • script files (not binaries) to install into _prefix/bin_, which need to be built first

  • REGRESS #

    • list of regression test cases (without suffix), see below

  • REGRESS_OPTS #

    • additional switches to pass to pg_regress

  • ISOLATION #

    • list of isolation test cases, see below for more details

  • ISOLATION_OPTS #

    • additional switches to pass to pg_isolation_regress

  • TAP_TESTS #

    • switch defining if TAP tests need to be run, see below

  • NO_INSTALL #

    • don’t define an install target, useful for test modules that don’t need their build products to be installed

  • NO_INSTALLCHECK #

    • don’t define an installcheck target, useful e.g., if tests require special configuration, or don’t use pg_regress

  • EXTRA_CLEAN #

    • extra files to remove in make clean

  • PG_CPPFLAGS #

    • will be prepended to CPPFLAGS

  • PG_CFLAGS #

    • will be appended to CFLAGS

  • PG_CXXFLAGS #

    • will be appended to CXXFLAGS

  • PG_LDFLAGS #

    • will be prepended to LDFLAGS

  • PG_LIBS #

    • will be added to PROGRAM link line

  • SHLIB_LINK #

    • will be added to MODULE_big link line

  • PG_CONFIG #

    • path to pg_config program for the PostgreSQL installation to build against (typically just pg_config to use the first one in your PATH)

将此 Makefile 作为 Makefile 文件放在包含您的扩展程序的目录中。然后，您可以执行 make 命令进行编译，然后执行 make install 命令安装模块。默认情况下，扩展程序将针对与 pg_config 程序对应的 PostgreSQL 安装进行编译和安装，该程序首先在 PATH 中找到。您可以使用不同的安装，方法是设置 PG_CONFIG 指向其 pg_config 程序，可以在 Makefile 文件内进行设置，也可以在 make 命令行中进行设置。

Put this makefile as Makefile in the directory which holds your extension. Then you can do make to compile, and then make install to install your module. By default, the extension is compiled and installed for the PostgreSQL installation that corresponds to the first pg_config program found in your PATH. You can use a different installation by setting PG_CONFIG to point to its pg_config program, either within the makefile or on the make command line.

您还可以在扩展程序源代码目录之外的目录中运行 make，如果您想要将构建目录分离开来。此过程也称为 VPATH 构建。以下是方法：

You can also run make in a directory outside the source tree of your extension, if you want to keep the build directory separate. This procedure is also called a VPATH build. Here’s how:

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

或者，您可以按照核心代码执行的方式设置 VPATH 构建的目录。执行此操作的一种方法是使用核心脚本 config/prep_buildtree。完成此操作后，您可以设置 make 变量 VPATH 来构建：

Alternatively, you can set up a directory for a VPATH build in a similar way to how it is done for the core code. One way to do this is using the core script config/prep_buildtree. Once this has been done you can build by setting the make variable VPATH like this:

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

该过程适用于更多不同的目录布局。

This procedure can work with a greater variety of directory layouts.

在 REGRESS 变量中列出的脚本用于回归测试模块，可以在执行 make install 命令后调用 make installcheck 来运行该脚本。要使该过程能够正常运行，必须运行 PostgreSQL 服务器。在 REGRESS 中列出的脚本文件必须出现在扩展程序目录中名为 sql/ 的子目录中。这些文件必须使用 .sql 扩展名，且该扩展名不能包含在 Makefile 中 REGRESS 列表中。对于每个测试，还应当在名为 expected/ 的子目录中放置一个包含预期输出的文件，并使用相同的词干和 .out 扩展名。make installcheck 使用 psql 执行每个测试脚本，并将产生的输出与匹配的预期文件进行比较。所有差异将以 diff -c 格式写入 regression.diffs 文件中。请注意，尝试运行缺少预期文件的测试将被报告为“问题”，因此请务必准备好所有预期文件。

The scripts listed in the REGRESS variable are used for regression testing of your module, which can be invoked by make installcheck after doing make install. For this to work you must have a running PostgreSQL server. The script files listed in REGRESS must appear in a subdirectory named sql/ in your extension’s directory. These files must have extension .sql, which must not be included in the REGRESS list in the makefile. For each test there should also be a file containing the expected output in a subdirectory named expected/, with the same stem and extension .out. make installcheck executes each test script with psql, and compares the resulting output to the matching expected file. Any differences will be written to the file regression.diffs in diff -c format. Note that trying to run a test that is missing its expected file will be reported as “trouble”, so make sure you have all expected files.

ISOLATION 变量中列出的脚本用于测试强调了与模块并发运行的会话的行为，通过 make installcheck 完成 make install 之后可以调用这些脚本。为此，您的计算机上必须有一个正在运行的 PostgreSQL 服务器。ISOLATION 中列出的脚本文件必须出现在一个名为 specs/ 的子目录中，该子目录位于扩展目录中。这些文件必须具有扩展名 .spec，并且不可包含在 makefile 中的 ISOLATION 列表中。对于每个测试，还应该有一个包含预期输出的文件，该文件位于一个名为 expected/ 的子目录中，且具有相同的词干和扩展名 .out。 make installcheck 执行每个测试脚本，并将生成的结果与匹配的预期文件进行比较。任何差异都将以 output_iso/regression.diffs 格式写入文件 diff -c 中。请注意，系统将尝试运行一个缺少其预期文件的测试报告为“故障”，因此请确保已准备好所有预期文件。

The scripts listed in the ISOLATION variable are used for tests stressing behavior of concurrent session with your module, which can be invoked by make installcheck after doing make install. For this to work you must have a running PostgreSQL server. The script files listed in ISOLATION must appear in a subdirectory named specs/ in your extension’s directory. These files must have extension .spec, which must not be included in the ISOLATION list in the makefile. For each test there should also be a file containing the expected output in a subdirectory named expected/, with the same stem and extension .out. make installcheck executes each test script, and compares the resulting output to the matching expected file. Any differences will be written to the file output_iso/regression.diffs in diff -c format. Note that trying to run a test that is missing its expected file will be reported as “trouble”, so make sure you have all expected files.

_TAP_TESTS_启用使用 TAP 测试。每次运行的数据都会存在于名为 _tmp_check/_的子目录中。有关更多详细信息，另请参见 Section 33.4。

TAP_TESTS enables the use of TAP tests. Data from each run is present in a subdirectory named tmp_check/. See also Section 33.4 for more details.

Tip

创建预期文件的最简单方法是创建空文件，然后进行测试运行（这当然会报告差异）。检查 results/ 目录（用于 REGRESS 中的测试）或 output_iso/results/ 目录（用于 ISOLATION 中的测试）中找到的实际结果文件，然后将其复制到 expected/，如果它们与您对该测试的预期相符。

The easiest way to create the expected files is to create empty files, then do a test run (which will of course report differences). Inspect the actual result files found in the results/ directory (for tests in REGRESS), or output_iso/results/ directory (for tests in ISOLATION), then copy them to expected/ if they match what you expect from the test.