Document internal vs external BDB usage in INSTALL

1 files changed, 36 insertions, 4 deletions

diff --git a/INSTALL b/INSTALL
index 79b0c6ebb..710c74311 100644
--- a/INSTALL
+++ b/INSTALL
@@ -8,10 +8,42 @@ the zip executable for java jar dependency analysis. All available from
 The NSS library for encryption. This is available from 
     http://www.mozilla.org/projects/security/pki/nss/
 
-The Berkeley DB >= 4.3.x (4.5.x or newer recommended). RPM includes an
-internal copy which is used by default, but if you want to use an external
-BDB (--with-external-db) it's available at
-    http://www.oracle.com/technology/software/products/berkeley-db/index.html
+The Berkeley DB >= 4.3.x (4.5.x or newer recommended) is required for the
+default database backend. BDB can be downloaded from
+http://www.oracle.com/technology/software/products/berkeley-db/index.html
+
+RPM supports two different ways to include it, both methods have their 
+distinct advantages and disadvantages:
+
+1) Building and using an internal copy of BDB
+   
+   This is the "safe" way: upgrades to system BDB can not affect your
+   rpmdb integrity and you have full control over how BDB is configured. 
+   On the other hand, any updates (security or bugfix) to BDB will require 
+   rebuilding RPM. 
+
+   To use this method, download a recent version of BDB from the URL above,
+   expand the tarball into rpm source directory root and create "db" symlink
+   to it, eg:
+   $ wget http://download.oracle.com/berkeley-db/db-4.5.20.tar.gz
+   $ tar xzf db-4.5.20.tar.gz
+   $ ln -s db-4.5.20 db
+   $ ./configure [other options...]
+
+2) Linking to external (system) BDB
+
+   If you can control when and how system BDB is upgraded, this option
+   saves space, removes the need to rebuild RPM in case of security etc
+   updates to BDB and also makes build rpm itself much faster. On the other
+   hand, major BDB upgrades can be disruptive, especially if
+   the on-disk format changes somehow. 
+
+   To use this method, simply pass in --with-external-db to ./configure
+   script. If the system BDB is installed outside compiler + linker default
+   paths, you can use CPPFLAGS and LDFLAGS to tell configure where to look,
+   for example:
+
+   $ ./configure --with-external-db CPPFLAGS=-I/usr/include/db45
 
 Minimal instructions for building BDB are 
     cd build_unix