35.16. 扩展的构建基础设施

如果你正在考虑发布你的PostgreSQL扩展模块,为它们建立一个可移植的构建系统实在是相当困难。因此PostgreSQL安装为扩展提供了一种被称为PGXS构建基础设施,因此简单的扩展模块能够在一个已经安装的服务器上简单地编译。PGXS主要是为了包括 C 代码的扩展而设计,不过它也能用于纯 SQL 的扩展。注意PGXS并不想成为一种用于构建任何与PostgreSQL交互的软件的通用构建系统框架。它只是简单地把简单服务器扩展模块的公共构建规则自动化。对于更复杂的包,你可能需要编写你自己的构建系统。

要把PGXS基础设施用于你的扩展,你必须编写一个简单的 makefile。在这个 makefile 中,你需要设置一些变量并且最终把它们包括在全局的PGXS makefile 中。这里有一个例子,它构建一个名为isbn_issn的扩展模块,其中包括一个含有 C 代码的共享库、一个扩展控制文件、一个 SQL 脚本以及一个文档文件:

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

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

最后三行应该总是相同的。在这个文件的前面部分,你要对变量赋值或者增加自定义的make规则。

设置这三个变量之一来指定要构建什么:

MODULES

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

MODULE_big

一个要从多个源文件中构建的共享库(在OBJS中列出对象文件)

PROGRAM

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

还可以设置下列变量:

EXTENSION

扩展名称;你必须为每一个名称提供一个extension.control文件,它将被安装到prefix/share/extension

MODULEDIR

subdirectory of prefix/share的子目录,DATA 和 DOCS 文件会被安装到其中(如果没有设置,设置了EXTENSION时默认为extension,没有设置EXTENSION时默认为contrib

DATA

要安装到prefix/share/$MODULEDIR中的随机文件

DATA_built

要安装到prefix/share/$MODULEDIR中的随机文件,它们需要先被构建

DATA_TSEARCH

要安装到prefix/share/tsearch_data中的随机文件

DOCS

要安装到prefix/doc/$MODULEDIR中的随机文件

SCRIPTS

要安装到prefix/bin中的脚本文件(非二进制)

SCRIPTS_built

要安装到prefix/bin中的脚本文件(非二进制),它们需要先被构建

REGRESS

回归测试案例(不带后缀)的列表,见下文

REGRESS_OPTS

要传递给pg_regress的附加开关

EXTRA_CLEAN

要在make clean中移除的额外文件

PG_CPPFLAGS

将被加到CPPFLAGS

PG_LIBS

将被加到PROGRAM链接行

SHLIB_LINK

将被加到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程序来使用一个不同的安装。

Caution

改变PG_CONFIG只能在PostgreSQL 8.3 及其后的版本上工作。在更老的发行中,把它设置为除pg_config之外的任何东西都不会工作。你必须更改你的PATH来选择要在哪个安装中构建。

列举在REGRESS变量中的脚本会被用来对你的扩展进行回归测试,回归测试可以在做完make install之后用make installcheck调用。要让这能够工作,你必须已经有一个运行着的PostgreSQL服务器。列举在REGRESS中的脚本文件必须在你扩展目录的名为sql/的子目录中出现。这些文件必须带有扩展.sql,但扩展不能被包括在 makefile 的REGRESS列表中。对每一个测试还应该在名为expected/的子目录中有一个包含预期输出的文件,它具有和脚本文件相同的词干并带有扩展.outmake installcheck会用psql执行每一个测试脚本,并且将得到结果输出与相应的预期输出比较。任何区别都将以diff -c格式写入到文件regression.diffs中。注意尝试运行一个不带预期文件的测试将被报告为"故障",因此确保你拥有所有的预期文件。

Tip: 创建预期文件最简单的方法是创建空文件,然后做一次测试运行(这当然将报告区别)。检查在results/目录中找到的实际结果文件,如果它们符合你的预期则把它们复制到expected/中。