diff options
Diffstat (limited to 'README-DEV')
| -rw-r--r-- | README-DEV | 102 |
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 |