- publishing free software manuals
PostgreSQL Reference Manual - Volume 2 - Programming Guide
by The PostgreSQL Global Development Group
Paperback (6"x9"), 408 pages
ISBN 0954612035
RRP £19.95 ($34.95)

Sales of this book support the PostgreSQL project! Get a printed copy>>>

5.9.7 Extension Building Infrastructure

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. Note that this infrastructure is not intended to be a universal build system framework that can be used to build all software interfacing to PostgreSQL; it simply automates common build rules for simple server extension modules. For more complicated packages, you need to write your own build system.

To use the infrastructure for your extension, you must write a simple makefile. In that makefile, you need to set some variables and finally include the global PGXS makefile. Here is an example that builds an extension module named isbn_issn consisting of a shared library, an SQL script, and a documentation text file:

MODULES = isbn_issn
DATA_built = isbn_issn.sql
DOCS = README.isbn_issn

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

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

The following variables can be set:

MODULES
list of shared objects to be built from source file with same stem (do not include suffix in this list)
DATA
random files to install into prefix/share/contrib
DATA_built
random files to install into prefix/share/contrib, which need to be built first
DOCS
random files to install under prefix/doc/contrib
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

or at most one of these two:

PROGRAM
a binary program to build (list objects files in OBJS)
MODULE_big
a shared object to build (list object files in OBJS)

The following can also be set:

EXTRA_CLEAN
extra files to remove in make clean
PG_CPPFLAGS
will be added to CPPFLAGS
PG_LIBS
will be added to PROGRAM link line
SHLIB_LINK
will be added to MODULE_big link line

Put this makefile as Makefile in the directory which holds your extension. Then you can do make to compile, and later make install to install your module. The extension is compiled and installed for the PostgreSQL installation that corresponds to the first pg_config command found in your path.

The scripts listed in the REGRESS variable are used for regression testing of your module, just like make installcheck is used for the main PostgreSQL server. For this to work you need to have a subdirectory named sql/ in your extension's directory, within which you put one file for each group of tests you want to run. The files should have extension .sql, which should not be included in the REGRESS list in the makefile. For each test there should be a file containing the expected result in a subdirectory named expected/, with extension .out. The tests are run by executing make installcheck, and the resulting output will be compared to the expected files. The differences will be written to the file regression.diffs in diff -c format. Note that trying to run a test which is missing the expected file will be reported as “trouble”, so make sure you have all expected files.

Tip: The easiest way of creating the expected files is creating empty files, then carefully inspecting the result files after a test run (to be found in the results/ directory), and copying them to expected/ if they match what you want from the test.

ISBN 0954612035PostgreSQL Reference Manual - Volume 2 - Programming GuideSee the print edition