From e308bcff5a610d6a3bbe33b3769f03f6d4533b16 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 18:02:19 +0200 Subject: Adding upstream version 248. Signed-off-by: Daniel Baumann --- pg_buildext.pod | 344 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 pg_buildext.pod (limited to 'pg_buildext.pod') diff --git a/pg_buildext.pod b/pg_buildext.pod new file mode 100644 index 0000000..37063f9 --- /dev/null +++ b/pg_buildext.pod @@ -0,0 +1,344 @@ +=head1 NAME + +pg_buildext - Build and install a PostgreSQL extension + +=head1 SYNOPSIS + +B [I] I [I] [I] + +=head1 DESCRIPTION + +B is a script that will build a PostgreSQL extension in a C +way, for potentially several PostgreSQL server versions in parallel. +It builds for the intersection of versions known in +C (versions supported by the package) and in +C (versions supported in this +release). + +Many PostgreSQL extension packages require no special handling at build time +and can use B or B to +automatically execute the steps outlined below. + +=head1 USAGE + +Packages using B should be prepared to build binaries for +PostgreSQL versions that are not present in Debian unstable, e.g. for older +releases when building backports for Debian (old)stable (possibly including +backports of newer PostgreSQL releases), or for all PostgreSQL releases when +the package is built for B. + +As the set of binary packages depends on the target PostgreSQL versions, +C is generated from a template in C when +B is run. +Package sections that contain B in the package name are replaced by +a list of sections, filling in the supported PostgreSQL versions. +Package sections that contain B outside the package name have the +newest supported PostgreSQL version filled in (useful for meta packages). +Include +C in C to +run a check at build time if updating debian/control is required. + +As B invokes B for the B, B, and B +actions, invocations from C (which is a makefile) should be prefixed +with B<+> so the sub-makes can talk with the make jobserver. Additional makefile +variables can be passed to B via the B<-m> option. + +Many extensions support B testing using B. As +this needs the package to be installed, it cannot be run at build time. +Instead, the tests should be run using B from C. + +If C exists, occurrences of package names containing +B are replaced by lists of package names with the target PostgreSQL +versions filled in. (If no replacing is needed in C, it +is fine to provide the tests control file directly.) + +=head1 OPTIONS + +=over 4 + +=item B<-cio> I + +=item B<-s> + +Passed to B when running B. + +=item B<-m> I + +Passed to B. + +=back + +=head1 ACTIONS + +Most actions expect a directory name where to build the sources. It will get +created for you if it does not exist. If the I contains a C<%v> +sign, it will get replaced by the specific version of PostgreSQL being built +against. (Usually this parameter is C.) + +=over 4 + +=item B + +Print effective list of supported versions, i.e. the intersection of the sets +of versions supported by the system +(from C) and the package +(from C). + +Use this when building packages. + +=item B + +In the list of installed packages, look for packages matching the B +package name templates from C, and print the PostgreSQL +major version number part. + +Use this when testing packages. + +=item B + +Check if C needs updating from C. This is +invoked from C. When +building for a B or B suite as determined by +C, this action also updates the control file. Otherwise, +B needs to be run manually. + +=item B + +Update C from C, and C +from C if the latter exists. + +=item B [I] I [I] + +For every supported version, call B<../configure> from the I +directory. (Most PostgreSQL extensions do not have a configure script.) + +=item B [I] I [I] + +Build the extension in the I directory. + +=item B [I] I I + +Invoke B from the I directory. +The third parameter specifies the package name to use. Most packages +use B. Make will be +called with DESTDIR="$(CURDIR)/debian/I". + +The B substitution variable B is set to depend +on the required PostgreSQL server package. For compatibility with previous +packaging standards, the dependency is also added to B if +postgresql:Depends is not used. + +=item B [I] [I] [I] + +Clean the build directories. + +=item B [I] I + +As a variant to calling B and B separately for VPATH builds, +loop over the supported PostgreSQL versions in the top source directory. This +should be used if the package does not support VPATH builds. As it also invokes +B, it should be placed were installation happens in debian/rules, +rather than where build would normally be called. + +=item B [I] [I] [I] + +Use B to run the extension regression tests. +This is meant to be run from C using B. If +I is omitted, the top source directory is used. + +If I is given, options are passed to B to set +up the temporary PostgreSQL instance to find extension files in +C. + +Other than the other actions which run on the "supported" versions, if C exists, this one +runs on the "installed" versions as reported by B (unless +I is provided, which means we are called during a build). + +=item B [I] [I] [I] + +=item B [I] [I] [I] + +Like B, but invokes B, or a shell, both wrapped in +B. Input is read from stdin. + +=back + +Sometimes it is desirable to run extra code per version before invoking the +action, in that case the loop over supported versions needs to be in the +calling script. To facilitate this mode, actions can also be called as +IB<->I. See the installcheck example below. + +=head1 SUPPORTED VERSIONS + +B reads C to decide which PostgreSQL to build +modules/extensions for. This file contains one PostgreSQL version number per +line, in the following formats: + +=over 4 + +=item B + +Support all versions. This is recommended unless there are known incompatibilities. + +=item I + +Support this version. + +=item IB<+> + +Support this and all greater versions. + +=item B<#>I<...> + +Comment. + +=back + +For a version to be used, it must also be listed in the output of +C. See this file for how to +configure the list of supported versions on your system. + +=head1 EXAMPLE + +=over 4 + +=item B + + Source: postgresql-foobar + Rules-Requires-Root: no + Build-Depends: + debhelper, + postgresql-all , + postgresql-server-dev-all (>= 217~), + + Package: postgresql-PGVERSION-foobar + Architecture: any + Depends: + ${misc:Depends}, + ${postgresql:Depends}, + ${shlibs:Depends}, + +=item B + + all + + # alternatives: + #9.6 + #11+ + +=item B using B: + + #!/usr/bin/make -f + + override_dh_installdocs: + dh_installdocs --all README.* + + %: + dh $@ --with pgxs + +=item If the package does no support building from subdirectories, use B: + + #!/usr/bin/make -f + + %: + dh $@ --with pgxs_loop + +=item If the package does not use PGXS's "make installcheck" for testing: + + override_dh_pgxs_test: + +=item B using B directly: + + #!/usr/bin/make -f + + include /usr/share/postgresql-common/pgxs_debian_control.mk + + # omit this if the package does not use autoconf + override_dh_auto_configure: + +pg_buildext configure build-%v "--libdir=/usr/lib/postgresql/%v/lib --datadir=/usr/share/postgresql-%v-foobar" + + override_dh_auto_build: + +pg_buildext build build-%v + + override_dh_auto_test: + # nothing to do here, see debian/tests/* instead + + override_dh_auto_install: + +pg_buildext install build-%v postgresql-%v-foobar + + override_dh_installdocs: + dh_installdocs --all README.* + + override_dh_auto_clean: + +pg_buildext clean build-%v + + %: + dh $@ + +=item B + + Depends: @, postgresql-server-dev-all + Tests: installcheck + Restrictions: allow-stderr + +=item B (optional) + + Depends: @, postgresql-contrib-PGVERSION, postgresql-PGVERSION-bar + Tests: installcheck + Restrictions: allow-stderr + +=item B + + #!/bin/sh + pg_buildext installcheck + # alternatively: pg_buildext installcheck build-%v + + # Running extra code before invoking the actual action: + set -e + for v in $(pg_buildext installed-versions); do + test -L build-$v/sql || ln -s ../sql build-$v/ + test -L build-$v/expected || ln -s ../expected build-$v/ + pg_buildext installcheck-$v build-$v + done + +=back + +=head1 SOURCE DIRECTORY + +If the package source code is not in the top level directory (i.e. the directory +which has C as subdirectory), use the I argument, where +I must be an absolute path. Example: + + override_dh_auto_build: + +pg_buildext build $(CURDIR)/postgresql-module build-%v + +=head1 COMPATIBILITY + +B was introduced in postgresql-server-dev-all (>= 141~). + +The usage of "all" or "NN+" in debian/pgversions was introduced in +postgresql-server-dev-all (>= 148~). + +B was introduced in postgresql-server-dev-all (>= +153~). + +B was introduced in postgresql-common (>= 170~). + +Handling of C with B replacement was +introduced in postgresql-common (>= 171~). + +The action B was introduced in postgresql-common (>= 208~). +B was switched to use it in the same version. + +B and B, the corresponding B<--buildsystem>, and +the B and B actions were introduced in postgresql-server-dev-all (>= 217~). + +=head1 SEE ALSO + +C, autopkgtest(1), +pg_virtualenv(1). + +=head1 AUTHORS + +Dimitri Fontaine Ldim@tapoueh.orgE>, with extensions by +Christoph Berg Lmyon@debian.orgE>. -- cgit v1.2.3