                                   BerkeleyDB

                                  Version 0.07

                                 21st Sep 1999

	Copyright (c) 1997-1999 Paul Marquess. All rights reserved. This
	program is free software; you can redistribute it and/or modify
	it under the same terms as Perl itself.


DESCRIPTION
-----------

BerkeleyDB is a module which allows Perl programs to make use of the
facilities provided by Berkeley DB version 2 or 3. (Note: if you want
to use version 1 of Berkeley DB with Perl you need the DB_File module).

Berkeley DB is a C library which provides a consistent interface to a
number of database formats. BerkeleyDB provides an interface to all
three of the database types (hash, btree and recno) currently supported
by Berkeley DB.

For further details see the documentation included at the end of the
file BerkeleyDB.pm.

PREREQUISITES
-------------

Before you can build BerkeleyDB you need to have the following
installed on your system:

    * Perl 5.004_04 or greater.

    * Berkeley DB Version 2.6.4 or greater

      The official web site for Berkeley DB is http://www.sleepycat.com

      The latest version of Berkeley DB is always available there. It
      is recommended that you use the most recent version available at
      the Sleepycat site.

      The one exception to this advice is where you want to use BerkeleyDB
      to access database files created by a third-party application,
      like Sendmail. In these cases you must build BerkeleyDB with a
      compatible version of Berkeley DB.



BUILDING THE MODULE
-------------------

Assuming you have met all the prerequisites, building the module should
be relatively straightforward.

Step 1 : If you are running either Solaris 2.5 or HP-UX 10 read either
         the Solaris Notes or HP-UX Notes sections below.

Step 2 : Edit the file config.in to suit you local installation.
         Instructions are given in the file.

Step 3 : Build and test the module using using this sequence of commands:

             perl Makefile.PL
             make
             make test

INSTALLATION
------------

    make install

TROUBLESHOOTING
===============

Here are some of the problems that people encounter when building BerkeleyDB.

Missing db.h or libdb.a
-----------------------

If you get an error like this:

  cc -c -I./libraries/ -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
  -DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
  -I/usr/local/lib/perl5/5.00503/i586-linux/CORE  BerkeleyDB.c
  BerkeleyDB.xs:52: db.h: No such file or directory

or this:

  cc -c -I./libraries/2.7.5 -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
  -DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
  -I/usr/local/lib/perl5/5.00503/i586-linux/CORE  BerkeleyDB.c
  LD_RUN_PATH="/lib" cc -o blib/arch/auto/BerkeleyDB/BerkeleyDB.so  -shared
  -L/usr/local/lib BerkeleyDB.o
  -L/home/paul/perl/ext/BerkDB/BerkeleyDB/libraries -ldb
  ld: cannot open -ldb: No such file or directory

This symptom can imply:

 1. You don't have Berkeley DB installed on your system at all.
    Solution: get & install Berkeley DB.

 2. You do have Berkeley DB installed, but it isn't in a standard place.
    Solution: Edit config.in and set the LIB and INCLUDE variables to point
              to the directories where libdb.a and db.h are installed.

Wrong db.h
----------

If you get an error like this when building this module:

  cc -c -I./libraries/ -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
  -DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
  -I/usr/local/lib/perl5/5.00503/i586-linux/CORE  BerkeleyDB.c
  BerkeleyDB.xs:93: parse error before `DB_INFO'
  BerkeleyDB.xs:93: warning: no semicolon at end of struct or union
  BerkeleyDB.xs:94: warning: data definition has no type or storage class
  BerkeleyDB.xs:95: parse error before `0x80000000'
  BerkeleyDB.xs:110: parse error before `}'
  BerkeleyDB.xs:110: warning: data definition has no type or storage class
  BerkeleyDB.xs:117: parse error before `DB_ENV'
  ...

This error usually happens when if you only have Berkeley DB version 1
on your system or you have both version 1 and version 2 (or 3) of Berkeley
DB installed on your system. When building BerkeleyDB it attempts attempts
to use the db.h for Berkeley DB version 1. This perl module can only
be built with Berkeley DB version 2 or 3.

