begriffs open source - ai-pg/blob - full-docs/src/sgml/html/extend-pgxs.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>36.18. Extension Building Infrastructure</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend-extensions.html" title="36.17. Packaging Related Objects into an Extension" /><link rel="next" href="triggers.html" title="Chapter 37. Triggers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.18. Extension Building Infrastructure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-extensions.html" title="36.17. Packaging Related Objects into an Extension">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 36. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 36. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 37. Triggers">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTEND-PGXS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.18. Extension Building Infrastructure <a href="#EXTEND-PGXS" class="id_link">#</a></h2></div></div></div><a id="id-1.8.3.21.2" class="indexterm"></a><p>
   3     If you are thinking about distributing your
   4     <span class="productname">PostgreSQL</span> extension modules, setting up a
   5     portable build system for them can be fairly difficult.  Therefore
   6     the <span class="productname">PostgreSQL</span> installation provides a build
   7     infrastructure for extensions, called <acronym class="acronym">PGXS</acronym>, so
   8     that simple extension modules can be built simply against an
   9     already installed server.  <acronym class="acronym">PGXS</acronym> is mainly intended
  10     for extensions that include C code, although it can be used for
  11     pure-SQL extensions too.  Note that <acronym class="acronym">PGXS</acronym> is not
  12     intended to be a universal build system framework that can be used
  13     to build any software interfacing to <span class="productname">PostgreSQL</span>;
  14     it simply automates common build rules for simple server extension
  15     modules.  For more complicated packages, you might need to write your
  16     own build system.
  17    </p><p>
  18     To use the <acronym class="acronym">PGXS</acronym> infrastructure for your extension,
  19     you must write a simple makefile.
  20     In the makefile, you need to set some variables
  21     and include the global <acronym class="acronym">PGXS</acronym> makefile.
  22     Here is an example that builds an extension module named
  23     <code class="literal">isbn_issn</code>, consisting of a shared library containing
  24     some C code, an extension control file, an SQL script, an include file
  25     (only needed if other modules might need to access the extension functions
  26     without going via SQL), and a documentation text file:
  27 </p><pre class="programlisting">
  28 MODULES = isbn_issn
  29 EXTENSION = isbn_issn
  30 DATA = isbn_issn--1.0.sql
  31 DOCS = README.isbn_issn
  32 HEADERS_isbn_issn = isbn_issn.h
  33
  34 PG_CONFIG = pg_config
  35 PGXS := $(shell $(PG_CONFIG) --pgxs)
  36 include $(PGXS)
  37 </pre><p>
  38     The last three lines should always be the same.  Earlier in the
  39     file, you assign variables or add custom
  40     <span class="application">make</span> rules.
  41    </p><p>
  42     Set one of these three variables to specify what is built:
  43
  44     </p><div class="variablelist"><dl class="variablelist"><dt id="EXTEND-PGXS-MODULES"><span class="term"><code class="varname">MODULES</code></span> <a href="#EXTEND-PGXS-MODULES" class="id_link">#</a></dt><dd><p>
  45         list of shared-library objects to be built from source files with same
  46         stem (do not include library suffixes in this list)
  47        </p></dd><dt id="EXTEND-PGXS-MODULE-BIG"><span class="term"><code class="varname">MODULE_big</code></span> <a href="#EXTEND-PGXS-MODULE-BIG" class="id_link">#</a></dt><dd><p>
  48         a shared library to build from multiple source files
  49         (list object files in <code class="varname">OBJS</code>)
  50        </p></dd><dt id="EXTEND-PGXS-PROGRAM"><span class="term"><code class="varname">PROGRAM</code></span> <a href="#EXTEND-PGXS-PROGRAM" class="id_link">#</a></dt><dd><p>
  51         an executable program to build
  52         (list object files in <code class="varname">OBJS</code>)
  53        </p></dd></dl></div><p>
  54
  55     The following variables can also be set:
  56
  57     </p><div class="variablelist"><dl class="variablelist"><dt id="EXTEND-PGXS-EXTENSION"><span class="term"><code class="varname">EXTENSION</code></span> <a href="#EXTEND-PGXS-EXTENSION" class="id_link">#</a></dt><dd><p>
  58         extension name(s); for each name you must provide an
  59         <code class="literal"><em class="replaceable"><code>extension</code></em>.control</code> file,
  60         which will be installed into
  61         <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/extension</code>
  62        </p></dd><dt id="EXTEND-PGXS-MODULEDIR"><span class="term"><code class="varname">MODULEDIR</code></span> <a href="#EXTEND-PGXS-MODULEDIR" class="id_link">#</a></dt><dd><p>
  63         subdirectory of <code class="literal"><em class="replaceable"><code>prefix</code></em>/share</code>
  64         into which DATA and DOCS files should be installed
  65         (if not set, default is <code class="literal">extension</code> if
  66         <code class="varname">EXTENSION</code> is set,
  67         or <code class="literal">contrib</code> if not)
  68        </p></dd><dt id="EXTEND-PGXS-DATA"><span class="term"><code class="varname">DATA</code></span> <a href="#EXTEND-PGXS-DATA" class="id_link">#</a></dt><dd><p>
  69         random files to install into <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>
  70        </p></dd><dt id="EXTEND-PGXS-DATA-BUILT"><span class="term"><code class="varname">DATA_built</code></span> <a href="#EXTEND-PGXS-DATA-BUILT" class="id_link">#</a></dt><dd><p>
  71         random files to install into
  72         <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>,
  73         which need to be built first
  74        </p></dd><dt id="EXTEND-PGXS-DATA-TSEARCH"><span class="term"><code class="varname">DATA_TSEARCH</code></span> <a href="#EXTEND-PGXS-DATA-TSEARCH" class="id_link">#</a></dt><dd><p>
  75         random files to install under
  76         <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/tsearch_data</code>
  77        </p></dd><dt id="EXTEND-PGXS-DOCS"><span class="term"><code class="varname">DOCS</code></span> <a href="#EXTEND-PGXS-DOCS" class="id_link">#</a></dt><dd><p>
  78         random files to install under
  79         <code class="literal"><em class="replaceable"><code>prefix</code></em>/doc/$MODULEDIR</code>
  80        </p></dd><dt id="EXTEND-PGXS-HEADERS"><span class="term"><code class="varname">HEADERS</code><br /></span><span class="term"><code class="varname">HEADERS_built</code></span> <a href="#EXTEND-PGXS-HEADERS" class="id_link">#</a></dt><dd><p>
  81         Files to (optionally build and) install under
  82         <code class="literal"><em class="replaceable"><code>prefix</code></em>/include/server/$MODULEDIR/$MODULE_big</code>.
  83        </p><p>
  84         Unlike <code class="literal">DATA_built</code>, files in <code class="literal">HEADERS_built</code>
  85         are not removed by the <code class="literal">clean</code> target; if you want them removed,
  86         also add them to <code class="literal">EXTRA_CLEAN</code> or add your own rules to do it.
  87        </p></dd><dt id="EXTEND-PGXS-HEADERS-MODULE"><span class="term"><code class="varname">HEADERS_$MODULE</code><br /></span><span class="term"><code class="varname">HEADERS_built_$MODULE</code></span> <a href="#EXTEND-PGXS-HEADERS-MODULE" class="id_link">#</a></dt><dd><p>
  88         Files to install (after building if specified) under
  89         <code class="literal"><em class="replaceable"><code>prefix</code></em>/include/server/$MODULEDIR/$MODULE</code>,
  90         where <code class="literal">$MODULE</code> must be a module name used
  91         in <code class="literal">MODULES</code> or <code class="literal">MODULE_big</code>.
  92        </p><p>
  93         Unlike <code class="literal">DATA_built</code>, files in <code class="literal">HEADERS_built_$MODULE</code>
  94         are not removed by the <code class="literal">clean</code> target; if you want them removed,
  95         also add them to <code class="literal">EXTRA_CLEAN</code> or add your own rules to do it.
  96        </p><p>
  97         It is legal to use both variables for the same module, or any
  98         combination, unless you have two module names in the
  99         <code class="literal">MODULES</code> list that differ only by the presence of a
 100         prefix <code class="literal">built_</code>, which would cause ambiguity. In
 101         that (hopefully unlikely) case, you should use only the
 102         <code class="literal">HEADERS_built_$MODULE</code> variables.
 103        </p></dd><dt id="EXTEND-PGXS-SCRIPTS"><span class="term"><code class="varname">SCRIPTS</code></span> <a href="#EXTEND-PGXS-SCRIPTS" class="id_link">#</a></dt><dd><p>
 104         script files (not binaries) to install into
 105         <code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>
 106        </p></dd><dt id="EXTEND-PGXS-SCRIPTS-BUILT"><span class="term"><code class="varname">SCRIPTS_built</code></span> <a href="#EXTEND-PGXS-SCRIPTS-BUILT" class="id_link">#</a></dt><dd><p>
 107         script files (not binaries) to install into
 108         <code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>,
 109         which need to be built first
 110        </p></dd><dt id="EXTEND-PGXS-REGRESS"><span class="term"><code class="varname">REGRESS</code></span> <a href="#EXTEND-PGXS-REGRESS" class="id_link">#</a></dt><dd><p>
 111         list of regression test cases (without suffix), see below
 112        </p></dd><dt id="EXTEND-PGXS-REGRESS-OPTS"><span class="term"><code class="varname">REGRESS_OPTS</code></span> <a href="#EXTEND-PGXS-REGRESS-OPTS" class="id_link">#</a></dt><dd><p>
 113         additional switches to pass to <span class="application">pg_regress</span>
 114        </p></dd><dt id="EXTEND-PGXS-ISOLATION"><span class="term"><code class="varname">ISOLATION</code></span> <a href="#EXTEND-PGXS-ISOLATION" class="id_link">#</a></dt><dd><p>
 115         list of isolation test cases, see below for more details
 116        </p></dd><dt id="EXTEND-PGXS-ISOLATION-OPTS"><span class="term"><code class="varname">ISOLATION_OPTS</code></span> <a href="#EXTEND-PGXS-ISOLATION-OPTS" class="id_link">#</a></dt><dd><p>
 117         additional switches to pass to
 118         <span class="application">pg_isolation_regress</span>
 119        </p></dd><dt id="EXTEND-PGXS-TAP-TESTS"><span class="term"><code class="varname">TAP_TESTS</code></span> <a href="#EXTEND-PGXS-TAP-TESTS" class="id_link">#</a></dt><dd><p>
 120         switch defining if TAP tests need to be run, see below
 121        </p></dd><dt id="EXTEND-PGXS-NO-INSTALL"><span class="term"><code class="varname">NO_INSTALL</code></span> <a href="#EXTEND-PGXS-NO-INSTALL" class="id_link">#</a></dt><dd><p>
 122         don't define an <code class="literal">install</code> target, useful for test
 123         modules that don't need their build products to be installed
 124        </p></dd><dt id="EXTEND-PGXS-NO-INSTALLCHECK"><span class="term"><code class="varname">NO_INSTALLCHECK</code></span> <a href="#EXTEND-PGXS-NO-INSTALLCHECK" class="id_link">#</a></dt><dd><p>
 125         don't define an <code class="literal">installcheck</code> target, useful e.g., if tests require special configuration, or don't use <span class="application">pg_regress</span>
 126        </p></dd><dt id="EXTEND-PGXS-EXTRA-CLEAN"><span class="term"><code class="varname">EXTRA_CLEAN</code></span> <a href="#EXTEND-PGXS-EXTRA-CLEAN" class="id_link">#</a></dt><dd><p>
 127         extra files to remove in <code class="literal">make clean</code>
 128        </p></dd><dt id="EXTEND-PGXS-PG-CPPFLAGS"><span class="term"><code class="varname">PG_CPPFLAGS</code></span> <a href="#EXTEND-PGXS-PG-CPPFLAGS" class="id_link">#</a></dt><dd><p>
 129         will be prepended to <code class="varname">CPPFLAGS</code>
 130        </p></dd><dt id="EXTEND-PGXS-PG-CFLAGS"><span class="term"><code class="varname">PG_CFLAGS</code></span> <a href="#EXTEND-PGXS-PG-CFLAGS" class="id_link">#</a></dt><dd><p>
 131         will be appended to <code class="varname">CFLAGS</code>
 132        </p></dd><dt id="EXTEND-PGXS-PG-CXXFLAGS"><span class="term"><code class="varname">PG_CXXFLAGS</code></span> <a href="#EXTEND-PGXS-PG-CXXFLAGS" class="id_link">#</a></dt><dd><p>
 133         will be appended to <code class="varname">CXXFLAGS</code>
 134        </p></dd><dt id="EXTEND-PGXS-PG-LDFLAGS"><span class="term"><code class="varname">PG_LDFLAGS</code></span> <a href="#EXTEND-PGXS-PG-LDFLAGS" class="id_link">#</a></dt><dd><p>
 135         will be prepended to <code class="varname">LDFLAGS</code>
 136        </p></dd><dt id="EXTEND-PGXS-PG-LIBS"><span class="term"><code class="varname">PG_LIBS</code></span> <a href="#EXTEND-PGXS-PG-LIBS" class="id_link">#</a></dt><dd><p>
 137         will be added to <code class="varname">PROGRAM</code> link line
 138        </p></dd><dt id="EXTEND-PGXS-SHLIB-LINK"><span class="term"><code class="varname">SHLIB_LINK</code></span> <a href="#EXTEND-PGXS-SHLIB-LINK" class="id_link">#</a></dt><dd><p>
 139         will be added to <code class="varname">MODULE_big</code> link line
 140        </p></dd><dt id="EXTEND-PGXS-PG-CONFIG"><span class="term"><code class="varname">PG_CONFIG</code></span> <a href="#EXTEND-PGXS-PG-CONFIG" class="id_link">#</a></dt><dd><p>
 141         path to <span class="application">pg_config</span> program for the
 142         <span class="productname">PostgreSQL</span> installation to build against
 143         (typically just <code class="literal">pg_config</code> to use the first one in your
 144         <code class="varname">PATH</code>)
 145        </p></dd></dl></div><p>
 146    </p><p>
 147     Put this makefile as <code class="literal">Makefile</code> in the directory
 148     which holds your extension. Then you can do
 149     <code class="literal">make</code> to compile, and then <code class="literal">make
 150     install</code> to install your module.  By default, the extension is
 151     compiled and installed for the
 152     <span class="productname">PostgreSQL</span> installation that
 153     corresponds to the first <code class="command">pg_config</code> program
 154     found in your <code class="varname">PATH</code>.  You can use a different installation by
 155     setting <code class="varname">PG_CONFIG</code> to point to its
 156     <code class="command">pg_config</code> program, either within the makefile
 157     or on the <code class="literal">make</code> command line.
 158    </p><p>
 159     You can select a separate directory prefix in which to install your
 160     extension's files, by setting the <code class="command">make</code> variable
 161     <code class="varname">prefix</code> when executing <code class="literal">make install</code>
 162     like so:
 163 </p><pre class="programlisting">
 164 make install prefix=/usr/local/postgresql
 165 </pre><p>
 166     This will install the extension control and SQL files into
 167     <code class="filename">/usr/local/postgresql/share</code> and the shared modules into
 168     <code class="filename">/usr/local/postgresql/lib</code>.  If the prefix does not
 169     include the strings <code class="literal">postgres</code> or
 170     <code class="literal">pgsql</code>, such as
 171 </p><pre class="programlisting">
 172 make install prefix=/usr/local/extras
 173 </pre><p>
 174     then <code class="literal">postgresql</code> will be appended to the directory
 175     names, installing the control and SQL files into
 176     <code class="filename">/usr/local/extras/share/postgresql/extension</code> and the
 177     shared modules into <code class="filename">/usr/local/extras/lib/postgresql</code>.
 178     Either way, you'll need to set <a class="xref" href="runtime-config-client.html#GUC-EXTENSION-CONTROL-PATH">extension_control_path</a> and <a class="xref" href="runtime-config-client.html#GUC-DYNAMIC-LIBRARY-PATH">dynamic_library_path</a> to enable the
 179     <span class="productname">PostgreSQL</span> server to find the files:
 180 </p><pre class="programlisting">
 181 extension_control_path = '/usr/local/extras/share/postgresql:$system'
 182 dynamic_library_path = '/usr/local/extras/lib/postgresql:$libdir'
 183 </pre><p>
 184    </p><p>
 185     You can also run <code class="literal">make</code> in a directory outside the source
 186     tree of your extension, if you want to keep the build directory separate.
 187     This procedure is also called a
 188     <a id="id-1.8.3.21.8.2" class="indexterm"></a><em class="firstterm">VPATH</em>
 189     build.  Here's how:
 190 </p><pre class="programlisting">
 191 mkdir build_dir
 192 cd build_dir
 193 make -f /path/to/extension/source/tree/Makefile
 194 make -f /path/to/extension/source/tree/Makefile install
 195 </pre><p>
 196    </p><p>
 197     Alternatively, you can set up a directory for a VPATH build in a similar
 198     way to how it is done for the core code. One way to do this is using the
 199     core script <code class="filename">config/prep_buildtree</code>. Once this has been done
 200     you can build by setting the <code class="literal">make</code> variable
 201     <code class="varname">VPATH</code> like this:
 202 </p><pre class="programlisting">
 203 make VPATH=/path/to/extension/source/tree
 204 make VPATH=/path/to/extension/source/tree install
 205 </pre><p>
 206     This procedure can work with a greater variety of directory layouts.
 207    </p><p>
 208     The scripts listed in the <code class="varname">REGRESS</code> variable are used for
 209     regression testing of your module, which can be invoked by <code class="literal">make
 210     installcheck</code> after doing <code class="literal">make install</code>.  For this to
 211     work you must have a running <span class="productname">PostgreSQL</span> server.
 212     The script files listed in <code class="varname">REGRESS</code> must appear in a
 213     subdirectory named <code class="literal">sql/</code> in your extension's directory.
 214     These files must have extension <code class="literal">.sql</code>, which must not be
 215     included in the <code class="varname">REGRESS</code> list in the makefile.  For each
 216     test there should also be a file containing the expected output in a
 217     subdirectory named <code class="literal">expected/</code>, with the same stem and
 218     extension <code class="literal">.out</code>.  <code class="literal">make installcheck</code>
 219     executes each test script with <span class="application">psql</span>, and compares the
 220     resulting output to the matching expected file.  Any differences will be
 221     written to the file <code class="literal">regression.diffs</code> in <code class="command">diff
 222     -c</code> format.  Note that trying to run a test that is missing its
 223     expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so make sure you
 224     have all expected files.
 225    </p><p>
 226     The scripts listed in the <code class="varname">ISOLATION</code> variable are used
 227     for tests stressing behavior of concurrent session with your module, which
 228     can be invoked by <code class="literal">make installcheck</code> after doing
 229     <code class="literal">make install</code>.  For this to work you must have a
 230     running <span class="productname">PostgreSQL</span> server.  The script files
 231     listed in <code class="varname">ISOLATION</code> must appear in a subdirectory
 232     named <code class="literal">specs/</code> in your extension's directory.  These files
 233     must have extension <code class="literal">.spec</code>, which must not be included
 234     in the <code class="varname">ISOLATION</code> list in the makefile.  For each test
 235     there should also be a file containing the expected output in a
 236     subdirectory named <code class="literal">expected/</code>, with the same stem and
 237     extension <code class="literal">.out</code>.  <code class="literal">make installcheck</code>
 238     executes each test script, and compares the resulting output to the
 239     matching expected file.  Any differences will be written to the file
 240     <code class="literal">output_iso/regression.diffs</code> in
 241     <code class="command">diff -c</code> format.  Note that trying to run a test that is
 242     missing its expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so
 243     make sure you have all expected files.
 244    </p><p>
 245     <code class="literal">TAP_TESTS</code> enables the use of TAP tests.  Data from each
 246     run is present in a subdirectory named <code class="literal">tmp_check/</code>.
 247     See also <a class="xref" href="regress-tap.html" title="31.4. TAP Tests">Section 31.4</a> for more details.
 248    </p><div class="tip"><h3 class="title">Tip</h3><p>
 249      The easiest way to create the expected files is to create empty files,
 250      then do a test run (which will of course report differences).  Inspect
 251      the actual result files found in the <code class="literal">results/</code>
 252      directory (for tests in <code class="literal">REGRESS</code>), or
 253      <code class="literal">output_iso/results/</code> directory (for tests in
 254      <code class="literal">ISOLATION</code>), then copy them to
 255      <code class="literal">expected/</code> if they match what you expect from the test.
 256     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-extensions.html" title="36.17. Packaging Related Objects into an Extension">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 36. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 37. Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.17. Packaging Related Objects into an Extension </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 37. Triggers</td></tr></table></div></body></html>