| Postgres-XC 1.2 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Chapter 34. Extending SQL | Fast Forward | Next |
Note: The following description applies both to Postgres-XC and PostgreSQL if not described explicitly. You can read PostgreSQL as Postgres-XC except for version number, which is specific to each product.
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. 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 PostgreSQL; 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 finally 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:
list of shared-library objects to be built from source files with same stem (do not include library suffixes in this list)
a shared library to build from multiple source files (list object files in OBJS)
an executable program to build (list object files in OBJS)
The following variables can also be set:
extension name(s); for each name you must provide an extension.control file, which will be installed into prefix/share/extension
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)
random files to install into prefix/share/$MODULEDIR
random files to install into prefix/share/$MODULEDIR, which need to be built first
random files to install under prefix/share/tsearch_data
random files to install under prefix/doc/$MODULEDIR
script files (not binaries) to install into prefix/bin
script files (not binaries) to install into prefix/bin, which need to be built first
list of regression test cases (without suffix), see below
additional switches to pass to pg_regress
extra files to remove in make clean
will be added to CPPFLAGS
will be added to PROGRAM link line
will be added to MODULE_big link line
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 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, 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.
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.