7
Copyright (c) 1997-2002 Paul Marquess. All rights reserved. This
8
program is free software; you can redistribute it and/or modify
9
it under the same terms as Perl itself.
15
BerkeleyDB is a module which allows Perl programs to make use of the
16
facilities provided by Berkeley DB version 2 or greater. (Note: if
17
you want to use version 1 of Berkeley DB with Perl you need the DB_File
20
Berkeley DB is a C library which provides a consistent interface to a
21
number of database formats. BerkeleyDB provides an interface to all
22
four of the database types (hash, btree, queue and recno) currently
23
supported by Berkeley DB.
25
For further details see the documentation in the file BerkeleyDB.pod.
30
Before you can build BerkeleyDB you need to have the following
31
installed on your system:
33
* Perl 5.004_04 or greater.
35
* Berkeley DB Version 2.6.4 or greater
37
The official web site for Berkeley DB is http://www.sleepycat.com
39
The latest version of Berkeley DB is always available there. It
40
is recommended that you use the most recent version available at
43
The one exception to this advice is where you want to use BerkeleyDB
44
to access database files created by a third-party application,
45
like Sendmail. In these cases you must build BerkeleyDB with a
46
compatible version of Berkeley DB.
52
Assuming you have met all the prerequisites, building the module should
53
be relatively straightforward.
55
Step 1 : If you are running Solaris 2.5, 2.7 or HP-UX 10 read either
56
the Solaris Notes or HP-UX Notes sections below.
57
If you are running Linux please read the Linux Notes section
61
Step 2 : Edit the file config.in to suit you local installation.
62
Instructions are given in the file.
64
Step 3 : Build and test the module using this sequence of commands:
78
Here are some of the problems that people encounter when building BerkeleyDB.
80
Missing db.h or libdb.a
81
-----------------------
83
If you get an error like this:
85
cc -c -I./libraries/ -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
86
-DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
87
-I/usr/local/lib/perl5/5.00503/i586-linux/CORE BerkeleyDB.c
88
BerkeleyDB.xs:52: db.h: No such file or directory
92
cc -c -I./libraries/2.7.5 -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
93
-DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
94
-I/usr/local/lib/perl5/5.00503/i586-linux/CORE BerkeleyDB.c
95
LD_RUN_PATH="/lib" cc -o blib/arch/auto/BerkeleyDB/BerkeleyDB.so -shared
96
-L/usr/local/lib BerkeleyDB.o
97
-L/home/paul/perl/ext/BerkDB/BerkeleyDB/libraries -ldb
98
ld: cannot open -ldb: No such file or directory
100
This symptom can imply:
102
1. You don't have Berkeley DB installed on your system at all.
103
Solution: get & install Berkeley DB.
105
2. You do have Berkeley DB installed, but it isn't in a standard place.
106
Solution: Edit config.in and set the LIB and INCLUDE variables to point
107
to the directories where libdb.a and db.h are installed.
109
#error db.h is not for Berkeley DB at all.
110
------------------------------------------
112
If you get the error above when building this module it means that there
113
is a file called "db.h" on your system that isn't the one that comes
118
1. You don't have Berkeley DB installed on your system at all.
119
Solution: get & install Berkeley DB.
121
2. Edit config.in and make sure the INCLUDE variable points to the
122
directory where the Berkeley DB file db.h is installed.
124
3. If option 2 doesn't work, try tempoarily renaming the db.h file
125
that is causing the error.
127
#error db.h is for Berkeley DB 1.x - need at least Berkeley DB 2.6.4
128
--------------------------------------------------------------------
130
The error above will occur if there is a copy of the Berkeley DB 1.x
131
file db.h on your system.
133
This error will happen when
135
1. you only have Berkeley DB version 1 on your system.
136
Solution: get & install a newer version of Berkeley DB.
138
2. you have both version 1 and a later version of Berkeley DB
139
installed on your system. When building BerkeleyDB it attempts to
140
use the db.h for Berkeley DB version 1.
141
Solution: Edit config.in and set the LIB and INCLUDE variables
142
to point to the directories where libdb.a and db.h are
146
#error db.h is for Berkeley DB 2.0-2.5 - need at least Berkeley DB 2.6.4
147
------------------------------------------------------------------------
149
The error above will occur if there is a copy of the the file db.h for
150
Berkeley DB 2.0 to 2.5 on your system.
152
This symptom can imply:
154
1. You don't have a new enough version of Berkeley DB.
155
Solution: get & install a newer version of Berkeley DB.
157
2. You have the correct version of Berkeley DB installed, but it isn't
159
Solution: Edit config.in and set the LIB and INCLUDE variables
160
to point to the directories where libdb.a and db.h are
163
Undefined Symbol: txn_stat
164
--------------------------
166
BerkeleyDB seems to have built correctly, but you get an error like this
167
when you run the test harness:
170
PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00503
171
-Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5.00503/i586-linux
172
-I/usr/local/lib/perl5/5.00503 -e 'use Test::Harness qw(&runtests $verbose);
173
$verbose=0; runtests @ARGV;' t/*.t
174
t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
175
module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
176
undefined symbol: txn_stat
177
at /usr/local/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.
180
This error usually happens when you have both version 1 and a newer version
181
of Berkeley DB installed on your system. BerkeleyDB attempts
182
to build using the db.h for Berkeley DB version 2/3/4 and the version 1
183
library. Unfortunately the two versions aren't compatible with each
184
other. BerkeleyDB can only be built with Berkeley DB version 2, 3 or 4.
186
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
187
correct directories can sometimes be enough to fix this
188
problem. If that doesn't work the easiest way to fix the
189
problem is to either delete or temporarily rename the copies
190
of db.h and libdb.a that you don't want BerkeleyDB to use.
192
Undefined Symbol: db_appinit
193
----------------------------
195
BerkeleyDB seems to have built correctly, but you get an error like this
196
when you run the test harness:
199
PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00561 -Iblib/arch
200
-Iblib/lib -I/home/paul/perl/install/5.005_61/lib/5.00561/i586-linux
201
-I/home/paul/perl/install/5.005_61/lib/5.00561 -e 'use Test::Harness
202
qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
203
t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
204
module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
205
undefined symbol: db_appinit
206
at /home/paul/perl/install/5.005_61/lib/5.00561/i586-linux/DynaLoader.pm
210
This error usually happens when you have both version 2 and version
211
3 of Berkeley DB installed on your system and BerkeleyDB attempts
212
to build using the db.h for Berkeley DB version 2 and the version 3
213
library. Unfortunately the two versions aren't compatible with each
216
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
217
correct directories can sometimes be enough to fix this
218
problem. If that doesn't work the easiest way to fix the
219
problem is to either delete or temporarily rename the copies
220
of db.h and libdb.a that you don't want BerkeleyDB to use.
222
Undefined Symbol: db_create
223
---------------------------
225
BerkeleyDB seems to have built correctly, but you get an error like this
226
when you run the test harness:
229
PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00561 -Iblib/arch
230
-Iblib/lib -I/home/paul/perl/install/5.005_61/lib/5.00561/i586-linux
231
-I/home/paul/perl/install/5.005_61/lib/5.00561 -e 'use Test::Harness
232
qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
233
t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
234
module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
235
undefined symbol: db_create
236
at /home/paul/perl/install/5.005_61/lib/5.00561/i586-linux/DynaLoader.pm
239
This error usually happens when you have both version 2 and version
240
3 of Berkeley DB installed on your system and BerkeleyDB attempts
241
to build using the db.h for Berkeley DB version 3 and the version 2
242
library. Unfortunately the two versions aren't compatible with each
245
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
246
correct directories can sometimes be enough to fix this
247
problem. If that doesn't work the easiest way to fix the
248
problem is to either delete or temporarily rename the copies
249
of db.h and libdb.a that you don't want BerkeleyDB to use.
252
Incompatible versions of db.h and libdb
253
---------------------------------------
255
BerkeleyDB seems to have built correctly, but you get an error like this
256
when you run the test harness:
259
PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00503
260
-Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5.00503/i586-linux
261
-I/usr/local/lib/perl5/5.00503 -e 'use Test::Harness qw(&runtests $verbose);
262
$verbose=0; runtests @ARGV;' t/*.t
264
BerkeleyDB needs compatible versions of libdb & db.h
265
you have db.h version 2.6.4 and libdb version 2.7.5
266
BEGIN failed--compilation aborted at t/btree.t line 25.
268
Test returned status 255 (wstat 65280, 0xff00)
271
Another variation on the theme of having two versions of Berkeley DB on
274
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
275
correct directories can sometimes be enough to fix this
276
problem. If that doesn't work the easiest way to fix the
277
problem is to either delete or temporarily rename the copies
278
of db.h and libdb.a that you don't want BerkeleyDB to use.
279
If you are running Linux, please read the Linux Notes section below.
285
Newer versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library
286
that has version 2.x of Berkeley DB linked into it. This makes it
287
difficult to build this module with anything other than the version of
288
Berkeley DB that shipped with your Linux release. If you do try to use
289
a different version of Berkeley DB you will most likely get the error
290
described in the "Incompatible versions of db.h and libdb" section of
293
To make matters worse, prior to Perl 5.6.1, the perl binary itself
294
*always* included the Berkeley DB library.
296
If you want to use a newer version of Berkeley DB with this module, the
297
easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x
300
There are two approaches you can use to get older versions of Perl to
301
work with specific versions of Berkeley DB. Both have their advantages
304
The first approach will only work when you want to build a version of
305
Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use
306
Berkeley DB 2.x, you must use the next approach. This approach involves
307
rebuilding your existing version of Perl after applying an unofficial
308
patch. The "patches" directory in the this module's source distribution
309
contains a number of patch files. There is one patch file for every
310
stable version of Perl since 5.004. Apply the appropriate patch to your
311
Perl source tree before re-building and installing Perl from scratch.
312
For example, assuming you are in the top-level source directory for
313
Perl 5.6.0, the command below will apply the necessary patch. Remember
314
to replace the path shown below with one that points to this module's
317
patch -p1 -N </path/to/BerkeleyDB/patches/5.6.0
319
Now rebuild & install perl. You should now have a perl binary that can
320
be used to build this module. Follow the instructions in "BUILDING THE
321
MODULE", remembering to set the INCLUDE and LIB variables in config.in.
324
The second approach will work with Berkeley DB 2.x or better.
325
Start by building Berkeley DB as a shared library. This is from
326
the Berkeley DB build instructions:
328
Building Shared Libraries for the GNU GCC compiler
330
If you're using gcc and there's no better shared library example for
331
your architecture, the following shared library build procedure will
334
Add the -fpic option to the CFLAGS value in the Makefile.
336
Rebuild all of your .o files. This will create a Berkeley DB library
337
that contains .o files with PIC code. To build the shared library,
338
then take the following steps in the library build directory:
343
% gcc -shared -o libdb.so *.o
348
Note, you may have to change the gcc line depending on the
349
requirements of your system.
351
The file libdb.so is your shared library
353
Once you have built libdb.so, you will need to store it somewhere safe.
355
cp libdb.so /usr/local/BerkeleyDB/lib
357
If you now set the LD_PRELOAD environment variable to point to this
358
shared library, Perl will use it instead of the version of Berkeley DB
359
that shipped with your Linux distribution.
361
export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so
363
Finally follow the instructions in "BUILDING THE MODULE" to build,
364
test and install this module. Don't forget to set the INCLUDE and LIB
365
variables in config.in.
367
Remember, you will need to have the LD_PRELOAD variable set anytime you
368
want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD
369
permanently set it will affect ALL commands you execute. This may be a
370
problem if you run any commands that access a database created by the
371
version of Berkeley DB that shipped with your Linux distribution.
378
If you are running Solaris 2.5, and you get this error when you run the
379
BerkeleyDB test harness:
381
libc internal error: _rmutex_unlock: rmutex not held.
383
you probably need to install a Sun patch. It has been reported that
384
Sun patch 103187-25 (or later revisions) fixes this problem.
386
To find out if you have the patch installed, the command "showrev -p"
387
will display the patches that are currently installed on your system.
392
If you are running Solaris 2.7 and all the tests in the test harness
393
generate a core dump, try applying Sun patch 106980-09 (or better).
395
To find out if you have the patch installed, the command "showrev -p"
396
will display the patches that are currently installed on your system.
402
Some people running HP-UX 10 have reported getting an error like this
403
when building this module with the native HP-UX compiler.
405
ld: (Warning) At least one PA 2.0 object file (BerkeleyDB.o) was detected.
406
The linked output may not run on a PA 1.x system.
407
ld: Invalid loader fixup for symbol "$000000A5".
409
If this is the case for you, Berkeley DB needs to be recompiled with
410
the +z or +Z option and the resulting library placed in a .sl file. The
411
following steps should do the trick:
413
1: Configure the Berkeley DB distribution with the +z or +Z C compiler
416
env "CFLAGS=+z" ../dist/configure ...
418
2: Edit the Berkeley DB Makefile and change:
420
"libdb= libdb.a" to "libdb= libdb.sl".
422
3: Build and install the Berkeley DB distribution as usual.
429
How to report a problem with BerkeleyDB.
431
To help me help you, I need of the following information:
433
1. The version of Perl and the operating system name and version you
434
are running. The complete output from running "perl -V" will tell
435
me all I need to know.
436
If your perl does not understand the "-V" option is too old.
437
BerkeleyDB needs Perl version 5.004_04 or better.
439
2. The version of BerkeleyDB you have. If you have successfully
440
installed BerkeleyDB, this one-liner will tell you:
442
perl -MBerkeleyDB -e 'print qq{BerkeleyDB ver $BerkeleyDB::VERSION\n}'
444
If you haven't installed BerkeleyDB then search BerkeleyDB.pm for a
449
3. The version of Berkeley DB you have installed. If you have
450
successfully installed BerkeleyDB, this one-liner will tell you:
452
perl -MBerkeleyDB -e 'print BerkeleyDB::DB_VERSION_STRING.qq{\n}'
454
If you haven't installed BerkeleyDB then search db.h for a line
457
#define DB_VERSION_STRING
459
4. If you are having problems building BerkeleyDB, send me a complete
460
log of what happened.
462
5. Now the difficult one. If you think you have found a bug in
463
BerkeleyDB and you want me to fix it, you will *greatly* enhance
464
the chances of me being able to track it down by sending me a small
465
self-contained Perl script that illustrates the problem you are
466
encountering. Include a summary of what you think the problem is
467
and a log of what happens when you run the script, in case I can't
468
reproduce your problem on my system. If possible, don't have the
469
script dependent on an existing 20Meg database. If the script you
470
send me can create the database itself then that is preferred.
472
I realise that in some cases this is easier said than done, so if
473
you can only reproduce the problem in your existing script, then
474
you can post me that if you want. Just don't expect me to find your
475
problem in a hurry, or at all. :-)
481
See the Changes file.
483
Paul Marquess <Paul.Marquess@btinternet.com>
added
removed
libdb/perl/BerkeleyDB/README
