Berkeley DB XML Reference Guide: Building Berkeley DB XML for Windows systems

Building Berkeley DB XML for Windows

If you want to build on Windows using Cygwin see the instructions for building on Unix systems.

The Berkeley DB XML distribution comprises several libraries: a base C++ library, three third-party libraries, and optional libraries for additional language interfaces such as Java, Perl, Python, PHP, and Tcl. Instructions for building the base libraries as well as Java, Tcl and PHP interfaces are included here. Instructions for the other language bindings appear in their respective directories: dbxml-2.5.16/dbxml/src/{perl,python}. All bindings require the C++ library and third-party libraries.

Berkeley DB XML makes use of several open source libraries. Each of these packages is freely available and distributed under an Open Source license. The Berkeley DB XML distribution bundles compatible versions of all third-party libraries. No additional downloads are required. Use of other versions may not work. If in doubt ask on the Berkeley DB XML forum. Berkeley DB XML requires the following third-party libraries:

Berkeley DB is a general purpose database toolkit. This release of Berkeley DB XML includes the Berkeley DB 4.8.x release, and requires the Berkeley DB 4.3.28 release or later.

Xerces is the Apache implementation of XML parsing technology and DOM. The build requires a source release of Xerces, not just a binary release. This release of Berkeley DB XML bundles Xerces-C 3.0.1 and requires the Xerces 3.0.0 release or newer.

XQilla is an open source implementation of XQuery 1.0 and XPath 2.0. Berkeley DB XML bundles the 2.2 release of XQilla. Later versions of XQilla may work, but are not implicitly supported.

ZLIB is an open source compression library. This release of Berkeley DB XML bundles the binary release of ZLIB 1.2.3. It is not required if wholedoc container compression is not desired.

1. Choose File -> Open -> Project/Solution. Look in the dbxml-2.5.16/dbxml/build_windows directory for solution files, select BDBXML_all_vs8.sln, and press Open.

2. Visual Studio will prompt you about converting the project files to a newer format. Allow this to proceeed.

3. Choose the project configuration from the drop-down menu on the Visual Studio tool bar.

4. To build, select Build Solution from the Build drop-down menu. All library files (*.lib) are placed in dbxml-2.5.16/lib, DLLs and executables are installed in dbxml-2.5.16/bin or dbxml-2.5.16/bin/debug depending on the configuration you choose, .jar files are placed in dbxml-2.5.16/jar, and header (include) files for application development are copied to dbxml-2.5.16/include.

5. By default, BDBXML_all_vs8.sln builds all third-party libraries, Berkeley DB XML, and Berkeley DB XML C++ examples. The examples are installed in bin{/debug} along with other executables.

1. Choose File -> Open -> Project/Solution. Look in the dbxml-2.5.16/dbxml/build_windows directory for solution files, select BDBXML_all_vs8.sln, and press Open.

2. Choose the project configuration from the drop-down menu on the Visual Studio tool bar.

3. To build, select Build Solution from the Build drop-down menu. All library files (*.lib) are placed in dbxml-2.5.16/lib, DLLs and executables are installed in dbxml-2.5.16/bin or dbxml-2.5.16/bin/debug depending on the configuration you choose, .jar files are placed in dbxml-2.5.16/jar, and header (include) files for application development are copied to dbxml-2.5.16/include.

4. By default, BDBXML_all_vs8.sln builds all third-party libraries, Berkeley DB XML, and Berkeley DB XML C++ examples. The examples are installed in bin{/debug} along with other executables.

1. Download and install Microsoft Platform SDK.

2. Choose File -> Open -> Project/Solution. Look in the dbxml-2.5.16/dbxml/build_windows directory for solution files, select BDBXML_all_vs8.sln, and press Open.

3. Right click the db project and select properties. On the properties page select All Configurations from the Configuration menu in the top left corner. Enter ws2_32.lib advapi32.lib for the Additional Dependencies option of Linker -> Input. Select the OK button to save the changes.

