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