The PostgreSQL 9.0 Reference Manual - Volume 2 - Programming Guide by The PostgreSQL Global Development Group Paperback (6"x9"), 478 pages ISBN 9781906966065 RRP £14.95 ($19.95) Sales of this book support the PostgreSQL project! Get a printed copy>>>

PostgreSQL 9.0 Reference Manual Volume 2 Buy the book here! >>> support free software

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

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

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

Set one of these three variables to specify what is built:

MODULES

list of shared objects to be built from source files with same stem (do not include suffix in this list)

MODULE_big

a shared object to build from multiple source files (list object files in OBJS)

PROGRAM

a binary program to build (list object files in OBJS)

The following variables can also be set:

MODULEDIR

subdirectory into which DATA and DOCS files should be installed (if not set, default is contrib)

DATA

random files to install into prefix/share/$MODULEDIR

DATA_built

random files to install into prefix/share/$MODULEDIR, which need to be built first

DATA_TSEARCH

random files to install under prefix/share/tsearch_data

DOCS

random files to install under prefix/doc/$MODULEDIR

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

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

PG_CONFIG

path to pg_config program for the PostgreSQL installation to build against (typically just pg_config to use the first one in your PATH)

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. By default, the extension is compiled and installed for the PostgreSQL installation that corresponds to the first pg_config program found in your path. You can use a different installation by setting PG_CONFIG to point to its pg_config program, either within the makefile or on the make command line.

Caution: Changing PG_CONFIG only works when building against PostgreSQL 8.3 or later. With older releases it does not work to set it to anything except pg_config; you must alter your PATH to select the installation to build against.

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.