37.18. Extension Building Infrastructure

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 , consisting of a shared library containing some C code, an extension control file, a 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:

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 extension.control file, which will be installed into prefix/share/extensionMODULEDIR

subdirectory of prefix/share into which DATA and DOCS files should be installed (if not set, default is extension if EXTENSION is set, or contrib if not)DATA

random files to install into prefix/share/$MODULEDIRDATA_built

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

random files to install under prefix/share/tsearch_dataDOCS

random files to install under prefix/doc/$MODULEDIRHEADERS
HEADERS_built

Unlike DATA_built, files in HEADERS_built are not removed by the clean target; if you want them removed, also add them to EXTRA_CLEAN or add your own rules to do it.HEADERS_$MODULE
HEADERS_built_$MODULE

Files to install (after building if specified) under prefix/include/server/$MODULEDIR/$MODULE, where $MODULE must be a module name used in MODULES or MODULE_big.

Unlike DATA_built, files in are not removed by the clean target; if you want them removed, also add them to EXTRA_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 prefix built_, which would cause ambiguity. In that (hopefully unlikely) case, you should use only the HEADERS_built_$MODULE variables.SCRIPTS

script files (not binaries) to install into prefix/binSCRIPTS_built

script files (not binaries) to install into prefix/bin, which need to be built firstREGRESS

list of regression test cases (without suffix), see belowREGRESS_OPTS

additional switches to pass to pg_regressISOLATION

list of isolation test cases, see below for more detailsISOLATION_OPTS

additional switches to pass to pg_isolation_regressTAP_TESTS

switch defining if TAP tests need to be run, see belowNO_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 cleanPG_CPPFLAGS

will be appended to CFLAGSPG_CXXFLAGS

will be appended to CXXFLAGSPG_LDFLAGS

will be prepended to LDFLAGSPG_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 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 then 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 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:

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:

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 PostgreSQL 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 PostgreSQL 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/. See also Section 32.4 for more details.

Tip