THIS DOCUMENT NEEDS TO BE UPDATED. THE INFO IT CONTAINS 
IS STILL VALUABLE, SO USE YOUR BRAIN :-)


README.txt
bsddb3 v6.1.x
http://www.jcea.es/programacion/pybsddb.htm
2009-06-30
--------------------------------

This module is intended to be the definitive modern Berkeley DB
interface for Python.  It should be both backwards compatible with
the earlier (circa Python 1.5 to 2.2) "bsddb" module in addition to
providing access to the much more powerful interface found in
Berkeley DB 4.x.

This module provides a nearly complete wrapping of the Oracle C API
for the Database Environment, Database, Cursor, Transaction and Lock
objects.  Each of these is exposed as a Python Type in the
bsddb3.db module.  The database objects can use different access
methods: btree, hash, recno, and queue.  For the first time all of
these are fully supported in the Python wrappers.  Please see the
documents in the docs directory for more details on the types and
methods provided.

There is also a collection of test cases in the test directory that
can be used to validate the modules, as well as giving an idea of how
to use bsddb3.db.

Thanks to The Written Word (http://thewrittenword.com/), bsddb3 was
known to pass its unit tests on these platforms:

     HP-UX        10.20, 11.00
     Tru64 UNIX   4.0D, 5.0, 5.1
     IRIX         6.2, 6.5
     Solaris      2.5.1, 2.6, 7, 8, 9, 10
     AIX          4.3.2

In addition we've run it on a several varieties of Linux and of course
on Win32.

This wrapper should be compatible with Berkeley DB releases going back
to 4.7 up to and including DB 6.1.  It should also be compatible
with Python versions 2.6, 2.7, and Python 3.2 to 3.4.


Installation
------------

If you are on a Win32 system then you can just get the binary
installer and run it and then you'll be all set.  If you want to build
it yourself, you can follow the directions below, but see the comments
in setup.py first.

If you are on a Unix/Linux system then keep reading...

The Python Distutils are used to build and install bsddb3, so it is
fairly simple to get things ready to go.

0. Check the patches directory for any updates required for the
   version of the Berkeley DB library that you have.  If a patch(s)
   are indicated in the README then apply it to your Berkeley DB
   sources and rebuild it.

1. First, make sure that you have a Berkeley DB version >= 4.7 and
   no later than 6.1 and that it is built and installed.  Setup.py will
   detect a db3 or Berkeley DB directory under either /usr/local or /usr
   in that order; this will catch installations from RPMs and most hand
   installations under Unix.  If setup.py can't find your libdb then you
   can give it a hint either in the environment (using the BERKELEYDB_DIR
   environment variable) or on the command line by specifying the
   directory containing the include and lib directory.  For example:

            python setup.py --berkeley-db=/stuff/BerkeleyDB.4.8 build

   If your Berkeley DB was built as a shared library, and if that
   shared library is not on the runtime load path, then you can
   specify the additional linker flags needed to find the shared
   library on the command line as well.  For example:

           --lflags="-Xlinker -rpath -Xlinker /stuff/BerkeleyDB.4.8/lib"

   or perhaps just

           --lflags="-R /stuff/BerkeleyDB.4.8/lib"

   Check your compiler and linker documentation to be sure.

   It is also possible to specify linking against a different library
   with the --libs switch:

           --libs="-ldb3"
           --libs="-ldb3 -lnsl"

   On some OSes distutils may not always use the correct compiler or
   linker flags.  One user reported having to add the "-lpthread" option
   in order to link with Berkeley DB that was compiled with threads on AIX.


   NOTE: My recommendation is to not rely on pre-built versions of
   Berkeley DB since on some systems there can be several versions
   already installed and it's sometimes difficult to tell which you
   are linking with when building bsddb3.  Instead get the sources
   from http://www.sleepycat.com/ and build/install it yourself as a
   static library and let setup.py find it in /usr/local.  It's not
   such a big library that you have to worry about wasting space by
   not dynamically linking and doing it this way will possibly save
   you some gray hairs.



2. From the main bsddb3 distribution directory run this command, (plus
   any extra flags needed as discussed above):

        python setup.py build

   If your Python was built with the old bsddb module built-in
   (statically linked) then the setup script will complain and you'll
   have to type "yes" to build anything.  Please see the note below
   about remedying this.


3. To run the test suite, run the following command:

        python test.py

   If you would like to see some verbose output from the tests simply
   add a -v option.  A second -v provides even more verbose output.
   The test.py driver script provides lots of options for debugging,
   running individual tests, etc.  Do "python test.py -h" for details.


4. To install the extension module and the Python modules in the
   bsddb3 package, run this command as the root user:

        python setup.py install


That's it!


Developer Information
---------------------

Both the Python and C source code is now shared with the Python
project.  If you're checking the code out from Subversion, you'll need to run
the getsvn.sh script to get a copy of the code.  How you run this
depends on whether you have write access to the Python Subversion or not
(most people do not -- you would know if you do).

To check the code out, do the following:

    % ./getsvn.sh anon

This will do an anonymous checkout of the code.  To do an
authenticated (via ssh) checkout, do the following:

    % ./getsvn.sh

This will check out an extsrc directory and a bsddb directory.  There
is one caveat: you'll find that extsrc will become populated with
every C file in Python's Modules directory.  You should just ignore this.


-- Robin
[email protected]

-- [later updates by] Gregory P. Smith
[email protected]

-- [even later updates by] Barry A. Warsaw
[email protected]

Got questions? email [email protected]