4. Select Options... from the Tools pull-down menu. Choose Projects and Solutions, then VC++ Directories. Select Include files from the Show directories for menu. Add the complete path to Microsoft Platform SDK\Include\mfc and Microsoft Platform SDK\Include to the list of directories. Next select Library files from the Show directories for: menu. Add the complete path too Microsoft Platform SDK\Lib to the list of directories.

5. Choose the project configuration from the drop-down menu on the Visual Studio tool bar.

6. To build, select Build Solution from the Build drop-down menu. All library files (*.lib) are placed in dbxml-2.5.16/lib, DLLs and executables are installed in dbxml-2.5.16/bin or dbxml-2.5.16/bin/debug depending on the configuration you choose, .jar files are placed in dbxml-2.5.16/jar, and header (include) files for application development are copied to dbxml-2.5.16/include.

7. By default, BDBXML_all_vs8.sln builds all third-party libraries, Berkeley DB XML, and Berkeley DB XML C++ examples. The examples are installed in bin{/debug} along with other executables.

1. Choose File -> Open Solution. Look in the dbxml-2.5.16/dbxml/build_windows directory for solution files, select BDBXML_all.sln, and press Open.

2. Choose the project configuration from the drop-down menu on the .NET tool bar.

3. To build, select Build Solution from the Build drop-down menu. All library files (*.lib) are placed in dbxml-2.5.16/lib, DLLs and executables are installed in dbxml-2.5.16/bin or dbxml-2.5.16/bin/debug depending on the configuration you choose, .jar files are placed in dbxml-2.5.16/jar, and header (include) files for application development are copied to dbxml-2.5.16/include.

4. By default, BDBXML_all.sln builds all third-party libraries, Berkeley DB XML, and Berkeley DB XML C++ examples. The examples are installed in bin{/debug} along with other executables.

1. Choose File -> Open Workspace. Look in the dbxml-2.5.16/dbxml/build_windows directory for Workspaces, select BDBXML_all.dsw, and press Open.

   It is possible that while opening BDBXML_all.dsw there will be an error regarding the XercesLib project. If that happens allow VC6 to "wrap" the project and save it as a new name (use the default). The new name will appear in the Workspace's project list. In this case build that project by itself before building anything else. Once that is done continue with the directions below.

2. Choose the desired project configuration by going to Build -> Set Active Configuration and select the appropriate option to the all project. Then click OK.

3. To build, select Build -> Build all.exe. All library files (*.lib) are placed in dbxml-2.5.16/lib, DLLs and executables are installed in dbxml-2.5.16/bin or dbxml-2.5.16/bin/debug depending on the configuration you choose, .jar files are placed in dbxml-2.5.16/jar, and header (include) files for application development are copied to dbxml-2.5.16/include.

4. By default, BDBXML_all.dsw builds all third-party libraries, Berkeley DB XML, and Berkeley DB XML C++ examples. The examples are installed in bin{/debug} along with other executables.

When building your application, you should normally use compile options "Debug Multithreaded DLL" and link against lib/libdbxml25d.lib. You can also build using a release version of the libraries and tools, which will be placed in lib/libdbxml25.lib. A safe way to construct a project file for your application is to adapt one of the Berkeley DB XML example projects.

After a successful build, the Berkeley DB XML example executable files are in bin{/debug}. See dbxml/examples/cxx/gettingStarted/Readme.txt for instructions on building the C++ example containers and running examples.

The Berkeley DB XML Java API is not built automatically. The following instructions assume that you have installed the Sun Java Development Kit in d:/java. If you installed elsewhere or have different Java software you will need to adjust the pathnames accordingly.

1. Set your include directories. Choose Tools -> Options -> Projects -> VC++ Directories. Under the "Show directories for" pull-down, select "Include files". Add the full pathnames for the java/include and java/include/win32 directories. Then click OK. These are the directories needed when including jni.h.

