36.16. Extension Building Infrastructure
If you are thinking about distributing your Postgres Pro extension modules, setting up a portable build system for them can be fairly difficult. Therefore the Postgres Pro installation provides a build infrastructure for extensions, called PGXS, so that simple extension modules can be built simply against an already installed server. PGXS is mainly intended for extensions that include C code, although it can be used for pure-SQL extensions too. Note that PGXS is not intended to be a universal build system framework that can be used to build any software interfacing to Postgres Pro; it simply automates common build rules for simple server extension modules. For more complicated packages, you might need to write your own build system.
To use the PGXS infrastructure for your extension, you must write a simple makefile. In the makefile, you need to set some variables and include the global PGXS makefile. Here is an example that builds an extension module named isbn_issn
, consisting of a shared library containing some C code, an extension control file, a SQL script, and a documentation text file:
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)
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-library objects to be built from source files with same stem (do not include library suffixes in this list)
MODULE_big
a shared library to build from multiple source files (list object files in
OBJS
)PROGRAM
an executable program to build (list object files in
OBJS
)
The following variables can also be set:
EXTENSION
extension name(s); for each name you must provide an
file, which will be installed intoextension
.controlprefix
/share/extensionMODULEDIR
subdirectory of
into which DATA and DOCS files should be installed (if not set, default isprefix
/shareextension
ifEXTENSION
is set, orcontrib
if not)DATA
random files to install into
prefix
/share/$MODULEDIRDATA_built
random files to install into
, which need to be built firstprefix
/share/$MODULEDIRDATA_TSEARCH
random files to install under
prefix
/share/tsearch_dataDOCS
random files to install under
prefix
/doc/$MODULEDIRSCRIPTS
script files (not binaries) to install into
prefix
/binSCRIPTS_built
script files (not binaries) to install into
, which need to be built firstprefix
/binREGRESS
list of regression test cases (without suffix), see below
REGRESS_OPTS
additional switches to pass to pg_regress
EXTRA_CLEAN
extra files to remove in
make clean
PG_CPPFLAGS
will be prepended to
CPPFLAGS
PG_CFLAGS
will be appended to
CFLAGS
PG_CXXFLAGS
will be appended to
CXXFLAGS
PG_LDFLAGS
will be prepended to
LDFLAGS
PG_LIBS
will be added to
PROGRAM
link lineSHLIB_LINK
will be added to
MODULE_big
link linePG_CONFIG
path to pg_config program for the Postgres Pro installation to build against (typically just
pg_config
to use the first one in yourPATH
)
Put this makefile as Makefile
in the directory which holds your extension. Then you can do make
to compile, and then make install
to install your module. By default, the extension is compiled and installed for the Postgres Pro 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.
You can also run make
in a directory outside the source tree of your extension, if you want to keep the build directory separate. This procedure is also called a VPATH build. Here's how:
mkdir build_dir cd build_dir make -f /path/to/extension/source/tree/Makefile make -f /path/to/extension/source/tree/Makefile install
Alternatively, you can set up a directory for a VPATH build in a similar way to how it is done for the core code. One way to do this is using the core script config/prep_buildtree
. Once this has been done you can build by setting the make
variable VPATH
like this:
make VPATH=/path/to/extension/source/tree make VPATH=/path/to/extension/source/tree install
This procedure can work with a greater variety of directory layouts.
The scripts listed in the REGRESS
variable are used for regression testing of your module, which can be invoked by make installcheck
after doing make install
. For this to work you must have a running Postgres Pro server. The script files listed in REGRESS
must appear in a subdirectory named sql/
in your extension's directory. These files must have extension .sql
, which must not be included in the REGRESS
list in the makefile. For each test there should also be a file containing the expected output in a subdirectory named expected/
, with the same stem and extension .out
. make installcheck
executes each test script with psql, and compares the resulting output to the matching expected file. Any differences will be written to the file regression.diffs
in diff -c
format. Note that trying to run a test that is missing its expected file will be reported as “trouble”, so make sure you have all expected files.
Tip
The easiest way to create the expected files is to create empty files, then do a test run (which will of course report differences). Inspect the actual result files found in the results/
directory, then copy them to expected/
if they match what you expect from the test.