Building HyperSQL Jars

How to build customized or specialized jar files

Fred Toussi

The HSQL Development Group

$Revision: 3556 $

$Date: 2010-03-26 19:09:40 -0400 (Fri, 26 Mar 2010) $

Table of Contents

Building with Ant
Obtaining Ant
Building Hsqldb with Ant
Building for Older JDKs
Building with IDE's
Hsqldb CodeSwitcher
Building documentation


From 2.0, the supplied hsqldb.jar file is built with Java 1.6. If you want to run with a 1.5 or older JVM, or if you want to use an alternative jar (hsqldb-min.jar, etc.) you must build the desired jar with a Java JDK and Ant version 1.7.

Building with Apache Ant

You should use version 1.7.x of Ant (Another Neat Tool) to do builds with HyperSQL.

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 build the hsqldb.jar file


Lists all targets which build jar files, with an explanation of the purposes of the different jars.


to clean up the /classes directory that is created


to remove the old jar and doc files 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 (can connect only to a HyperSQL Server).


to build a small jar that supports in-process catalogs, but neither running nor connecting to HyperSQL Servers.


to build sqltool.jar, which contains only the SqlTool classes.


Many more targets are available. Run ant -p and ant explainjars.

HSQLDB can be built in any combination of two JRE (Java Runtime Environment) versions and many jar file sizes.

A jar built with an older JRE is compatible for use with a newer JRE (you can compile with Java 1.5 and run with 1.6). But the newer JDBC capabilities of the JRE will be not be available.

The client jar (hsqljdbc.jar) contains only the HSQLDB JDBC Driver client. The smallest engine jar (hsqldbmin.jar) contains the engine and the HSQLDB JDBC Driver client. The default size (hsqldb.jar) also contains server mode support and the utilities. The largest size (hsqldbtest.jar)includes some test classes as well. 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.

If you want your code built for high performance, as opposed to debugging (in the same way that we make our production distributions), make a file named in your build directory with the contents

build.debug: false
The resulting Java binaries will be faster and smaller, at the cost of exception stack traces not identifying source code locations (which can be extremely useful for debugging).

After installing Ant on your system use the following command from the /build directory. Just run ant explainjars for a concise list of all available jar files.

ant explainjars

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

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

ant hsqldb

The Ant method always builds a jar with the JDK that is used by Ant and specified in its JAVA_HOME environment variable.

Building for Older JDKs

HyperSQL version 2.0 cannot be directly compiled or used with JDK 1.4. It may be possible to use the RetroTranslator tool to achieve this. The suggested procedure is as follows: First use Ant with JDK 1.5 and build the jar. Then translate the jar using RetroTranslator with backport (which bundles replacement classes for concurrency control). This translation should cover the concurrency features that are specific to version 1.5 and later.

ant switchtojdk14
ant hsqldb
-- translate the jar

Building with IDE's

All HyperSQL source files are supplied ready to compile. There is no complex pre-compile stage. It is therefore possible to compile the sources with an IDE, without using ant. Only if compilation with Java 1.5 is required, you should first run the Ant code switcher task before compiling and remove from the source directories a few source files that are specific to Java 6 (these are listed in the build.xml file).

Hsqldb CodeSwitcher

CodeSwitcher is a tool to manage different version of Java source code. It allows to compile HyperSQL 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 the Ant build. You do not have to use it separately to compile HyperSQL.

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 B.2. Example source code before CodeSwitcher is run


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


    /*,"hsqldb database");




The next step is to run CodeSwitcher.

Example B.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 B.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 build.xml file in the /build directory.

Building documentation

The JavaDoc can be built simply by invoking the javadoc target.

The two Guides are in DocBook XML source format. To rebuild, run the Ant target gen-docs. Instructions will be displayed. See the file doc-src/readme-docauthors.txt for tips.

$Revision: 3601 $