Berkeley DB Reference Guide: Building Berkeley DB XML for UNIX/POSIX systems

Dynamic shared libraries

Warning: the following information is intended to be generic and is likely to be correct for most UNIX systems. Unfortunately, dynamic shared libraries are not standard between UNIX systems, so there may be information here that is not correct for your system. If you have problems, consult your compiler and linker manual pages, or your system administrator.

The Berkeley DB XML dynamic shared libraries are created with the name libdbxml-major.minor.so, where major is the major version number and minor is the minor version number. Other shared libraries are created if Java and Tcl support are enabled: specifically, libdbxml_java-major.minor.so and libdbxml_tcl-major.minor.so.

On most UNIX systems, when any shared library is created, the linker stamps it with a "SONAME". In the case of Berkeley DB XML, the SONAME is libdbxml-major.minor.so. It is important to realize that applications linked against a shared library remember the SONAMEs of the libraries they use and not the underlying names in the filesystem.

When the Berkeley DB XML shared library is installed, links are created in the install lib directory so that libdbxml-major.minor.so, libdbxml-major.so, and libdbxml.so all refer to the same library. This library will have an SONAME of libdbxml-major.minor.so.

Any previous versions of the Berkeley DB XML libraries that are present in the install directory (such as libdbxml-2.7.so or libdbxml-2.so) are left unchanged. (Removing or moving old shared libraries is one drastic way to identify applications that have been linked against those vintage releases.)

Once you have installed the Berkeley DB XML libraries, unless they are installed in a directory where the linker normally looks for shared libraries, you will need to specify the installation directory as part of compiling and linking against Berkeley DB XML. Consult your system manuals or system administrator for ways to specify a shared library directory when compiling and linking applications with the Berkeley DB XML libraries. Many systems support environment variables (for example, LD_LIBRARY_PATH or LD_RUN_PATH), or system configuration files (for example, /etc/ld.so.conf) for this purpose.

Warning: some UNIX installations may have an already existing /usr/lib/libdbxml.so, and this library may be an incompatible version of Berkeley DB XML.

We recommend that applications link against libdbxml.so (for example, using -ldbxml). Even though the linker uses the file named libdbxml.so, the executable file for the application remembers the library's SONAME (libdbxml-major.minor.so). This has the effect of marking the applications with the versions they need at link time. Because applications locate their needed SONAMEs when they are executed, all previously linked applications will continue to run using the library they were linked with, even when a new version of Berkeley DB XML is installed and the file libdbxml.so is replaced with a new version.

Applications that know they are using features specific to a particular Berkeley DB XML release can be linked to that release. For example, an application wanting to link to Berkeley DB XML major release "3" can link using -ldbxml-3, and applications that know about a particular minor release number can specify both major and minor release numbers; for example, -ldbxml-3.5.

If you want to link with Berkeley DB XML before performing library installation, the "make" command will have created a shared library object in the .libs subdirectory of the build directory, such as build_unix/.libs/libdbxml-major.minor.so. If you want to link a file against this library, with, for example, a major number of "3" and a minor number of "5", you should be able to do something like the following:

cc -L BUILD_DIRECTORY/.libs -o testprog testprog.o -ldbxml-3.5
env LD_LIBRARY_PATH="BUILD_DIRECTORY/.libs:$LD_LIBRARY_PATH" ./testprog

where BUILD_DIRECTORY is the full directory path to the directory where you built Berkeley DB XML.

The libtool program (which is configured in the build directory) can be used to set the shared library path and run a program. For example, the following runs the gdb debugger on the db_dump utility after setting the appropriate paths:

libtool gdb db_dump

Libtool may not know what to do with arbitrary commands (it is hardwired to recognize "gdb" and some other commands). If it complains the mode argument will usually resolve the problem:

libtool --mode=execute my_debugger db_dump

On most systems, using libtool in this way is exactly equivalent to setting the LD_LIBRARY_PATH environment variable and then executing the program. On other systems, using libtool has the virtue of knowing about any other details on systems that don't behave in this typical way.

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.