begriffs open source - ai-pg/blob - full-docs/txt/extend-pgxs.txt

   1
   2 36.18. Extension Building Infrastructure #
   3
   4    If you are thinking about distributing your PostgreSQL extension
   5    modules, setting up a portable build system for them can be fairly
   6    difficult. Therefore the PostgreSQL installation provides a build
   7    infrastructure for extensions, called PGXS, so that simple extension
   8    modules can be built simply against an already installed server. PGXS
   9    is mainly intended for extensions that include C code, although it can
  10    be used for pure-SQL extensions too. Note that PGXS is not intended to
  11    be a universal build system framework that can be used to build any
  12    software interfacing to PostgreSQL; it simply automates common build
  13    rules for simple server extension modules. For more complicated
  14    packages, you might need to write your own build system.
  15
  16    To use the PGXS infrastructure for your extension, you must write a
  17    simple makefile. In the makefile, you need to set some variables and
  18    include the global PGXS makefile. Here is an example that builds an
  19    extension module named isbn_issn, consisting of a shared library
  20    containing some C code, an extension control file, an SQL script, an
  21    include file (only needed if other modules might need to access the
  22    extension functions without going via SQL), and a documentation text
  23    file:
  24 MODULES = isbn_issn
  25 EXTENSION = isbn_issn
  26 DATA = isbn_issn--1.0.sql
  27 DOCS = README.isbn_issn
  28 HEADERS_isbn_issn = isbn_issn.h
  29
  30 PG_CONFIG = pg_config
  31 PGXS := $(shell $(PG_CONFIG) --pgxs)
  32 include $(PGXS)
  33
  34    The last three lines should always be the same. Earlier in the file,
  35    you assign variables or add custom make rules.
  36
  37    Set one of these three variables to specify what is built:
  38
  39    MODULES #
  40           list of shared-library objects to be built from source files
  41           with same stem (do not include library suffixes in this list)
  42
  43    MODULE_big #
  44           a shared library to build from multiple source files (list
  45           object files in OBJS)
  46
  47    PROGRAM #
  48           an executable program to build (list object files in OBJS)
  49
  50    The following variables can also be set:
  51
  52    EXTENSION #
  53           extension name(s); for each name you must provide an
  54           extension.control file, which will be installed into
  55           prefix/share/extension
  56
  57    MODULEDIR #
  58           subdirectory of prefix/share into which DATA and DOCS files
  59           should be installed (if not set, default is extension if
  60           EXTENSION is set, or contrib if not)
  61
  62    DATA #
  63           random files to install into prefix/share/$MODULEDIR
  64
  65    DATA_built #
  66           random files to install into prefix/share/$MODULEDIR, which need
  67           to be built first
  68
  69    DATA_TSEARCH #
  70           random files to install under prefix/share/tsearch_data
  71
  72    DOCS #
  73           random files to install under prefix/doc/$MODULEDIR
  74
  75    HEADERS
  76           HEADERS_built #
  77           Files to (optionally build and) install under
  78           prefix/include/server/$MODULEDIR/$MODULE_big.
  79
  80           Unlike DATA_built, files in HEADERS_built are not removed by the
  81           clean target; if you want them removed, also add them to
  82           EXTRA_CLEAN or add your own rules to do it.
  83
  84    HEADERS_$MODULE
  85           HEADERS_built_$MODULE #
  86           Files to install (after building if specified) under
  87           prefix/include/server/$MODULEDIR/$MODULE, where $MODULE must be
  88           a module name used in MODULES or MODULE_big.
  89
  90           Unlike DATA_built, files in HEADERS_built_$MODULE are not
  91           removed by the clean target; if you want them removed, also add
  92           them to EXTRA_CLEAN or add your own rules to do it.
  93
  94           It is legal to use both variables for the same module, or any
  95           combination, unless you have two module names in the MODULES
  96           list that differ only by the presence of a prefix built_, which
  97           would cause ambiguity. In that (hopefully unlikely) case, you
  98           should use only the HEADERS_built_$MODULE variables.
  99
 100    SCRIPTS #
 101           script files (not binaries) to install into prefix/bin
 102
 103    SCRIPTS_built #
 104           script files (not binaries) to install into prefix/bin, which
 105           need to be built first
 106
 107    REGRESS #
 108           list of regression test cases (without suffix), see below
 109
 110    REGRESS_OPTS #
 111           additional switches to pass to pg_regress
 112
 113    ISOLATION #
 114           list of isolation test cases, see below for more details
 115
 116    ISOLATION_OPTS #
 117           additional switches to pass to pg_isolation_regress
 118
 119    TAP_TESTS #
 120           switch defining if TAP tests need to be run, see below
 121
 122    NO_INSTALL #
 123           don't define an install target, useful for test modules that
 124           don't need their build products to be installed
 125
 126    NO_INSTALLCHECK #
 127           don't define an installcheck target, useful e.g., if tests
 128           require special configuration, or don't use pg_regress
 129
 130    EXTRA_CLEAN #
 131           extra files to remove in make clean
 132
 133    PG_CPPFLAGS #
 134           will be prepended to CPPFLAGS
 135
 136    PG_CFLAGS #
 137           will be appended to CFLAGS
 138
 139    PG_CXXFLAGS #
 140           will be appended to CXXFLAGS
 141
 142    PG_LDFLAGS #
 143           will be prepended to LDFLAGS
 144
 145    PG_LIBS #
 146           will be added to PROGRAM link line
 147
 148    SHLIB_LINK #
 149           will be added to MODULE_big link line
 150
 151    PG_CONFIG #
 152           path to pg_config program for the PostgreSQL installation to
 153           build against (typically just pg_config to use the first one in
 154           your PATH)
 155
 156    Put this makefile as Makefile in the directory which holds your
 157    extension. Then you can do make to compile, and then make install to
 158    install your module. By default, the extension is compiled and
 159    installed for the PostgreSQL installation that corresponds to the first
 160    pg_config program found in your PATH. You can use a different
 161    installation by setting PG_CONFIG to point to its pg_config program,
 162    either within the makefile or on the make command line.
 163
 164    You can select a separate directory prefix in which to install your
 165    extension's files, by setting the make variable prefix when executing
 166    make install like so:
 167 make install prefix=/usr/local/postgresql
 168
 169    This will install the extension control and SQL files into
 170    /usr/local/postgresql/share and the shared modules into
 171    /usr/local/postgresql/lib. If the prefix does not include the strings
 172    postgres or pgsql, such as
 173 make install prefix=/usr/local/extras
 174
 175    then postgresql will be appended to the directory names, installing the
 176    control and SQL files into /usr/local/extras/share/postgresql/extension
 177    and the shared modules into /usr/local/extras/lib/postgresql. Either
 178    way, you'll need to set extension_control_path and dynamic_library_path
 179    to enable the PostgreSQL server to find the files:
 180 extension_control_path = '/usr/local/extras/share/postgresql:$system'
 181 dynamic_library_path = '/usr/local/extras/lib/postgresql:$libdir'
 182
 183    You can also run make in a directory outside the source tree of your
 184    extension, if you want to keep the build directory separate. This
 185    procedure is also called a VPATH build. Here's how:
 186 mkdir build_dir
 187 cd build_dir
 188 make -f /path/to/extension/source/tree/Makefile
 189 make -f /path/to/extension/source/tree/Makefile install
 190
 191    Alternatively, you can set up a directory for a VPATH build in a
 192    similar way to how it is done for the core code. One way to do this is
 193    using the core script config/prep_buildtree. Once this has been done
 194    you can build by setting the make variable VPATH like this:
 195 make VPATH=/path/to/extension/source/tree
 196 make VPATH=/path/to/extension/source/tree install
 197
 198    This procedure can work with a greater variety of directory layouts.
 199
 200    The scripts listed in the REGRESS variable are used for regression
 201    testing of your module, which can be invoked by make installcheck after
 202    doing make install. For this to work you must have a running PostgreSQL
 203    server. The script files listed in REGRESS must appear in a
 204    subdirectory named sql/ in your extension's directory. These files must
 205    have extension .sql, which must not be included in the REGRESS list in
 206    the makefile. For each test there should also be a file containing the
 207    expected output in a subdirectory named expected/, with the same stem
 208    and extension .out. make installcheck executes each test script with
 209    psql, and compares the resulting output to the matching expected file.
 210    Any differences will be written to the file regression.diffs in diff -c
 211    format. Note that trying to run a test that is missing its expected
 212    file will be reported as “trouble”, so make sure you have all expected
 213    files.
 214
 215    The scripts listed in the ISOLATION variable are used for tests
 216    stressing behavior of concurrent session with your module, which can be
 217    invoked by make installcheck after doing make install. For this to work
 218    you must have a running PostgreSQL server. The script files listed in
 219    ISOLATION must appear in a subdirectory named specs/ in your
 220    extension's directory. These files must have extension .spec, which
 221    must not be included in the ISOLATION list in the makefile. For each
 222    test there should also be a file containing the expected output in a
 223    subdirectory named expected/, with the same stem and extension .out.
 224    make installcheck executes each test script, and compares the resulting
 225    output to the matching expected file. Any differences will be written
 226    to the file output_iso/regression.diffs in diff -c format. Note that
 227    trying to run a test that is missing its expected file will be reported
 228    as “trouble”, so make sure you have all expected files.
 229
 230    TAP_TESTS enables the use of TAP tests. Data from each run is present
 231    in a subdirectory named tmp_check/. See also Section 31.4 for more
 232    details.
 233
 234 Tip
 235
 236    The easiest way to create the expected files is to create empty files,
 237    then do a test run (which will of course report differences). Inspect
 238    the actual result files found in the results/ directory (for tests in
 239    REGRESS), or output_iso/results/ directory (for tests in ISOLATION),
 240    then copy them to expected/ if they match what you expect from the
 241    test.