Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
extend-pgxs.html230 linesDownload Raw Back to 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>38.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="38.17. Packaging Related Objects into an Extension" /><link rel="next" href="triggers.html" title="Chapter 39. 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">38.18. Extension Building Infrastructure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 39. 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">38.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 your4    <span class="productname">PostgreSQL</span> extension modules, setting up a5    portable build system for them can be fairly difficult.  Therefore6    the <span class="productname">PostgreSQL</span> installation provides a build7    infrastructure for extensions, called <acronym class="acronym">PGXS</acronym>, so8    that simple extension modules can be built simply against an9    already installed server.  <acronym class="acronym">PGXS</acronym> is mainly intended10    for extensions that include C code, although it can be used for11    pure-SQL extensions too.  Note that <acronym class="acronym">PGXS</acronym> is not12    intended to be a universal build system framework that can be used13    to build any software interfacing to <span class="productname">PostgreSQL</span>;14    it simply automates common build rules for simple server extension15    modules.  For more complicated packages, you might need to write your16    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 variables21    and include the global <acronym class="acronym">PGXS</acronym> makefile.22    Here is an example that builds an extension module named23    <code class="literal">isbn_issn</code>, consisting of a shared library containing24    some C code, an extension control file, an SQL script, an include file25    (only needed if other modules might need to access the extension functions26    without going via SQL), and a documentation text file:27</p><pre class="programlisting">28MODULES = isbn_issn29EXTENSION = isbn_issn30DATA = isbn_issn--1.0.sql31DOCS = README.isbn_issn32HEADERS_isbn_issn = isbn_issn.h33 34PG_CONFIG = pg_config35PGXS := $(shell $(PG_CONFIG) --pgxs)36include $(PGXS)37</pre><p>38    The last three lines should always be the same.  Earlier in the39    file, you assign variables or add custom40    <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 same46        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 files49        (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 build52        (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 an59        <code class="literal"><em class="replaceable"><code>extension</code></em>.control</code> file,60        which will be installed into61        <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 installed65        (if not set, default is <code class="literal">extension</code> if66        <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 into72        <code class="literal"><em class="replaceable"><code>prefix</code></em>/share/$MODULEDIR</code>,73        which need to be built first74       </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 under76        <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 under79        <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 under82        <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) under89        <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 used91        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 any98        combination, unless you have two module names in the99        <code class="literal">MODULES</code> list that differ only by the presence of a100        prefix <code class="literal">built_</code>, which would cause ambiguity. In101        that (hopefully unlikely) case, you should use only the102        <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 into105        <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 into108        <code class="literal"><em class="replaceable"><code>prefix</code></em>/bin</code>,109        which need to be built first110       </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 below112       </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 details116       </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 to118        <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 below121       </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 test123        modules that don't need their build products to be installed124       </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 line138       </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 line140       </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 the142        <span class="productname">PostgreSQL</span> installation to build against143        (typically just <code class="literal">pg_config</code> to use the first one in your144        <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 directory148    which holds your extension. Then you can do149    <code class="literal">make</code> to compile, and then <code class="literal">make150    install</code> to install your module.  By default, the extension is151    compiled and installed for the152    <span class="productname">PostgreSQL</span> installation that153    corresponds to the first <code class="command">pg_config</code> program154    found in your <code class="varname">PATH</code>.  You can use a different installation by155    setting <code class="varname">PG_CONFIG</code> to point to its156    <code class="command">pg_config</code> program, either within the makefile157    or on the <code class="literal">make</code> command line.158   </p><p>159    You can also run <code class="literal">make</code> in a directory outside the source160    tree of your extension, if you want to keep the build directory separate.161    This procedure is also called a162    <a id="id-1.8.3.21.7.2" class="indexterm"></a><em class="firstterm">VPATH</em>163    build.  Here's how:164</p><pre class="programlisting">165mkdir build_dir166cd build_dir167make -f /path/to/extension/source/tree/Makefile168make -f /path/to/extension/source/tree/Makefile install169</pre><p>170   </p><p>171    Alternatively, you can set up a directory for a VPATH build in a similar172    way to how it is done for the core code. One way to do this is using the173    core script <code class="filename">config/prep_buildtree</code>. Once this has been done174    you can build by setting the <code class="literal">make</code> variable175    <code class="varname">VPATH</code> like this:176</p><pre class="programlisting">177make VPATH=/path/to/extension/source/tree178make VPATH=/path/to/extension/source/tree install179</pre><p>180    This procedure can work with a greater variety of directory layouts.181   </p><p>182    The scripts listed in the <code class="varname">REGRESS</code> variable are used for183    regression testing of your module, which can be invoked by <code class="literal">make184    installcheck</code> after doing <code class="literal">make install</code>.  For this to185    work you must have a running <span class="productname">PostgreSQL</span> server.186    The script files listed in <code class="varname">REGRESS</code> must appear in a187    subdirectory named <code class="literal">sql/</code> in your extension's directory.188    These files must have extension <code class="literal">.sql</code>, which must not be189    included in the <code class="varname">REGRESS</code> list in the makefile.  For each190    test there should also be a file containing the expected output in a191    subdirectory named <code class="literal">expected/</code>, with the same stem and192    extension <code class="literal">.out</code>.  <code class="literal">make installcheck</code>193    executes each test script with <span class="application">psql</span>, and compares the194    resulting output to the matching expected file.  Any differences will be195    written to the file <code class="literal">regression.diffs</code> in <code class="command">diff196    -c</code> format.  Note that trying to run a test that is missing its197    expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so make sure you198    have all expected files.199   </p><p>200    The scripts listed in the <code class="varname">ISOLATION</code> variable are used201    for tests stressing behavior of concurrent session with your module, which202    can be invoked by <code class="literal">make installcheck</code> after doing203    <code class="literal">make install</code>.  For this to work you must have a204    running <span class="productname">PostgreSQL</span> server.  The script files205    listed in <code class="varname">ISOLATION</code> must appear in a subdirectory206    named <code class="literal">specs/</code> in your extension's directory.  These files207    must have extension <code class="literal">.spec</code>, which must not be included208    in the <code class="varname">ISOLATION</code> list in the makefile.  For each test209    there should also be a file containing the expected output in a210    subdirectory named <code class="literal">expected/</code>, with the same stem and211    extension <code class="literal">.out</code>.  <code class="literal">make installcheck</code>212    executes each test script, and compares the resulting output to the213    matching expected file.  Any differences will be written to the file214    <code class="literal">output_iso/regression.diffs</code> in215    <code class="command">diff -c</code> format.  Note that trying to run a test that is216    missing its expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so217    make sure you have all expected files.218   </p><p>219    <code class="literal">TAP_TESTS</code> enables the use of TAP tests.  Data from each220    run is present in a subdirectory named <code class="literal">tmp_check/</code>.221    See also <a class="xref" href="regress-tap.html" title="33.4. TAP Tests">Section 33.4</a> for more details.222   </p><div class="tip"><h3 class="title">Tip</h3><p>223     The easiest way to create the expected files is to create empty files,224     then do a test run (which will of course report differences).  Inspect225     the actual result files found in the <code class="literal">results/</code>226     directory (for tests in <code class="literal">REGRESS</code>), or227     <code class="literal">output_iso/results/</code> directory (for tests in228     <code class="literal">ISOLATION</code>), then copy them to229     <code class="literal">expected/</code> if they match what you expect from the test.230    </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="38.17. Packaging Related Objects into an Extension">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="triggers.html" title="Chapter 39. Triggers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.17. Packaging Related Objects into an Extension </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 39. Triggers</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai