Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Bevaka 1
Stjärnmärk 0
Wiki 捐赠
gooderp18绿色标准版
Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.
Gren: master
Grenar Taggar
${ item.name }
Skapa branchen ${ searchTerm }
från 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/PostgreSQL/doc/postgresql/html/extend-pgxs.html

227 lines
18KB
Rå Permalänk Blame Historik 

  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>37.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 V1.79.1" /><link rel="prev" href="extend-extensions.html" title="37.17. 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.18. Extension Building Infrastructure</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-extensions.html" title="37.17. 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 12.4 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.18. Extension Building Infrastructure</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, a 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><span class="term"><code class="varname">MODULES</code></span></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><span class="term"><code class="varname">MODULE_big</code></span></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><span class="term"><code class="varname">PROGRAM</code></span></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><span class="term"><code class="varname">EXTENSION</code></span></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><span class="term"><code class="varname">MODULEDIR</code></span></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><span class="term"><code class="varname">DATA</code></span></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><span class="term"><code class="varname">DATA_built</code></span></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><span class="term"><code class="varname">DATA_TSEARCH</code></span></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><span class="term"><code class="varname">DOCS</code></span></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><span class="term"><code class="varname">HEADERS</code><br /></span><span class="term"><code class="varname">HEADERS_built</code></span></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><span class="term"><code class="varname">HEADERS_$MODULE</code><br /></span><span class="term"><code class="varname">HEADERS_built_$MODULE</code></span></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><span class="term"><code class="varname">SCRIPTS</code></span></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><span class="term"><code class="varname">SCRIPTS_built</code></span></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><span class="term"><code class="varname">REGRESS</code></span></dt><dd><p>

  111.         list of regression test cases (without suffix), see below

  112.        </p></dd><dt><span class="term"><code class="varname">REGRESS_OPTS</code></span></dt><dd><p>

  113.         additional switches to pass to <span class="application">pg_regress</span>

  114.        </p></dd><dt><span class="term"><code class="varname">ISOLATION</code></span></dt><dd><p>

  115.         list of isolation test cases, see below for more details

  116.        </p></dd><dt><span class="term"><code class="varname">ISOLATION_OPTS</code></span></dt><dd><p>

  117.         additional switches to pass to

  118.         <span class="application">pg_isolation_regress</span>

  119.        </p></dd><dt><span class="term"><code class="varname">TAP_TESTS</code></span></dt><dd><p>

  120.         switch defining if TAP tests need to be run, see below

  121.        </p></dd><dt><span class="term"><code class="varname">NO_INSTALLCHECK</code></span></dt><dd><p>

  122.         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>

  123.        </p></dd><dt><span class="term"><code class="varname">EXTRA_CLEAN</code></span></dt><dd><p>

  124.         extra files to remove in <code class="literal">make clean</code>

  125.        </p></dd><dt><span class="term"><code class="varname">PG_CPPFLAGS</code></span></dt><dd><p>

  126.         will be prepended to <code class="varname">CPPFLAGS</code>

  127.        </p></dd><dt><span class="term"><code class="varname">PG_CFLAGS</code></span></dt><dd><p>

  128.         will be appended to <code class="varname">CFLAGS</code>

  129.        </p></dd><dt><span class="term"><code class="varname">PG_CXXFLAGS</code></span></dt><dd><p>

  130.         will be appended to <code class="varname">CXXFLAGS</code>

  131.        </p></dd><dt><span class="term"><code class="varname">PG_LDFLAGS</code></span></dt><dd><p>

  132.         will be prepended to <code class="varname">LDFLAGS</code>

  133.        </p></dd><dt><span class="term"><code class="varname">PG_LIBS</code></span></dt><dd><p>

  134.         will be added to <code class="varname">PROGRAM</code> link line

  135.        </p></dd><dt><span class="term"><code class="varname">SHLIB_LINK</code></span></dt><dd><p>

  136.         will be added to <code class="varname">MODULE_big</code> link line

  137.        </p></dd><dt><span class="term"><code class="varname">PG_CONFIG</code></span></dt><dd><p>

  138.         path to <span class="application">pg_config</span> program for the

  139.         <span class="productname">PostgreSQL</span> installation to build against

  140.         (typically just <code class="literal">pg_config</code> to use the first one in your

  141.         <code class="varname">PATH</code>)

  142.        </p></dd></dl></div><p>

  143.    </p><p>

  144.     Put this makefile as <code class="literal">Makefile</code> in the directory

  145.     which holds your extension. Then you can do

  146.     <code class="literal">make</code> to compile, and then <code class="literal">make

  147.     install</code> to install your module.  By default, the extension is

  148.     compiled and installed for the

  149.     <span class="productname">PostgreSQL</span> installation that

  150.     corresponds to the first <code class="command">pg_config</code> program

  151.     found in your <code class="varname">PATH</code>.  You can use a different installation by

  152.     setting <code class="varname">PG_CONFIG</code> to point to its

  153.     <code class="command">pg_config</code> program, either within the makefile

  154.     or on the <code class="literal">make</code> command line.

  155.    </p><p>

  156.     You can also run <code class="literal">make</code> in a directory outside the source

  157.     tree of your extension, if you want to keep the build directory separate.

  158.     This procedure is also called a

  159.     <a id="id-1.8.3.21.7.2" class="indexterm"></a><em class="firstterm">VPATH</em>

  160.     build.  Here's how:

  161. </p><pre class="programlisting">

  162. mkdir build_dir

  163. cd build_dir

  164. make -f /path/to/extension/source/tree/Makefile

  165. make -f /path/to/extension/source/tree/Makefile install

  166. </pre><p>

  167.    </p><p>

  168.     Alternatively, you can set up a directory for a VPATH build in a similar

  169.     way to how it is done for the core code. One way to do this is using the

  170.     core script <code class="filename">config/prep_buildtree</code>. Once this has been done

  171.     you can build by setting the <code class="literal">make</code> variable

  172.     <code class="varname">VPATH</code> like this:

  173. </p><pre class="programlisting">

  174. make VPATH=/path/to/extension/source/tree

  175. make VPATH=/path/to/extension/source/tree install

  176. </pre><p>

  177.     This procedure can work with a greater variety of directory layouts.

  178.    </p><p>

  179.     The scripts listed in the <code class="varname">REGRESS</code> variable are used for

  180.     regression testing of your module, which can be invoked by <code class="literal">make

  181.     installcheck</code> after doing <code class="literal">make install</code>.  For this to

  182.     work you must have a running <span class="productname">PostgreSQL</span> server.

  183.     The script files listed in <code class="varname">REGRESS</code> must appear in a

  184.     subdirectory named <code class="literal">sql/</code> in your extension's directory.

  185.     These files must have extension <code class="literal">.sql</code>, which must not be

  186.     included in the <code class="varname">REGRESS</code> list in the makefile.  For each

  187.     test there should also be a file containing the expected output in a

  188.     subdirectory named <code class="literal">expected/</code>, with the same stem and

  189.     extension <code class="literal">.out</code>.  <code class="literal">make installcheck</code>

  190.     executes each test script with <span class="application">psql</span>, and compares the

  191.     resulting output to the matching expected file.  Any differences will be

  192.     written to the file <code class="literal">regression.diffs</code> in <code class="command">diff

  193.     -c</code> format.  Note that trying to run a test that is missing its

  194.     expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so make sure you

  195.     have all expected files.

  196.    </p><p>

  197.     The scripts listed in the <code class="varname">ISOLATION</code> variable are used

  198.     for tests stressing behavior of concurrent session with your module, which

  199.     can be invoked by <code class="literal">make installcheck</code> after doing

  200.     <code class="literal">make install</code>.  For this to work you must have a

  201.     running <span class="productname">PostgreSQL</span> server.  The script files

  202.     listed in <code class="varname">ISOLATION</code> must appear in a subdirectory

  203.     named <code class="literal">specs/</code> in your extension's directory.  These files

  204.     must have extension <code class="literal">.spec</code>, which must not be included

  205.     in the <code class="varname">ISOLATION</code> list in the makefile.  For each test

  206.     there should also be a file containing the expected output in a

  207.     subdirectory named <code class="literal">expected/</code>, with the same stem and

  208.     extension <code class="literal">.out</code>.  <code class="literal">make installcheck</code>

  209.     executes each test script, and compares the resulting output to the

  210.     matching expected file.  Any differences will be written to the file

  211.     <code class="literal">output_iso/regression.diffs</code> in

  212.     <code class="command">diff -c</code> format.  Note that trying to run a test that is

  213.     missing its expected file will be reported as <span class="quote">“<span class="quote">trouble</span>”</span>, so

  214.     make sure you have all expected files.

  215.    </p><p>

  216.     <code class="literal">TAP_TESTS</code> enables the use of TAP tests.  Data from each

  217.     run is present in a subdirectory named <code class="literal">tmp_check/</code>.

  218.     See also <a class="xref" href="regress-tap.html" title="32.4. TAP Tests">Section 32.4</a> for more details.

  219.    </p><div class="tip"><h3 class="title">Tip</h3><p>

  220.      The easiest way to create the expected files is to create empty files,

  221.      then do a test run (which will of course report differences).  Inspect

  222.      the actual result files found in the <code class="literal">results/</code>

  223.      directory (for tests in <code class="literal">REGRESS</code>), or

  224.      <code class="literal">output_iso/results/</code> directory (for tests in

  225.      <code class="literal">ISOLATION</code>), then copy them to

  226.      <code class="literal">expected/</code> if they match what you expect from the test.

  227.     </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">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="triggers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">37.17. Packaging Related Objects into an Extension </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 38. Triggers</td></tr></table></div></body></html>
上海开阖软件有限公司 沪ICP备12045867号-1