path: root/README-DEV
diff options
authorKaren Arutyunov <karen@codesynthesis.com>2017-09-21 01:02:04 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2017-10-09 19:14:35 +0300
commit2a969b7f4bdb223d3626dc14b684701942ccafb2 (patch)
tree5b317acd47e5183b7dd127417cd0017c39f28f94 /README-DEV
parent05ac4b76f5d30def9d51815c7f25d54316592f45 (diff)
Make package to be source rather than stub
Diffstat (limited to 'README-DEV')
1 files changed, 102 insertions, 0 deletions
diff --git a/README-DEV b/README-DEV
new file mode 100644
index 0000000..4a56908
--- /dev/null
@@ -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:
+ /usr/lib/x86_64-linux-gnu
+ /usr/include/postgresql
+ /usr/include/postgresql/internal
+ /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