38.17. 扩展大楼基础架构

如果您正在考虑分发 PostgreSQL 扩展模块，则为它们构建可移植的构建系统可能会非常困难。因此，PostgreSQL 安装提供了用于扩展的构建基础结构，称为 PGXS，因此可以简单地针对已安装的服务器构建简单的扩展模块。 PGXS 主要用于包含 C 代码的扩展，尽管它也可以用于纯 SQL 扩展。注意，PGXS 并不是一个通用的构建系统框架，可用于构建任何与 PostgreSQL 接口的软件。它只是简单地自动化了简单服务器扩展模块的通用构建规则。对于更复杂的软件包，您可能需要编写自己的构建系统。

要将 PGXS 基础结构用于扩展，必须编写一个简单的 makefile。在生成文件中，您需要设置一些变量并包括全局 PGXS 生成文件。这是一个构建名为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)

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

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

• MODULES

  • 从具有相同词干的源文件构建的共享库对象列表(此列表中不包括库后缀)

• MODULE_big

  • 从多个源文件构建的共享库(在OBJS中列出目标文件)

• PROGRAM

  • 要构建的可执行程序(在OBJS中列出目标文件)

也可以设置以下变量：

• EXTENSION

  • extensions；对于每个名称，您必须提供一个extension.control文件，该文件将安装到prefix/share/extension

• 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不同，clean目标不会删除HEADERS_built中的文件；如果要删除它们，也可以将它们添加到EXTRA_CLEAN或添加自己的规则来执行此操作。

• HEADERS_$MODULE
HEADERS_built_$MODULE

  • 要安装的文件(如果指定，则在构建后)在prefix/include/server/$MODULEDIR/$MODULE下，其中$MODULE必须是MODULES或MODULE_big中使用的模块名称。

与DATA_built不同，clean目标不会删除HEADERS_built_$MODULE中的文件；如果要删除它们，也可以将它们添加到EXTRA_CLEAN或添加自己的规则来执行此操作。

将两个变量用于同一模块或任意组合是合法的，除非您在MODULES列表中有两个模块名称，它们的唯一区别仅在于前缀built_，这会引起歧义。在这种情况下(希望不太可能)，您应该仅使用HEADERS_built_$MODULE变量。

• SCRIPTS

  • 脚本文件(不是二进制文件)安装到prefix/bin

• SCRIPTS_built

  • 要安装到prefix/bin的脚本文件(不是二进制文件)，需要首先构建

• REGRESS

  • 回归测试用例列表(无后缀)，请参见下文

• REGRESS_OPTS

  • 其他开关传递给 pg_regress

• 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

  • 用于 PostgreSQL 安装的 pg_config 程序的路径(通常使用pg_config来使用PATH中的第一个)

将此扩展文件作为Makefile放置在 extensions 所在的目录中。然后，您可以make进行编译，然后make install进行模块安装。默认情况下，extensions 是针对与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 构建设置目录。一种方法是使用核心脚本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/的子目录中。这些文件必须具有.sqlextensions，该 extensions 不能包含在 makefile 的REGRESS列表中。对于每个测试，还应该在名为expected/的子目录中有一个包含预期输出的文件，该文件具有相同的词干和 extensions.out。 make installcheck使用 psql 执行每个测试脚本，并将结果输出与匹配的预期文件进行比较。任何差异将以diff -c格式写入文件regression.diffs。请注意，尝试运行缺少预期文件的测试将报告为“麻烦”，因此请确保您拥有所有预期文件。