Berkeley DB Reference Guide: Building Berkeley DB for UNIX systems
Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++

### Berkeley DB Reference Guide: Building Berkeley DB for UNIX systems |

# Architecture independent notes

1. Berkeley DB was configured using --enable-tcl and fails to build.

   The Berkeley DB Tcl interface requires Tcl 8.1 or greater.

   Unfortunately, there is no single location in which to find the Tcl include file (<tcl.h>) or the Tcl library (libtcl.a) on different platforms. Berkeley DB configuration does not do anything special to locate the Tcl include file, although it does try a few different library combinations in an attempt to figure out how to load the Tcl library.

   If your Tcl include file is not in one of the standard places checked by your compiler, then you will have to add CPPFLAGS and/or LIBS and LDFLAGS to your environment and reconfigure. For example:

   >     prompt: env CPPFLAGS="-I/usr/local/lib" ../dist/configure ...

   See Changing compile or load options for more information.

   You may also need to add additional libraries in order to get the Tcl test suite to load. Linux systems often require linking "libtcl.a" to "libtcl#.#.a" or adding "-ldl" to the load line. Solaris systems often require adding "-lsocket" and sometimes "-lnsl -ldl" to the load line. These changes are most simply done by editing the Makefile in your build directory explicitly.

   Alternatively, you can download Tcl from the Scriptics Corporation web site and build your own copy locally.

2. I have several versions of Tcl installed. How do I configure Berkeley DB to use a particular version?

   To compile the Tcl interface with a particular version of Tcl, you may need to set the environment variables CPPFLAGS, LDFLAGS and LIBS appropriately for your system before configuring Berkeley DB. For example:

   >     prompt: CPPFLAGS="-I/usr/local/include" \
   >     LDFLAGS="-L/usr/local/lib" LIBS="-lm -ltcl81 -ldl" \
   >     ../dist/configure --enable-dynamic --enable-debug \
   >     --enable-diagnostic --enable-tcl --enable-test

   See Changing compile or load options for more information.

3. When compiling with gcc, I get unreferenced symbols, e.g.,:

   >     symbol __muldi3: referenced symbol not found
   >     symbol __cmpdi2: referenced symbol not found

   On systems where they're available (e.g., HP-UX, Solaris), Berkeley DB uses 64-bit integral types. As far as we can tell, some versions of gcc don't support these types. The simplest workaround is to reconfigure Berkeley DB using the --disable-bigfile configuration option, and then rebuild.

4. My C++ program traps during a failure in a DB call on my gcc-based system.

   We believe there are some severe bugs in the implementation of exceptions for some gcc compilers. Exceptions require some interaction between compiler, assembler, runtime libraries, and we're not sure exactly what is at fault, but one failing combination is gcc 2.7.2.3 running on SuSE Linux 6.0. The problem on this system can be seen with a rather simple test case of an exception thrown from a shared library and caught in the main program.

   A variation of this problem seems to occur on AIX, although we believe it does not necessarily involve shared libraries on that platform.

   If you see a trap that occurs when an exception might be thrown by the DB runtime, we suggest that you use static libraries instead of dynamic (shared) libraries. See the documentation for configuration. If this doesn't work, and you have a choice of compilers, try using a more recent gcc or a non-gcc based compiler to build Berkeley DB.

   Finally, you can disable the use of exceptions in the C++ runtime for Berkeley DB by using the DB_CXX_NO_EXCEPTIONS flag with db_env_create or db_create. When this flag is on, all C++ methods fail by returning an error code rather than throwing an exception.

5. I get unexpected results and database corruption when running threaded programs.

   I get error messages that mutex (e.g., pthread_mutex_XXX or mutex_XXX) functions are undefined when linking applications with Berkeley DB.

   On some architectures, the Berkeley DB library uses the POSIX pthreads and UI threads interfaces for underlying mutex support, e.g., Solaris and HP-UX. You can specify compilers, compiler flags or link with the appropriate thread library when loading your application, to resolve the undefined references:

   >     cc ... -lpthread ...
   >     cc ... -lthread ...
   >     xlc_r ...
   >     cc ... -mt ...

   See the appropriate architecture-specific Reference Guide pages for more information.

   On systems where more than one type of mutex is available, it may be necessary for applications to use the same threads package from which Berkeley DB draws its mutexes, e.g., if Berkeley DB was built to use the POSIX pthreads mutex calls for mutex support, the application may need to be written to use the POSIX pthreads interfaces for its threading model. While this is only conjecture at this time and we know of no systems that actually have this requirement, it's not unlikely that some exist.

   In a few cases, Berkeley DB can be configured to use specific underlying mutex interfaces. You can use the --enable-posixmutexes and --enable-uimutexes configuration options to specify the POSIX and Unix International (UI) threads packages. This should not, however, be necessary in most cases.

   In some cases, it is vitally important to make sure that you load the correct library. For example, on Solaris systems, there are POSIX pthread interfaces in the C library, and so applications can link Berkeley DB using only C library and not see any undefined symbols. However, the C library POSIX pthread mutex support is insufficient for Berkeley DB and Berkeley DB cannot detect that fact. Similar errors can arise when applications (e.g., tclsh) use dlopen to dynamically load Berkeley DB as a library.

   If you are seeing problems in this area after you've confirmed that you're linking with the correct libraries, there are two other things you can try. First, if your platform supports inter-library dependencies, we recommend that you change the Berkeley DB Makefile to specify the appropriate threads library when creating the Berkeley DB dynamic library, as an inter-library dependency. Second, if your application is using dlopen to dynamically load Berkeley DB, specify the appropriate thread library on the link line when you load the application itself.

6. I get core dumps when running programs that fork children.

   Berkeley DB handles should not be shared across process forks, each forked child should acquire its own Berkeley DB handles.

7. Berkeley DB programs or the test suite fail unexpectedly.

   The Berkeley DB architecture does not support placing the shared memory regions on remote filesystems, e.g., the Network File System (NFS) or the Andrew File System (AFS). For this reason, the shared memory regions (normally located in the database home directory) must reside on a local filesystem. See Shared Memory Regions for more information.

   With respect to running the test suite, always check to make sure that TESTDIR is not on a remote mounted filesystem.

8. The db_dump185 utility fails to build.

   If the errors look something like:

   >     cc -o db_dump185 db_dump185.o
   >     ld:
   >     Unresolved:
   >     dbopen

   it means that the Berkeley DB 1.85 code was not found in the standard libraries. To build db_dump185 (the utility that converts Berkeley DB 1.85 and earlier databases to Berkeley DB version 2.X), you must have already built and installed the Berkeley DB version 1.85 code on the system. If the Berkeley DB 1.85 code is not part of the standard libraries used for loading, you will need to edit your Makefile, and change the lines:

   >     DBE=	db_dump185.o $(CLOBJS)
   >     db_dump185: $(DBE)
   >     	$(CC) -o $@ $(DBE)

   So that the library where the Berkeley DB 1.85 code is found is loaded, e.g.,

   >     DBE=	db_dump185.o $(CLOBJS)
   >     db_dump185: $(DBE)
   >     	$(CC) -o $@ $(DBE) -ldb185

Copyright Sleepycat Software