36.18. 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, an SQL script, an include file (only needed if other modules might need to access the extension functions without going via SQL), and a documentation text file:
MODULES = isbn_issn EXTENSION = isbn_issn DATA = isbn_issn--1.0.sql DOCS = README.isbn_issn HEADERS_isbn_issn = isbn_issn.h 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:
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/$MODULEDIRHEADERS
HEADERS_built
#Files to (optionally build and) install under
.prefix
/include/server/$MODULEDIR/$MODULE_bigUnlike
DATA_built
, files inHEADERS_built
are not removed by theclean
target; if you want them removed, also add them toEXTRA_CLEAN
or add your own rules to do it.HEADERS_$MODULE
HEADERS_built_$MODULE
#Files to install (after building if specified) under
, whereprefix
/include/server/$MODULEDIR/$MODULE$MODULE
must be a module name used inMODULES
orMODULE_big
.Unlike
DATA_built
, files inHEADERS_built_$MODULE
are not removed by theclean
target; if you want them removed, also add them toEXTRA_CLEAN
or add your own rules to do it.It is legal to use both variables for the same module, or any combination, unless you have two module names in the
MODULES
list that differ only by the presence of a prefixbuilt_
, which would cause ambiguity. In that (hopefully unlikely) case, you should use only theHEADERS_built_$MODULE
variables.SCRIPTS
#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
ISOLATION
#list of isolation test cases, see below for more details
ISOLATION_OPTS
#additional switches to pass to pg_isolation_regress
TAP_TESTS
#switch defining if TAP tests need to be run, see below
NO_INSTALL
#don't define an
install
target, useful for test modules that don't need their build products to be installedNO_INSTALLCHECK
#don't define an
installcheck
target, useful e.g., if tests require special configuration, or don't use pg_regressEXTRA_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.
The scripts listed in the ISOLATION
variable are used for tests stressing behavior of concurrent session with 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 ISOLATION
must appear in a subdirectory named specs/
in your extension's directory. These files must have extension .spec
, which must not be included in the ISOLATION
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, and compares the resulting output to the matching expected file. Any differences will be written to the file output_iso/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.
TAP_TESTS
enables the use of TAP tests. Data from each run is present in a subdirectory named tmp_check/
.
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 (for tests in REGRESS
), or output_iso/results/
directory (for tests in ISOLATION
), then copy them to expected/
if they match what you expect from the test.