| Server IP : 172.67.134.114 / Your IP : 162.159.115.41 Web Server : Apache/2.4.37 System : Linux almalinux.duckdns.org 4.18.0-553.111.1.el8_10.x86_64 #1 SMP Sun Mar 8 20:06:07 EDT 2026 x86_64 User : ricodeal ( 1046) PHP Version : 7.4.33 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/postgresql-docs/html/ |
Upload File : |
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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>37.16. Extension Building Infrastructure</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="[email protected]" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="extend-extensions.html" title="37.15. Packaging Related Objects into an Extension" /><link rel="next" href="triggers.html" title="Chapter 38. Triggers" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">37.16. Extension Building Infrastructure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-extensions.html" title="37.15. Packaging Related Objects into an Extension">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 37. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 37. Extending <acronym xmlns="http://www.w3.org/1999/xhtml" class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 10.23 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 38. Triggers">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="EXTEND-PGXS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">37.16. Extension Building Infrastructure</h2></div></div></div><a id="id-1.8.3.19.2" class="indexterm"></a><p> If you are thinking about distributing your
<span class="productname">PostgreSQL</span> extension modules, setting up a
portable build system for them can be fairly difficult. Therefore
the <span class="productname">PostgreSQL</span> installation provides a build
infrastructure for extensions, called <acronym class="acronym">PGXS</acronym>, so
that simple extension modules can be built simply against an
already installed server. <acronym class="acronym">PGXS</acronym> is mainly intended
for extensions that include C code, although it can be used for
pure-SQL extensions too. Note that <acronym class="acronym">PGXS</acronym> is not
intended to be a universal build system framework that can be used
to build any software interfacing to <span class="productname">PostgreSQL</span>;
it simply automates common build rules for simple server extension
modules. For more complicated packages, you might need to write your
own build system.
</p><p> To use the <acronym class="acronym">PGXS</acronym> infrastructure for your extension,
you must write a simple makefile.
In the makefile, you need to set some variables
and include the global <acronym class="acronym">PGXS</acronym> makefile.
Here is an example that builds an extension module named
<code class="literal">isbn_issn</code>, consisting of a shared library containing
some C code, an extension control file, a SQL script, and a documentation
text file:
</p><pre class="programlisting">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)</pre><p>
The last three lines should always be the same. Earlier in the
file, you assign variables or add custom
<span class="application">make</span> rules.
</p><p> Set one of these three variables to specify what is built:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">MODULES</code></span></dt><dd><p> list of shared-library objects to be built from source files with same
stem (do not include library suffixes in this list)
</p></dd><dt><span class="term"><code class="varname">MODULE_big</code></span></dt><dd><p> a shared library to build from multiple source files
(list object files in <code class="varname">OBJS</code>)
</p></dd><dt><span class="term"><code class="varname">PROGRAM</code></span></dt><dd><p> an executable program to build
(list object files in <code class="varname">OBJS</code>)
</p></dd></dl></div><p>
The following variables can also be set:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">EXTENSION</code></span></dt><dd><p> extension name(s); for each name you must provide an
<code class="literal"><em class="replaceable"><code>extension</code></em>.control</code> file,
which will be installed into
<code class="literal"><em class="replaceable"><code>prefix</code></em>/share/extension</code>
</p></dd><dt><span class="term"><code class="varname">MODULEDIR</code></span></dt><dd><p> subdirectory of <code class="literal"><em class="replaceable"><code>prefix</code></em>/share</code>
into which DATA and DOCS files should be installed
(if not set, default is <code class="literal">extension</code> if
<code class="varname">EXTENSION</code> is set,
or <code class="literal">contrib</code> if not)
</p></dd><dt><span class="term"><code class="varname">DATA</code></span></dt><dd><p> random files to install into <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>
</p></dd><dt><span class="term"><code class="varname">DATA_built</code></span></dt><dd><p> random files to install into
<code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>,
which need to be built first
</p></dd><dt><span class="term"><code class="varname">DATA_TSEARCH</code></span></dt><dd><p> random files to install under
<code class="literal"><em class="replaceable"><code>prefix</code></em>/share/tsearch_data</code>
</p></dd><dt><span class="term"><code class="varname">DOCS</code></span></dt><dd><p> random files to install under
<code class="literal"><em class="replaceable"><code>prefix</code></em>/doc/$MODULEDIR</code>
</p></dd><dt><span class="term"><code class="varname">SCRIPTS</code></span></dt><dd><p> script files (not binaries) to install into
<code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>
</p></dd><dt><span class="term"><code class="varname">SCRIPTS_built</code></span></dt><dd><p> script files (not binaries) to install into
<code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>,
which need to be built first
</p></dd><dt><span class="term"><code class="varname">REGRESS</code></span></dt><dd><p> list of regression test cases (without suffix), see below
</p></dd><dt><span class="term"><code class="varname">REGRESS_OPTS</code></span></dt><dd><p> additional switches to pass to <span class="application">pg_regress</span>
</p></dd><dt><span class="term"><code class="varname">NO_INSTALLCHECK</code></span></dt><dd><p> 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>
</p></dd><dt><span class="term"><code class="varname">EXTRA_CLEAN</code></span></dt><dd><p> extra files to remove in <code class="literal">make clean</code>
</p></dd><dt><span class="term"><code class="varname">PG_CPPFLAGS</code></span></dt><dd><p> will be prepended to <code class="varname">CPPFLAGS</code>
</p></dd><dt><span class="term"><code class="varname">PG_CFLAGS</code></span></dt><dd><p> will be appended to <code class="varname">CFLAGS</code>
</p></dd><dt><span class="term"><code class="varname">PG_CXXFLAGS</code></span></dt><dd><p> will be appended to <code class="varname">CXXFLAGS</code>
</p></dd><dt><span class="term"><code class="varname">PG_LDFLAGS</code></span></dt><dd><p> will be prepended to <code class="varname">LDFLAGS</code>
</p></dd><dt><span class="term"><code class="varname">PG_LIBS</code></span></dt><dd><p> will be added to <code class="varname">PROGRAM</code> link line
</p></dd><dt><span class="term"><code class="varname">SHLIB_LINK</code></span></dt><dd><p> will be added to <code class="varname">MODULE_big</code> link line
</p></dd><dt><span class="term"><code class="varname">PG_CONFIG</code></span></dt><dd><p> path to <span class="application">pg_config</span> program for the
<span class="productname">PostgreSQL</span> installation to build against
(typically just <code class="literal">pg_config</code> to use the first one in your
<code class="varname">PATH</code>)
</p></dd></dl></div><p>
</p><p> Put this makefile as <code class="literal">Makefile</code> in the directory
which holds your extension. Then you can do
<code class="literal">make</code> to compile, and then <code class="literal">make
install</code> to install your module. By default, the extension is
compiled and installed for the
<span class="productname">PostgreSQL</span> installation that
corresponds to the first <code class="command">pg_config</code> program
found in your <code class="varname">PATH</code>. You can use a different installation by
setting <code class="varname">PG_CONFIG</code> to point to its
<code class="command">pg_config</code> program, either within the makefile
or on the <code class="literal">make</code> command line.
</p><p> You can also run <code class="literal">make</code> 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
<a id="id-1.8.3.19.7.2" class="indexterm"></a><em class="firstterm">VPATH</em>
build. Here's how:
</p><pre class="programlisting">mkdir build_dir
cd build_dir
make -f /path/to/extension/source/tree/Makefile
make -f /path/to/extension/source/tree/Makefile install</pre><p>
</p><p> 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 <code class="filename">config/prep_buildtree</code>. Once this has been done
you can build by setting the <code class="literal">make</code> variable
<code class="varname">VPATH</code> like this:
</p><pre class="programlisting">make VPATH=/path/to/extension/source/tree
make VPATH=/path/to/extension/source/tree install</pre><p>
This procedure can work with a greater variety of directory layouts.
</p><p> The scripts listed in the <code class="varname">REGRESS</code> variable are used for
regression testing of your module, which can be invoked by <code class="literal">make
installcheck</code> after doing <code class="literal">make install</code>. For this to
work you must have a running <span class="productname">PostgreSQL</span> server.
The script files listed in <code class="varname">REGRESS</code> must appear in a
subdirectory named <code class="literal">sql/</code> in your extension's directory.
These files must have extension <code class="literal">.sql</code>, which must not be
included in the <code class="varname">REGRESS</code> list in the makefile. For each
test there should also be a file containing the expected output in a
subdirectory named <code class="literal">expected/</code>, with the same stem and
extension <code class="literal">.out</code>. <code class="literal">make installcheck</code>
executes each test script with <span class="application">psql</span>, and compares the
resulting output to the matching expected file. Any differences will be
written to the file <code class="literal">regression.diffs</code> in <code class="command">diff
-c</code> format. Note that trying to run a test that is missing its
expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so make sure you
have all expected files.
</p><div class="tip"><h3 class="title">Tip</h3><p> 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 <code class="literal">results/</code>
directory, then copy them to <code class="literal">expected/</code> if they match
what you expect from the test.
</p></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-extensions.html" title="37.15. Packaging Related Objects into an Extension">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 37. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 38. Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.15. Packaging Related Objects into an Extension </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 10.23 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 38. Triggers</td></tr></table></div></body></html>