path: root/README-DEV
diff options
authorKaren Arutyunov <karen@codesynthesis.com>2017-11-03 22:17:16 (GMT)
committerKaren Arutyunov <karen@codesynthesis.com>2017-11-24 02:06:39 (GMT)
commit43d743e75b7b747341b9a5c36a933b490548bebb (patch)
tree03d3c056929c9b8f51dd5d7cbd42c544f14c591b /README-DEV
parent9b1a5c3c0633240b2da16e57503cb67c392fdb3d (diff)
Add implementation
Diffstat (limited to 'README-DEV')
1 files changed, 116 insertions, 0 deletions
diff --git a/README-DEV b/README-DEV
new file mode 100644
index 0000000..aacc371
--- /dev/null
@@ -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"
+ "")
+ 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.