Postgresql 中文操作指南

38.18. Extension Building Infrastructure #

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

若要为扩展使用 PGXS 基础结构，您必须编写一个简单的 makefile。在 makefile 中，您需要设置一些变量并包括全局 PGXS makefile。下面是一个示例，它构建名为 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)

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

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

  • MODULES #

    • 从具有相同词根的源文件构建的共享库对象列表（此列表中不要包含库后缀）

  • MODULE_big #

    • 一个从多个源文件构建的共享库（在 OBJS 中列出对象文件）

  • PROGRAM #

    • 一个要构建的可执行程序（在 OBJS 中列出对象文件）

下列变量也可设置：

  • EXTENSION #

    • 扩展名；对于每个名称，你必须提供一个 extension.control_ file, which will be installed into _ 前缀_/share/extension_

  • MODULEDIR #

    • 子目录，DATA 和 DOCS 文件应该安装到此处（如果没有设置，则默认值是 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_ 下，其中 $MODULE 必须是 MODULES 或 MODULE_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 的链接行

  • SHLIB_LINK #

    • 将添加到 MODULE_big 的链接行

  • PG_CONFIG #

    • 指定 pg_config 程序的路径，用于与 PostgreSQL 安装进行构建（通常只需指定 pg_config，以使用 PATH 中的第一个程序）

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

您还可以在扩展程序源代码目录之外的目录中运行 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 构建的目录。执行此操作的一种方法是使用核心脚本 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 installcheck 使用 psql 执行每个测试脚本，并将产生的输出与匹配的预期文件进行比较。所有差异将以 diff -c 格式写入 regression.diffs 文件中。请注意，尝试运行缺少预期文件的测试将被报告为“问题”，因此请务必准备好所有预期文件。

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

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

Tip

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