Appendix A. Building Hsqldb version 1.7.2

Fred Toussi

HSQLDB Development Group

$Date: 2004/06/06 08:45:56 $

Table of Contents

Building with Ant
Obtaining Ant
Building Hsqldb with Ant
Building with DOS Batch Files
Hsqldb CodeSwitcher


From 1.7.2, the supplied hsqldb.jar file is built with Java 1.4.2. If you want to run the engine under JDK1.3 or earlier, you should rebuild the jar with Ant.

Building with Ant, from the Apache Jakarta Project

Ant (Another Neat Tool) is used for building hsqldb. The version currently used to test the build script is 1.6.1 but versions since 1.5.1 should also be compatible.

Obtaining Ant

Ant is a part of the Jakarta/Apache Project.

Building Hsqldb with Ant

Once you have unpacked the zip package for hsqldb, under the /hsqldb folder, in /build there is a build.xml file that builds the hsqldb.jar with Ant (Ant must be already installed). To use it, change to /build then type:

 ant -projecthelp

This displays the available ant targets, which you can supply as command line arguments to ant. These include


to make the hsqldb.jar


to clean up the /classes directory that is created


to remove the old jar as well


to build javadoc


to build a smaller jar for hsqldb that does not contain utilities


to build an extremely small jar containing only the client-side JDBC driver (does not support direct connection to HSQLDB URLs of the form jdbc:hsldb:mem:*, jdbc:hsqldb:file:*, nor jdbc:hsqldb:res:*).


to build a very small jar with no support for servers


to build a larger jar for hsqldb that contains tests


Many more targets are available

HSQLDB can be built in any combination of five different sizes and three JRE (Java Runtime Environment) versions. The smallest jar size(hsqljdbc.jar) contains only the HSQLDB JDBC Driver client. The next smallest jar size (hsqldbmin.jar) contains only the standalone database (no servers) and JDBC support and is suitable for embedded applications. The default size (hsqldb.jar) also contains server mode support and the utilities. The largest size (hsqldbtest.jar)includes some test classes as well. (You can also build hsqlsqltool.jar. If you use SqlTool, see the SqlTool chapter about that.)

In order to build and run the test classes, you need the JUnit jar in the /lib directory. This is available from

The preferred method of rebuilding the jar is with Ant. After installing Ant on your system use the following command from the /build directory:

ant explainjars

The command displays a list of different options for building different sizes of the HSQLDB Jar. The default is built using:

Example A.1. Buiding the standard Hsqldb jar file with Ant

    ant jar

The Ant method always builds a jar with the JDK that is used by Ant and specified in the JAVA_HOME environment variable. Building with JDK 1.4.x will result in a jar that is not backward compatible. From version 1.7.2, use of JDK 1.1.x is not recommended for building the JAR, even for running under JDK 1.1.x -- use JDK 1.3.1 for compatibility with 1.1.x.

Before building the hsqldbtest.jar package, you should download the junit jar from and put it in the /lib directory, alongside servlet.jar, which is included in the .zip package.

Building with DOS Batch Files

UNIX users must use Ant to build hsqldb.

For DOS/Windows users, a set of MSDOS batch files is provided as an alternative to using Ant. These produce only the default jar size. The path and classpath variables for the JDK should of course be set before running any of the batch files.

If you are compiling for JDK's other than 1.4.x, you should use the appropriate switchToJDK11.bat or switchToJDK12.bat to adapt the source files to the target JDK before running the appropriate buildJDK11.bat or buildJDK12.bat JDK and JRE versions.

From version 1.7.2, Use of JDK 1.1.x is not recommended for building the JAR, even for running under JDK 1.1.x -- use JDK1.3 for running under 1.1.x. Javadoc can be built with Ant and batch files.

Hsqldb CodeSwitcher

CodeSwitcher is a tool to manage different version of Java source code. It allows to compile HSQLDB for different JDKs. It is something like a precompiler in C but it works directly on the source code and does not create intermediate output or extra files.

CodeSwitcher is used internally in HSQLDB build scripts. You do not have to use it separately to compile HSQLDB.

CodeSwitcher reads the source code of a file, removes comments where appropriate and comments out the blocks that are not used for a particular version of the file. This operation is done for all files of a defined directory, and all subdirectories.

Example A.2. Example source code before CodeSwitcher is run


    //#ifdef JAVA2,"hsqldb database");


    /*,"hsqldb database");




The next step is to run CodeSwitcher.

Example A.3. CodeSwitcher command line invocation

    java org.hsqldb.util.CodeSwitcher . -JAVA2

The '.' means the program works on the current directory (all subdirectories are processed recursively). -JAVA2 means the code labelled with JAVA2 must be switched off.

Example A.4. Source code after CodeSwitcher processing


    //#ifdef JAVA2

    /*,"hsqldb database");


    //#else,"hsqldb database");



For detailed information on the command line options run java org.hsqldb.util.CodeSwitcher. Usage examples can be found in the switchtojdk1*.bat files in the /build directory.