Make package to be source rather than stub

1 files changed, 102 insertions, 0 deletions

diff --git a/README-DEV b/README-DEV
new file mode 100644
index 0000000..4a56908
--- /dev/null
+++ b/README-DEV
@@ -0,0 +1,102 @@
+This document describes for libpq was packages 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 are 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