2. Set the executable files directories. Choose Tools -> Options -> Projects -> VC++ Directories. Under the "Show directories for" pull-down, select "Executable files". Add the full pathname for the java/bin directory, then click OK. This is the directory needed to find javac.

3. Set the build type to Release or Debug (or other appropriate configuration) in the drop-down on the .NET tool bar.

4. Right-click on db_java and select Build. This builds the Java support library for Berkeley DB, which is required for Berkeley DB XML, and compiles all the java files, placing the resulting db.jar and dbexamples.jar files in bin or bin/debug.

5. Right-click on dbxml_java and select Build. This builds the Java support library for Berkeley DB XML and compiles all the java files, placing the resulting dbxml.jar and dbxmlexamples.jar files in jar.

Building Java with Visual C++ 6.0

1. Set the include directories. Choose Tools -> Options -> Directories. Under the "Show directories for" pull-down, select "Include files". Add the full pathnames for the java/include and java/include/win32 directories. These are the directories needed when including jni.h.

2. Set the executable files directories. Choose Tools -> Options -> Directories. Under the "Show directories for" pull-down, select "Executable files". Add the full pathname for the java/bin directory. This is the directory needed to find javac.

3. Go to Build -> Set Active Configuration and select either the Debug or Release version of the db_java project. Then press OK.

4. Select Build -> Build libdb_java48.dll. This builds the Java support library for Berkeley DB, which is required for Berkeley DB XML, and compiles all the java files, placing the resulting db.jar and dbexamples.jar files in jar.

5. Go to Build -> Set Active Configuration and select either the Debug or Release version of the dbxml_java project. Then press OK.

6. Select Build -> Build libdbxml_java25.dll. This builds the Java support library for Berkeley DB XML, and compiles all the java files, placing the resulting dbxml.jar and dbxmlexamples.jar files in jar.

To run Java code, set your environment variable CLASSPATH to include the full pathname of these jar files, and your environment variable PATH to include the bin (Release build) or bin/debug (Debug build) subdirectory. The jar files for debug and release builds are identical, and will attempt to load the approriate native libraries, first attempting to load Release, then Debug libraries. On Windows, remember that files or directories in the CLASSPATH and PATH variables must be separated by semicolons (unlike UNIX)

After a successful build, the Berkeley DB XML examples are in jar/dbxmlexamples.jar. See dbxml/examples/java/gettingStarted/Readme.txt for instructions on building the Java example containers and running Java examples.

Tcl support is not built automatically. You must have Tcl installed on the machine. You should use at least version 8.4. These notes assume that Tcl is installed as d:/tcl but you can change that if you want.

The Tcl library must be built as the same build type as the Berkeley DB and Berkeley DB XML libraries (both Release or both Debug). We found that the binary release of Tcl can be used with the Release configurations of Berkeley DB and Berkeley DB XML, but you will need to build Tcl from sources for the Debug configuration. Before building Tcl, you will need to modify its makefile to make sure that you are building a debug version, including thread support. This is because the set of DLLs linked into the Tcl executable must match the corresponding set of DLLs used by Berkeley DB and Berkeley DB XML.

Building Tcl with Visual C++ .NET or higher

1. Set the include directories. Choose Tools -> Options -> Projects -> VC++ Directories. Under the "Show directories for" pull-down, select "Include files". Add the full pathname for tcl/include, then click OK. This is the directory that contains tcl.h.

2. Set the library files directory. Choose Tools -> Options -> Projects -> VC++ Directories. Under the "Show directories for" pull-down menu, select "Library files". Add the full pathname for the tcl/lib directory, then click OK. This is the directory needed to find tcl84.lib (or whatever the library is named in your distribution).

3. Set the build type to Release or Debug (or other appropriate configuration) in the drop-down on the .NET tool bar.

4. Right-click on db_tcl and select Build. This builds the Tcl support library for Berkeley DB, which is required for Berkeley DB XML, placing the result into bin/debug/libdb_tcl48d.dll or bin/libdb_tcl48.dll.

