This document describes how libpq was packaged for build2. In particular,
this understanding will be useful when ugrading to a new upstream version.

The original libpq library is packaged together with the PostgreSQL server and
client utilities. Most of the libpq source files are located in the
src/interfaces/libpq/ directory. Some .c files are symlinked (copied on
Windows) from other src/ subdirectories during make. So run configure script
in the package root, run make in src/interfaces/libpq/ and then copy source
files and symlink targets into libpq/ directory of the build2 package. Note
that to obtain the full set of source files that includes Windows-specific
ones, you should perform these steps in the MSYS2/MinGW environment. Copy
Windows-specific files and strlcpy.c to libpq/win32/ and libpq/non-bsd/
directories respectively. Also copy src/port/pthread-win32.h to libpq/ (next
to pthread-win32.c).

Note that the library name in the .def file takes precedence over the one
specified in the linker command line for both VC and MinGW GCC. So we comment
it out in libpq/win32/libpqdll.def.

Besides libpq-specific files some of the PostgreSQL common headers are also
required. All of them except one (see below) are located in src/include/
subdirectories. Copy them into the libpq/postgresql/ directory, preserving the
original directory structure, with the following exceptions:

 * src/include/pg_config_os.h

   This is a symlink referencing the target-specific header in the
   src/include/port/ directory, created by the configure script. Copy these
   headers under postgresql/port/*/pg_config_os.h path names for the supported
   target classes. For example, copy src/include/port/linux.h to
   libpq/postgresql/port/linux/pg_config_os.h. During compilation the
   '-I.../libpq/postgresql/port/linux' option will be passed to the compiler,
   so the appropriate pg_config_os.h is picked up.

 * src/port/pg_config_paths.h

   This file is generated by src/port/Makfile and defines several directory
   path macros. Only SYSCONFDIR macro is used in libpq source files. Make the
   file empty and place it into libpq/postgresql directory. During compilation
   the macro will be defined with -DSYSCONFDIR preprocessor option.

 * src/include/pg_config.h.in,
   src/include/pg_config.h.win32
   pg_config_ext.h.in
   pg_config_ext.h.win32

   Use as sources for the manual creation of libpq/postgresql/pg_config.h and
   libpq/postgresql/pg_config_ext.h, that are used for all target systems.
   Also add the source headers to the package appending the '.orig' extension
   to their names.

By default the original package installs the library into the /usr/local/pgsql
directory. There are also several 'unofficial API' headers installed into the
/usr/local/pgsql/include/internal directory. If installing at some custom
location that has no postgresql or pgsql words in its path, then it becomes
<custom-location>/include/postgresql/internal. We currently do not  install
unofficial API headers.

For the record, the PostgreSQL binary and development packages install
libraries and headers into the following directories:

Debian/Ubuntu:
  /usr/lib/x86_64-linux-gnu
  /usr/include/postgresql
  /usr/include/postgresql/internal

Fedora/RHEL:
  /usr/lib64
  /usr/include
  /usr/include/pgsql/internal

When merge libpq build2 package with a new version of the original package
make sure that all the preprocessor include directives reference the packaged
header files, rather than PostgreSQL headers that are installed into the
system. It's easy to miss some headers in the package if the PostgreSQL
development package is installed on the host. To verify the correctness you
can build the merged project, concatenate the produced .d files, sort the
resulting file removing duplicates and edit the result, leaving only the
system headers. Afterwards grep through the remained headers for the
'PostgreSQL' pattern:

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

Also make sure that the macros set in libpq/postgresql/pg_config.h is still up
to date. For that purpose obtain the macros that are used in the new source
base, then obtain the macros (un)defined in the current
libpq/postgresql/pg_config.h and compare the sets. That can be achieved
running the following commands in the build2 project root directory:

$ for m in `cat libpq/postgresql/pg_config.h.in.orig libpq/postgresql/pg_config.h.win32.orig | sed -n 's/.*#\s*\(define\|undef\)\s\{1,\}\([_A-Z0-9]\{1,\}\)\(\s.*\)\{0,1\}$/\2/p' | sort -u`; do
    if grep -q -e "\b$m\b" `find . -name '*.h' -a ! -name 'pg_config.h' -o -name '*.c'`; then
      echo "$m"
    fi
  done >used-macros

$ cat libpq/postgresql/pg_config.h |
  sed -n 's/#\s*\(define\|undef\)\s\{1,\}\([_A-Z0-9]\{1,\}\)\(\s.*\)\{0,1\}$/\2/p' |
  sort -u >defined-macros

$ diff defined-macros used-macros