notes/alternate-bdb-version

   1 This file contains brief notes on building Subversion using a version of
   2 Berkeley DB other than that which APR-util is linked to.
   3
   4 This is not an officially supported configuration, but can occasionally be a
   5 useful thing to do.
   6
   7 Section 1: Building Berkeley DB
   8 -------------------------------
   9
  10 It is necessary that the Berkeley DB installation you build not conflict with
  11 the one that _is_ linked to APR-util, in two ways:
  12
  13  1) In the filesystem.
  14     If you are installing to a separate prefix, this is not a problem.
  15     If, on the other hand, you are preparing a system package for installation
  16     under /usr, you must delete or rename several things after running
  17     'make install', but before your packaging system gathers the files into
  18     the final package:
  19
  20     lib: Delete libdb.a, libdb.so and libdb-4.so, which should leave you with
  21       only files containing the full 4.X version of Berkeley DB in
  22       their names.
  23
  24     bin: Rename each executable replacing the string "db_" with "db4.X_" in
  25       each case.
  26
  27     include: Move all the include files that are installed into a subdirectory
  28       called "db-4.X".  Additionally, create a symlink within this
  29       subdirectory called "db4", pointing to ".".  This is because APR-util
  30       may well be attempting to include <db4/db.h>.  See the file apu_want.h
  31       to know whether this symlink is actually required on your system.
  32
  33     docs: Put the installed Berkeley DB documentation for this version
  34       whereever seems appropriate for your distribution.
  35
  36
  37   2) In symbol names.
  38      A more insidious kind of potential conflict exists where mod_dav_svn is
  39      concerned.  Without care, due to the way some dynamic linkers work, when
  40      loaded within Apache HTTPD, libsvn_fs_base may dynamically resolve the
  41      Berkeley DB symbols via the already-loaded APR-util, rather than the
  42      intended version.  Fortunately, Berkeley DB comes ready-equipped with a
  43      way to prevent this.  You must configure Berkeley DB with the parameter
  44      --with-uniquename=_someuniquestring.  Personally, I suggest _db4X.  This
  45      will result in the Berkeley DB symbols being suffixed with this string,
  46      avoiding the mentioned problem.
  47
  48
  49 Section 2: Building Subversion
  50 ------------------------------
  51
  52 OK, you have a suitable version of Berkeley DB.  Now you need to trick
  53 Subversion into linking with it, despite the fact that Subversion's build
  54 system is geared to taking the Berkeley DB linkage options from APR-util.
  55
  56 Ensure that the development packages for the version of Berkeley DB that your
  57 APR-util is linked to _are_ installed, because we want configure to find a
  58 working Berkeley DB, so we can just override its choice of installation with
  59 some Makefile editing later.
  60
  61 Configure Subversion as normal, then edit the Makefile:
  62
  63 Alter the definition of SVN_APRUTIL_LIBS, removing any existing -ldb, -ldb4,
  64 or -ldb-4.X option, and add *at the beginning*, the appropriate -ldb-4.X
  65 option for your desired Berkeley DB version.  Add an -L/path/to/libs option if
  66 needed.
  67
  68 Alter the definition of INCLUDES, adding *at the beginning*, the appropriate
  69 -I/usr/include/db-4.X option.
  70
  71 Last issue: Despite this meddling, libtool still fetches a -ldb option for the
  72 version of Berkeley DB linked to APR-util from the APR-util .la file, and uses
  73 it when linking the command line programs.  Because of the use of
  74 --with-uniquename above, this is not a problem per se, but it does result, on
  75 Linux, in the addition of spurious DT_NEEDED dependency records to the
  76 binaries, such that they claim to be dependent on BOTH the alternate AND
  77 APR-util versions of Berkeley DB, despite the fact they never invoke code in
  78 the linked-to-APR-util version.  This can be avoided by setting
  79 EXTRA_LDFLAGS="-Wl,--as-needed", though you should be aware that this will
  80 likely strip off several other DT_NEEDED records too, none of which should be
  81 necessary, but with the complexities of shared library linking, you should
  82 probably test that this hasn't had any unforeseen side-effects.
  83
  84 Now make.  If all goes well, your newly built Subversion should be using your
  85 alternate Berkeley DB version.