5. Right-click on dbxml_tcl and select Build. This builds the Tcl support library for Berkeley DB XML, placing the result into bin/debug/libdbxml_tcl25d.dll or bin/libdbxml_tcl25.dll.

If you use a version different from Tcl 8.4.x you will need to change the name of the Tcl library used in the build (for example, tcl84.lib) to the appropriate name. To do this, right click on db_tcl, go to Properties -> Linker -> Input -> Additional dependencies and change tcl84.lib to match the Tcl version you are using.

Building Tcl with Visual C++ 6.0

1. Set the include directories. Choose Tools -> Options -> Directories. Under the "Show directories for" pull-down menu, select "Include files". Add the full pathname for tcl/include, then click OK. This is the directory that contains tcl.h.

2. Set the library files directory. Choose Tools -> Options -> Directories. Under the "Show directories for" pull-down menu, select "Library files". Add the full pathname for the tcl/lib directory, then click OK. This is the directory needed to find tcl84.lib (or whatever the library is named in your distribution).

3. Go to Build -> Set Active Configuration and select either the Debug or Release version of the db_tcl project. Then press OK.

4. Select Build -> Build libdb_tcl48 }.dll. This builds the Tcl support library for Berkeley DB

5. Go to Build -> Set Active Configuration and select either the Debug or Release version of the dbxml_tcl project. Then press OK.

6. Select Build -> Build libdbxml_tcl25.dll. This builds the Tcl support library for Berkeley DB XML, placing the result into bin/debug/libdbxml_tcl25d.dll or bin/libdbxml_tcl25.dll.

If you use a version different from Tcl 8.4.x you will need to change the name of the Tcl library used in the build (for example, tcl84.lib) to the appropriate name. To do this, choose Project -> Settings -> db_tcl and change the Tcl library listed in the Object/Library modules tcl84.lib to match the Tcl version you are using.

Disabling default compression has the benefit of speeding up access to data in whole document containers at the cost of increasing container size. Disabling default compression also removes the dependency on the ZLIB library. Compression can be disabled by deleting the preprocessor definition _DBXML_COMPRESSSION and the linker dependency zdll.lib from the project dbxml, then rebuilding the project. Be warned that containers created with default compression cannot be opened if default compression has been disabled.

The Berkeley DB XML source distribution includes compatible versions of necessary third-party libraries. The BDBXML_all* solution builds them. This section is for advanced building, where libraries are not located in the directories as expected by the distribution. Berkeley DB XML can be built with third-party libraries that are not located in the Berkeley DB XML default location. In this case, use the BDBXML_all* solution/workspace. Opening may generate warnings that project files cannot be found. In this case, those warnings can be ignored.

In Visual C++ open the Tools/Options tabbed dialog for adding directories. Add the include and library paths for the third-party libraries located elsewhere. To do this, select Options... from the Tools pull-down menu. In Visual C++ 6.0, a tabbed dialog should appear. Choose the Directories tab in the dialog, and for the Platform, select Win32. In Visual Studio .NET, a different window appears. Choose Projects, then VC++ Directories.

In either case, use Include files under Show directories for to add include directories, and Library files for library paths.

For Berkeley DB add the include path db-<version>, db-<version>/build_windows. Also add the library paths db-<version>/build_windows/Debug and db-<version>/build_windows/Release.

For the source release of Xerces add the include path xerces-c-src/src. Then add the appropriate build directory for your compiler, for example, xerces-c-src/build/win32/vc6/debug and xerces-c-src/build/win32/vc6/release. Use vc7.1 instead of vc6 for Visual Studio .NET.

While there may be compatible releases of XQilla libraries available it is necessary to use those included in the Berkeley DB XML distribution in order to be supported.

The dbxml_java project includes a Custom Build Step that includes the path to the Berkeley DB .jar file three times. These must be changed to db-<version>/build_windows/debug/db.jar for the Debug configuration, and to db-<version>/build_windows/release/db.jar for the Release configuration.

Copyright (c) 1996-2009 Oracle. All rights reserved.