This symptom can imply:

 1. You don't have Berkeley DB version 2 or 3 installed on your system
    at all.
    Solution: get & install Berkeley DB.

 2. You do have Berkeley DB 2 or 3 installed, but it isn't in a standard
    place.
    Solution: Edit config.in and set the LIB and INCLUDE variables
              to point to the directories where libdb.a and db.h are
              installed.

Undefined Symbol: txn_stat 
--------------------------

BerkeleyDB seems to have built correctly, but you get an error like this
when you run the test harness:

  $ make test
  PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00503
  -Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5.00503/i586-linux
  -I/usr/local/lib/perl5/5.00503 -e 'use Test::Harness qw(&runtests $verbose);
  $verbose=0; runtests @ARGV;' t/*.t
  t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
  module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
  undefined symbol: txn_stat
  at /usr/local/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.
  ...

This error usually happens when you have both version 1 and version
2 (or 3) of Berkeley DB installed on your system and BerkeleyDB attempts
to build using the db.h for Berkeley DB version 2/3 and the version 1
library. Unfortunately the two versions aren't compatible with each
other. BerkeleyDB can only be built with Berkeley DB version 2 or 3.

Solution: Setting the LIB & INCLUDE variables in config.in to point to the
          correct directories can sometimes be enough to fix this
          problem. If that doesn't work the easiest way to fix the
          problem is to either delete or temporarily rename the copies
          of db.h and libdb.a that you don't want BerkeleyDB to use.

Undefined Symbol: db_appinit 
----------------------------

BerkeleyDB seems to have built correctly, but you get an error like this
when you run the test harness:

  $ make test
  PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00561 -Iblib/arch 
  -Iblib/lib -I/home/paul/perl/install/5.005_61/lib/5.00561/i586-linux 
  -I/home/paul/perl/install/5.005_61/lib/5.00561 -e 'use Test::Harness 
  qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
  t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for 
  module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so: 
  undefined symbol: db_appinit 
  at /home/paul/perl/install/5.005_61/lib/5.00561/i586-linux/DynaLoader.pm 
  ...


This error usually happens when you have both version 2 and version
3 of Berkeley DB installed on your system and BerkeleyDB attempts
to build using the db.h for Berkeley DB version 2 and the version 3
library. Unfortunately the two versions aren't compatible with each
other. 

Solution: Setting the LIB & INCLUDE variables in config.in to point to the
          correct directories can sometimes be enough to fix this
          problem. If that doesn't work the easiest way to fix the
          problem is to either delete or temporarily rename the copies
          of db.h and libdb.a that you don't want BerkeleyDB to use.

Undefined Symbol: db_create
---------------------------

BerkeleyDB seems to have built correctly, but you get an error like this
when you run the test harness:

  $ make test   
  PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00561 -Iblib/arch 
  -Iblib/lib -I/home/paul/perl/install/5.005_61/lib/5.00561/i586-linux 
  -I/home/paul/perl/install/5.005_61/lib/5.00561 -e 'use Test::Harness 
  qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
  t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for 
  module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so: 
  undefined symbol: db_create 
  at /home/paul/perl/install/5.005_61/lib/5.00561/i586-linux/DynaLoader.pm 
  ...

This error usually happens when you have both version 2 and version
3 of Berkeley DB installed on your system and BerkeleyDB attempts
to build using the db.h for Berkeley DB version 3 and the version 2
library. Unfortunately the two versions aren't compatible with each
other. 

Solution: Setting the LIB & INCLUDE variables in config.in to point to the
          correct directories can sometimes be enough to fix this
          problem. If that doesn't work the easiest way to fix the
          problem is to either delete or temporarily rename the copies
          of db.h and libdb.a that you don't want BerkeleyDB to use.


Incompatable versions of db.h and libdb
---------------------------------------

