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

The original libmariadb library is packaged together with the MariaDB server
and client utilities. All library source files are located in the libmariadb/
subdirectory. We don't need all of them since we only provide support for the
minimum set of features, the same as the upstream package does by default. We
also do not build anything except the client library (like utilities, tests,
examples or plugins). The reasonable approach for defining the required source
files is to exclude everything you have doubts about, and rely on the linker
reporting unresolved symbols. We balance between keeping the upstream package
directory structure and making sure that the library can be properly imported
into a build2 projects. Below are the packaging steps in more detail.

1. Recursively copy headers from libmariadb/include/ to mysql/.

2. Copy source files from libmariadb/zlib/ to mysql/zlib/, excluding examples
   (minigzip.c and example.c). This is a bundled third-party library, so copy
   README as well.

3. Copy source files from libmariadb/win-iconv/ to mysql/win-iconv, except
   mlang.h.

4. Recursively copy static plugins source files from libmariadb/plugins to
   mysql/plugins.

5. Recursively copy source and template files from libmariadb/libmariadb/ to
   mysql/libmariadb/, except bmove_upp.c, get_password.c, secure/gnutls.c and
   secure/openssl.c.

6. Copy libmariadb/include/mariadb_version.h.in to mysql/version.h.in, and
   create mysql/mariadb_version.h that includes <mysql/version.h>.

   Also we need to workaround MinGW __stdcall issue for 32 bit targets, adding
   some additional code to mysql/mariadb_version.h.

7. Copy libmariadb/include/ma_config.h.in to mysql/ma_config.h.in.orig, and use
   it for creating mysql/ma_config.h manually, defining/undefining only those
   macros that are used in the library source code (see below).

8. Create mysql/libmariadb/mariadbclient_win32.def.in to contain a list of the
   exported names. For that purpose grep through
   libmariadb/libmariadb/CMakeLists.txt to see how the mariadbclient.def file
   is generated for Windows. The corresponding code normally looks like

   CREATE_EXPORT_FILE(WRITE mariadbclient.def
                    "libmariadb_3"
                    "${MARIADB_LIB_SYMBOLS};${MYSQL_LIB_SYMBOLS}"
                    "")

    If that's the case, collect names that get appended to the
    MARIADB_LIB_SYMBOLS and MYSQL_LIB_SYMBOLS variables as if all IF() clauses
    are executed. Replace mariadb_deinitialize_ssl name with
    $mariadb_deinitialize_ssl$ (see mysql/buildfile for details).

9. Copy libmariadb/COPYING.LIB to COPYING.

When merge libmariadb build2 package with a new version of the upstream package
make sure that all the preprocessor include directives reference the packaged
header files, rather than MariaDB or MySQL headers that are installed into the
system. It's easy to miss some headers in the package if MariaDB or MySQL
development package is installed on the host. We also need to check if the
bundled library headers are picked up. 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 some patterns:

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

Also make sure that the macros set in mysql/ma_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 mysql/ma_config.h and compare the
sets. That can be achieved running the following commands in the build2 project
root directory:

$ for m in `cat mysql/ma_config.h.in.orig | sed -n 's/.*#\s*\(define\|cmakedefine\)\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 'ma_config.h' -o -name '*.c' -o -name '*.h.in' -o -name '*.c.in'`; then
      echo "$m"
    fi
  done >used-macros

$ cat mysql/ma_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

To obtain the pre-defined macros for gcc and clang use following commands:

$ gcc -dM -E - < /dev/null
$ clang -dM -E - < /dev/null

Note that some macro definitions are passed to the preprocessor via the -D
command line options. Such macro sets may be specific for source file
subdirectories. It makes sense to check that the sets used for the build2
package still match the ones for the new upstream package. For that purpose you
can grep the old and new upstream package CMakeList.txt files for
ADD_DEFINITIONS() directives and review the changes. If needed, you may also
run cmake for the upstream project and view the flags.make files created for
the corresponding source directories. Or, as a last resort, you can see the
actual compiler and linker command lines running make utility with VERBOSE=1
option. For VC, you need to set output verbosity to Diagnostics level at the
'Tools/Options/Projects and Solutions\Build and Run' dialog tab, change the
current directory to the project build directory in CMD console, and run the
following command:

> devenv mariadb-connector-c.sln /build >build.log

It also makes sense to check for changes in compiler and linker flags. You may
grep CMakeList.txt files for the appropriate directives, or you may compile the
upstream project in the verbose mode on the platform of interest.

Note that when configuring the upstream project for MinGW build, you need to
pass additional -G "MinGW Makefiles" option to cmake.