BerkeleyDb-4.7 Installation and Usage HOWTO ########################################### This document explains how to set up your development environment in order to use the package BerkeleyDb-4.7 provided by the setup program BerkeleyDb-4.7Setup-.exe. 1 Download and install the package documentation, header and library files ========================================================================== - Download the Win32 package installer BerkeleyDb-4.6Setup-.exe from SysToMath (see http://www.SysToMath.com/etc/html/libraries.html). - Environment Variable LOCROOT This environment variable shall reside in the system environment (Settings, Control Panel, System, Enhanced, Environment, System Variables). As the Win32 executables and DLLs are installed in %LOCROOT%\bin\w32, it is recommended to add the value %LOCROOT%\bin\w32 to the system path. This has the advantage that all programs and DLLs located in %LOCROOT%\bin\w32 are found without stating an explicit directory path. It is further recommended that %LOCROOT% does not contain spaces and target an initially empty directory on a partition with at least 4 GB of free space. The directory %LOCROOT% shall be the installation path of all SysToMath packages installed on the system. - Install the package with the installation path %LOCROOT% by executing the Win32 package installer BerkeleyDb-4.6Setup-.exe. 2 Download and install the SysToMath package sources (optional) =============================================================== - Download the Win32 package installer MakePkgSetup-.exe from SysToMath (see http://www.SysToMath.com/etc/html/libraries.html). - Install the SysToMath package builder package MakePkg with the installation path %LOCROOT% by execuing MakePkgSetup-.exe - Download the SysToMath package source archive BerkeleyDb-4.7Src-.tgz from SysToMath (see http://www.SysToMath.com/etc/html/libraries.html). - Environment Variable DEVLROOT This environment variable shall reside in the system environment (Settings, Control Panel, System, Enhanced, Environment, System Variables). %DEVLROOT% shall be different from %LOCROOT% but may be a subdirectory of it. It is further recommended that %DEVLROOT% does not contain spaces and target an initially empty directory on a partition with at least 4 GB of free space. - Expand the package source archive into the directory %DEVLROOT% or into a subdirectory thereof. For the correct functioning of the command makepkg it is important that all SysToMath package source archives are installed somewhere in the tree rooted by %DEVLROOT%. - Read the file ReleaseHowto.txt of the package source archive to learn about the procedures necessary to maintain and build the package. 3 Supported Tool Families ========================= The libraries contained in the package are designed to support the tool families: - Microsoft Visual Studio Tool Family on Win32 - GNU Tool Family on Win32 - GNU Tool Family on Linux Remember that depending on your choice during installation not all tool families and library configurations described in the following might be available. 3.1 Microsoft Visual Studio Tool Family on Win32 ------------------------------------------------ The Microsoft Visual Studio tool family on Win32 consists of the tool sets: - Microsoft Visual Studio 6.0 (vc60) - Microsoft Visual Studio .NET 2003 (vc71) - Microsoft Visual Studio 2005 (vc80) - Microsoft Visual Studio 2008 (vc90) 3.1.1 Directory Paths ..................... In Tools, Options, Projects, VC++ Directories some entries are required: - Executable Files: $(LOCROOT)\bin\w32 - Include Files: $(LOCROOT)\include\berkeleydb-4_7 - Library Files: $(LOCROOT)\lib\w32 3.1.2 Include Paths ................... The header files constituting the API of the BerkeleyDB C/C++ libraries all reside in the directory %LOCROOT%\include\berkeleydb-4_7\berkeley Provided the above recommendments apply, for instance one writes in a program using the BerkeleyDB C++ API: #include 3.1.1 Automatic Linking with Microsoft Visual Studio .................................................... On Microsoft Visual Studio 6.0 (vc60), Microsoft Visual Studio .NET 2003 (vc71), Microsoft Visual Studio 2005 (vc80) and Microsoft Visual Studio 2008 (vc90) the necessary libraries are linked automatically when header files of one of the BerkeleyDB C/C++ libraries are included, unless this mechanism is suppressed by the definition of the preprocessor symbol STM_ALL_NO_LIB (for all libraries) or STM_BERKELEYDB_NO_LIB (for the BerkeleyDB C/C++ librariy) before that inclusion. The choice of the libraries depends on the toolset used (vc60, vc71, vc80 or vc90) and on the system runtime library selected for the executable to be built. The BerkeleyDB C/C++ library provides two dynamic library configurations (dll files) and four static ones (lib files). In the following list vcnn stands for vc60, vc71, vc80 or vc90: - ReleaseDllMt: Dynamic release library berkeleydb-vcnn-mt.dll together with its import library berkeleydb-vcnn-mt.lib chosen when linking against the multithreaded release DLL runtime (Compiler switch /MD) and defining the preprocessor variable STM_DYN_LINK before the library header file inclusion. - ReleaseMt: Static release library libberkeleydb-vcnn-mt.lib chosen when linking against the multithreaded release DLL runtime (Compiler switch /MD). - ReleaseMtStaticRt: Static release library libberkeleydb-vcnn-mt-s.lib chosen when linking against the multithreaded static release runtime (Compiler switch /MT). - DebugDllMt: Dynamic debug library berkeleydb-vcnn-mt-gd.dll together with its import library berkeleydb-vcnn-mt-gd.lib chosen when linking against the multithreaded debug DLL runtime (Compiler switch /MDd) and defining the preprocessor variable STM_DYN_LINK before the library header file inclusion. - DebugMt: Static debug library libberkeleydb-vcnn-mt-gd.lib chosen when linking against the multithreaded debug DLL runtime (Compiler switch /MDd). - DebugMtStaticRt: Static debug library libberkeleydb-vcnn-mt-sgd.lib chosen when linking against the multithreaded static debug runtime (Compiler switch /MTd). 3.2 GNU Tool Family on Win32 ---------------------------- The GNU tool family on Win 32 consists of the tool sets: - GNU gcc for POSIX environment (cygwin) - GNU gcc for Microsoft environment (cygming) The tool set cygwin (chosen by gcc or g++ without option -mno-cygwin) produces libraries depending on the GPL licensed dynamic library cygwin1.dll and therefore is restricted to free open source software projects, whereas the tool set cygming (chosen by gcc or g++ with option -mno-cygwin) produces libraries only depending on the Microsoft runtime libraries and thus also allows commercial closed source software projects. In the following it is assumed that the environment variable CYGWINROOT designates the Cygwin root directory and Cygwin (www.cygwin.com) with at least the complete packages Base, Devel, Net and Text is installed in %CYGWINROOT% with default text file type set to UNIX/binary, that the values %CYGWINROOT%\usr\local\bin and %CYGWINROOT%\bin are contained in the system executable path before %SYSTEMROOT%\system32 in the above order and that you use gcc and g++ from within a bash console with the following additional environment: export locroot=$(cygpath -u "${LOCROOT//\\//}") 3.2.1 Include Paths ................... To find the include directories, use for gcc and g++ the following option: -I"${locroot}/include/berkeleydb-4_7" 3.2.2 Library Paths ................... To find the libraries, use for gcc and g++ the following option: -L"${locroot}/lib/w32" 3.2.3 Linking with the GNU Tool Family ...................................... The libraries for the GNU tool family have to be linked explicitely. The choice of the libraries depends on the tool set used (cygwin or cygming) and on the system runtime library selected for the executable to be built. The Berkeley C/C++ library provides two dynamic library configurations (dll files) and two static ones (a files). In the following list cygxxx stands for cygwin or cygming: - ReleaseDllMt: Dynamic release library berkeleydb-cygxxx-mt.dll together with its import library libberkeleydb-cygxxx-mt.dll.a to be chosen for multithreaded not debug enabled dynamically linked executables (the preprocessor variables NDEBUG and STM_DYN_LINK should be defined). - ReleaseMt: Static release library libberkeleydb-cygxxx-mt.a to be chosen for multithreaded not debug enabled statically linked executables (the preprocessor variable NDEBUG should be defined). - DebugDllMt: Dynamic debug library berkeleydb-cygxxx-mt-d.dll together with its import library libberkeleydb-cygxxx-mt-d.dll.a to be chosen for multithreaded debug enabled dynamically linked executables (the preprocessor variables _DEBUG and STM_DYN_LINK should be defined). - DebugMt: Static debug library libberkeleydb-cygxxx-mt-d.a to be chosen for multithreaded debug enabled statically linked executables (the preprocessor variable _DEBUG should be defined). 3.3 GNU Tool Family on Linux ---------------------------- The GNU tool family on Linux consists of the tool sets: - GNU gcc for glibc version >= 2.3 (libc23) - GNU gcc for glibc version >= 2.4 (libc24) In the following it is assumed that the directory tree rooted by the Win32 environment variable LOCROOT has been NFS exported to the Linux system by means of the Cygwin NFS server. Doing so translates the lnk files on the Win32 side to symbolic links on the Linux side. Further the Linux environment variable locroot is assumed to point to the root of that tree on the Linux system. 3.3.1 Include Paths ................... To find the include directories, use for gcc and g++ the following option: -I"${locroot}/include/berkeleydb-4_7" 3.3.2 Library Paths ................... To find the libraries, use for gcc and g++ the following option: -L"${locroot}/lib/l32" 3.3.3 Linking with the GNU Tool Family ...................................... The libraries for the GNU tool family have to be linked explicitely. The choice of the libraries depends on the tool set used (libc23 or libc24) and on the system runtime library selected for the executable to be built. The Berkeley C/C++ library provides two shared library configurations (so files) and two static ones (a files). In the following list libc2x stands for libc23 or libc24: - ReleaseDllMt: Shared release library libberkeleydb-libc2x-mt.so to be chosen for multithreaded not debug enabled dynamically linked executables (the preprocessor variables NDEBUG and STM_DYN_LINK should be defined). - ReleaseMt: Static release library libberkeleydb-libc2x-mt.a to be chosen for multithreaded not debug enabled statically linked executables (the preprocessor variable NDEBUG should be defined). - DebugDllMt: Shared debug library libberkeleydb-libc2x-mt-d.so to be chosen for multithreaded debug enabled dynamically linked executables (the preprocessor variables _DEBUG and STM_DYN_LINK should be defined). - DebugMt: Static debug library libberkeleydb-libc2x-mt-d.a to be chosen for multithreaded debug enabled statically linked executables (the preprocessor variable _DEBUG should be defined).