BerkeleyDB seems to have built correctly, but you get an error like this
when you run the test harness:

  $ make test
  PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00503
  -Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5.00503/i586-linux
  -I/usr/local/lib/perl5/5.00503 -e 'use Test::Harness qw(&runtests $verbose);
  $verbose=0; runtests @ARGV;' t/*.t
  t/btree.............
  BerkeleyDB needs compatible versions of libdb & db.h
          you have db.h version 2.6.4 and libdb version 2.7.5
  BEGIN failed--compilation aborted at t/btree.t line 25.
  dubious
        Test returned status 255 (wstat 65280, 0xff00)
  ...	

Another variation on the theme of having two versions of Berkeley DB on
your system. 

Solution: Setting the LIB & INCLUDE variables in config.in to point to the
          correct directories can sometimes be enough to fix this
          problem. If that doesn't work the easiest way to fix the
          problem is to either delete or temporarily rename the copies
          of db.h and libdb.a that you don't want BerkeleyDB to use.


Solaris Notes
-------------

If you are running Solaris 2.5, and you get this error when you run the
BerkeleyDB test harness:

    libc internal error: _rmutex_unlock: rmutex not held.

you probably need to install a Sun patch. It has been reported that
Sun patch 103187-25 (or later revisions) fixes this problem.

To find out if you have the patch installed, the command "showrev -p"
will display the patches that are currently installed on your system.



HP-UX Notes
-----------

Some people running HP-UX 10 have reported getting an error like this
when building this module with the native HP-UX compiler.

    ld: (Warning) At least one PA 2.0 object file (BerkeleyDB.o) was detected.
    The linked output may not run on a PA 1.x system.
    ld: Invalid loader fixup for symbol "$000000A5".

If this is the case for you, Berkeley DB needs to be recompiled with
the +z or +Z option and the resulting library placed in a .sl file. The
following steps should do the trick:

  1: Configure the Berkeley DB distribution with the +z or +Z C compiler
     flag:

        env "CFLAGS=+z" ../dist/configure ...

  2: Edit the Berkeley DB Makefile and change:

        "libdb= libdb.a" to "libdb= libdb.sl".

  3: Build and install the Berkeley DB distribution as usual.



FEEDBACK
--------

How to report a problem with BerkeleyDB.

To help me help you, I need of the following information:

 1. The version of Perl and the operating system name and version you
    are running. The output from running "perl -V" will tell me all I
    need to know.
    If your perl does not understand the "-V" option is is too old.
    BerkeleyDB needs Perl version 5.004_04 or better.

 2. The version of BerkeleyDB you have. If you have successfully
    installed BerkeleyDB, this one-liner will tell you:

       perl -MBerkeleyDB -e 'print "BerkeleyDB ver $BerkeleyDB::VERSION\n"'

    If you haven't installed BerkeleyDB then search BerkeleyDB.pm for a
    line like this:

      $VERSION = "1.20" ;

 3. The version of Berkeley DB you have installed. If you have
    successfully installed BerkeleyDB, this one-liner will tell you:

        perl -MBerkeleyDB -e 'print BerkeleyDB::DB_VERSION_STRING."\n"'

    If you haven't installed BerkeleyDB then search db.h for a line
    like this:

      #define DB_VERSION_STRING

 4. If you are having problems building BerkeleyDB, send me a complete
    log of what happened.

 5. Now the difficult one. If you think you have found a bug in
    BerkeleyDB and you want me to fix it, you will *greatly* enhance
    the chances of me being able to track it down by sending me a small
    self-contained Perl script that illustrates the problem you are
    encountering. Include a summary of what you think the problem is
    and a log of what happens when you run the script, in case I can't
    reproduce your problem on my system. If possible, don't have the
    script dependent on an existing 20Meg database. If the script you
    send me can create the database itself then that is preferred.

    I realise that in some cases this is easier said than done, so if
    you can only reproduce the problem in your existing script, then
    you can post me that if you want. Just don't expect me to find your
    problem in a hurry, or at all. :-)


CHANGES
-------

See the Changes file.

Paul Marquess <Paul.Marquess@btinternet.com>

