summaryrefslogtreecommitdiff
path: root/README-DEV
blob: c7ba5e1210ad73071f1db5adef03651b9b5952e0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
This document describes an approach applied to packaging PostgreSQL for
build2. In particular, this understanding will be useful when upgrading to a
new upstream version.

The upstream package contains the PostgreSQL server, libpq library, and client
utilities. Currently, we only package libpq (see libpq/README-DEV for
details).

We add the upstream package as a git submodule and symlink the required files
and subdirectories into the build2 package subdirectories. Then, when required,
we "overlay" the upstream with our own headers, placing them into the library
directory.

Note that symlinking upstream submodule subdirectories into a build2 package
subdirectory results in creating intermediate build files (.d, .o, etc) inside
upstream directory while building the package in source tree. That's why we
need to make sure that packages do not share upstream source files via
subdirectory symlinks, not to also share the related intermediate files. If
several packages need to compile the same upstream source file, then only one
of them can symlink it via the parent directory while others must symlink it
directly. We also add the `ignore = untracked` configuration option into
.gitmodules to make sure that git ignores the intermediate build files under
upstream/ subdirectory.

The upstream package can be configured to contain a specific feature set. We
reproduce the union of features configured for the upstream source package in
Debian and Fedora distributions. The configuration options defining these sets
are specified in the Debian's rules and Fedora's RPM .spec files. Note,
that at the time of this writing the latest packaged versions are different
(12.1 on Debian and 11.6 on Fedora). That's probably ok since 12.1 doesn't
introduce any new configuration options comparing to 11.6. These files can be
obtained as follows:

$ wget http://deb.debian.org/debian/pool/main/p/postgresql-12/postgresql-12_12.1-1.debian.tar.xz
$ tar xf postgresql-12_12.1-1.debian.tar.xz debian/rules

$ wget https://kojipkgs.fedoraproject.org/packages/libpq/11.6/1.fc32/src/libpq-11.6-1.fc32.src.rpm
$ rpm2cpio libpq-11.6-1.fc32.src.rpm | cpio -civ '*.spec'

As a side note, on Debian and Fedora the source, library, and headers are
packaged as follows:

                src            libpq   headers
Debian/Ubuntu:  postgresql-12  libpq5  libpq-dev
Fedora/RHEL:    libpq          libpq   libpq-devel

Search for the Debian and Fedora packages at https://packages.debian.org/search
and https://apps.fedoraproject.org/packages/.

Here are the discovered configuration options.

Debian:

  --with-icu --with-tcl --with-perl --with-python --with-pam --with-openssl
  --with-libxml --with-libxslt --enable-nls --enable-integer-datetimes
  --with-gssapi --with-ldap --enable-thread-safety

Fedora:

  --with-ldap --with-openssl --with-gssapi --enable-nls --without-readline

The union of these feature sets translates into the following options, after
suppressing the defaults:

  --with-icu --with-tcl --with-perl --with-python --with-pam --with-openssl
  --with-libxml --with-libxslt --enable-nls --with-gssapi --with-ldap

We, however, drop the external dependencies that are not packaged for build2
and end up with the following options:

  --with-openssl --without-readline --without-zlib

See the configuration options description at the "Installation Procedure" page
(https://www.postgresql.org/docs/current/install-procedure.html).

Normally, when packaging a project, we need to replace some auto-generated
headers with our own implementations and deduce compilation/linking options.
For PostgreSQL we can rely on the configure.in, GNUmakefile.in, and the
manually maintained makefiles for that. In practice, however, that can be
uneasy and error prone, so you may also need to refer to auto-generated
header files or to see the actual compiler and linker command lines in the
build log. If that's the case, you can configure/build the upstream package on
the platform of interest running the following commands in the upstream
project root directory.

On POSIX and for MinGW GCC:

$ mkdir build
$ cd build
$ ../configure --with-openssl --without-readline --without-zlib >build.log 2>&1
$ cd src/interfaces/libpq
$ make >>../../../build.log 2>&1

See the "Installation from Source Code" page
(https://www.postgresql.org/docs/current/installation.html) for details.

For MSVC:

Add bison and flex to PATH, if building in the git repository. Install
OpenSSL.

> cd src\tools\msvc

Edit config_default.pl to enable OpenSSL:

  openssl   => 'c:\OpenSSL',    # --with-openssl=<path>

> build libpq >>build.log 2>&1

See the "Building with Visual C++ or the Microsoft Windows SDK" page
(https://www.postgresql.org/docs/current/install-windows-full.html) for
details.

When the packaging is complete, build all the project packages in source tree
and make sure that no PostgreSQL headers are included from the system, running
the following commands from the project root:

$ cat `find . -name '*.d'` | sort -u >headers
$ emacs headers  # Edit, leaving system headers only.
$ fgrep PostgreSQL <headers