35.16. 扩展构建基础设施 #
如果你打算分发自己的 PostgreSQL 扩展模块,那么为它们搭建一个可移植的构建系统可能相当困难。因此,PostgreSQL 安装提供了一套称为 PGXS 的扩展构建基础设施,使简单的扩展模块可以针对已安装好的服务器直接构建。PGXS 主要面向包含 C 代码的扩展,不过它也能用于纯 SQL 扩展。注意,PGXS 并不打算成为一个可以用来构建任意与 PostgreSQL 交互软件的通用构建系统框架;它只是把简单服务器扩展模块的常见构建规则自动化。对于更复杂的软件包,你可能还是需要自己编写构建系统。
要使用PGXS基础设施构建扩展,必须编写一个简单的 makefile。在其中需要设置一些变量,并包含全局PGXSmakefile。下面的示例构建一个扩展模块,名为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.controlprefix/share/extensionMODULEDIR下的子目录,用于安装 DATA 和 DOCS 文件(若未设置,则在设置了prefix/shareEXTENSION时默认为extension,否则默认为contrib)DATA要安装到
的任意文件prefix/share/$MODULEDIRDATA_built要安装到
的任意文件,但它们需要先被构建prefix/share/$MODULEDIRDATA_TSEARCH要安装到
下的任意文件prefix/share/tsearch_dataDOCS要安装到
下的任意文件prefix/doc/$MODULEDIRSCRIPTS要安装到
的脚本文件(不是二进制文件)prefix/binSCRIPTS_built要安装到
的脚本文件(不是二进制文件),但它们需要先被构建prefix/binREGRESS回归测试用例列表(不带后缀),详见下文
REGRESS_OPTS传递给 pg_regress 的额外开关
EXTRA_CLEAN在
make clean中要额外删除的文件PG_CPPFLAGS将被添加到
CPPFLAGS前面PG_LIBS将被加入
PROGRAM的链接命令行SHLIB_LINK将被加入
MODULE_big的链接命令行PG_CONFIG要针对其进行构建的 PostgreSQL 安装所对应的 pg_config 程序路径(通常只写
pg_config,表示使用你PATH中找到的第一个)
把这个 makefile 命名为 Makefile,并放在保存扩展的目录中。然后你就可以执行 make 进行编译,再执行
make install 安装你的模块。默认情况下,该扩展会针对你 PATH 中找到的第一个
pg_config 所对应的
PostgreSQL 安装进行编译和安装。你也可以使用不同的安装,只需让 PG_CONFIG 指向它的
pg_config 程序,无论是在 makefile 中设置,还是在
make 命令行上设置都可以。
小心
更改 PG_CONFIG 只在针对 PostgreSQL 8.3 及更高版本构建时有效。对于更早的版本,把它设为 pg_config 以外的值都不起作用;你必须修改 PATH 来选择要针对其构建的安装。
在 REGRESS 变量中列出的脚本用于对模块做回归测试,可在执行完 make install 之后,通过
make installcheck 来运行。要让它工作,你必须有一个正在运行的 PostgreSQL 服务器。列在
REGRESS 中的脚本文件必须位于扩展目录下名为
sql/ 的子目录中。这些文件必须具有
.sql 扩展名,而该扩展名不能出现在 makefile 的
REGRESS 列表中。对于每个测试,还应在名为
expected/ 的子目录中有一个包含期望输出的文件,其主干名相同,扩展名为 .out。make installcheck 会用 psql
执行每个测试脚本,并把得到的输出与对应的期望文件比较。任何差异都会以
diff -c 格式写入
regression.diffs 文件。注意,如果尝试运行一个缺少期望文件的测试,将被报告为 “trouble”,所以请确保所有期望文件都已准备好。
提示
创建期望文件最简单的方法是先建立空文件,然后运行一次测试(当然这会报告差异)。检查 results/ 目录中的实际结果文件;如果它们与你对测试的预期一致,就把它们复制到 expected/ 中。