Add implementation

1 files changed, 116 insertions, 0 deletions

diff --git a/README-DEV b/README-DEV
new file mode 100644
index 0000000..aacc371
--- /dev/null
+++ b/README-DEV
@@ -0,0 +1,116 @@
+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.