Table of Contents
hsqldb.jar file supplied in the lib
directory of the zip release package is tested and built with Java 11. An
separate jar for Java 8 is also supplied in the same directory. The code
is also tested extensively with Java 6-8 as well as the latest Java
versions. If you want to run with a Java 6 JVM, or use an alternative jar
hsqldb-min.jar, etc.), you must build the desired
jar with a JDK or download from hsqldb.org. You can also find official
jars built with Java 8 and Java 11 in major maven repositories as well as
downloads from hsqldb.org.
The Gradle task / Ant target
reports the versions of Java and Ant actually used.
If you want to change Ant or Gradle build settings, edit the text
build.properties in the HyperSQL
build directory (creating it if it doesn't exist
yet), and enter your properties using Java properties file syntax. (You
can also use
local-docbook.properties in the same way
for DocBook-specific properties).
Unlike most software build systems, you do not need to have the
Gradle system installed on your computer to use it. You don't need to
understand the details to use it, but this is the purpose of the
gradlew wrapper scripts that you
can see in HyperSQL's
build directory. If you want or
need to learn more about Gradle, you can start on the Gradle web site.
Gradle can find the Java to use by finding out where
Depending on your operating system, version, and how you
installed your JDK, Gradle may not be able to find the JDK. Gradle will
inform you if this happens. The easiest way to fix this problem is to
set environmental variable
You can invoke Gradle builds from the command-line.
Get a command-line shell. Windows users can use either
users will know how to get a shell.
In the shell, cd to the
under the root directory where you extracted or installed HyperSQL to.
(Operating system search or find functions can be used if you can't
find it quickly by poking around on the command line or with Windows
Windows users can ignore this step. UNIX shell users should
ensure that the current directory (
.) is in their
search path, or prefix their
gradlew command in the
next step with
./ (e.g., like
In the shell, run
gradlew for a
If you ran just
gradlew, then you will be
presented with simple instructions for how to do everything that you
want to do. Basically, you will run the same
gradlew command repeatedly, with different switches
and arguments for each build target.
Gradle's -v switch reports version details more directly
For example, the command below builds the
The Gradle invocations actually run Ant build targets. Some of the targets are listed in the next section.
You should use version 1.9 or 1.10 of Ant (Another Neat Tool) to do Ant builds with HyperSQL.
Ant is a part of the Apache Project.
Once you have unpacked the zip package for hsqldb, under the
/hsqldb folder, in
there is a
build.xml file that builds the
hsqldb.jar with Ant (Ant must be already
installed). To use it, change to
This displays the available Ant targets, which you can supply as command line arguments to ant. These include
|to build the
|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 during a build.|
|to remove the old jar and doc files as well as clean.|
|to build javadoc for all public classes accessible to user applications.|
|to build the
|to build a smaller jar for HSQLDB that does not contain utilities|
|to build a small jar that supports in-process catalogs, but not running HyperSQL Servers.|
|to build sqltool.jar, which contains only the SqlTool classes.|
|Many more targets are available. Run
HSQLDB can be built in any combination of 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 6 and run with 8). But the newer JDBC capabilities of HyperSQL and the JRE will be not be available.
The smallest engine 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 http://www.junit.org and put it in the
/lib directory, alongside
servlet.jar, which is included in the .zip
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
build.properties in your build
directory with the contents
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
/build directory. Just run
explainjars for a concise list of all available jar
The command displays a list of different options for building different sizes of the HSQLDB Jar. The default is built using:
The Ant method always builds a jar with the JDK that is used by Ant and specified in its JAVA_HOME environment variable.
The jars can be compiled with JDK 6 or later. Build has been tested under JDK versions 6, 8, 9, 10, 11, etc. The same Ant version can be used with all the tested JDKs.
The Ant build.xml can be used with most IDEs to build the Jar targets. All HyperSQL source files are supplied ready to compile. It is therefore possible to compile the sources without using Ant direcly. If compilation with Java 6 is required, you should run the Ant switchtojdk6 target before compiling to modify the files that have code blocks specific to Java 8 or above (these are listed in the jdkcodeswitch.list file).
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 invoke 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 C.2. Example source code before CodeSwitcher is run
... //#ifdef JAVA8 properties.store(out,"hsqldb database"); //#else /* properties.save(out,"hsqldb database"); */ //#endif ...
The next step is to run CodeSwitcher.
The '.' means the program works on the current directory (all
subdirectories are processed recursively).
the code labelled with JAVA8 must be switched off.
Example C.4. Source code after CodeSwitcher processing
... //#ifdef JAVA8 /* pProperties.store(out,"hsqldb database"); */ //#else pProperties.save(out,"hsqldb database"); //#endif ...
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
The JavaDoc can be built simply by invoking the javadoc task/target with Gradle or Ant.
The two Guides (the one you are reading now plus the Utilities user
guide) are in DocBook XML source format. To rebuild to PDF or one of the
HTML output formats from the XML source, run the Gradle target
gen-docs (or the Ant target
gen-docs). Instructions will be displayed. In
gen-docstask/target will tell you of a Gradle task that you can use to download and install them automatically. This Gradle task,
installDbImages, will tell you how to edit a properties text file to tell it what directory to install the files into. (Command-line, as opposed to GUI, builders, can use the Gradle
-Pswitch to set the property, instead of editing, if they prefer).
build.xmlin the HyperSQL
builddirectory about where to obtain these things and how to hook them in. The same Gradle task
installDbImagesexplained above can download and install the entire stylesheet bundle (this option is offered the first time that you run the
If running Gradle, you probably want to turn logging up to level info for generation and validation tasks, because the default warn/lifecycle level doesn't give much feedback.
validate-docs is also very
useful to DocBook builders.
The documentation license does not allow you to post
modifications to our guides, but you can modify them for internal use by
your organization, and you can use our DocBook system to write new DocBook
documents related or unrelated to HyperSQL. To create new DocBook
documents, create a subdirectory off of
each new document, with the main DocBook source file within having same
name as the directory plus
.xml. See the peer directory
guide as an
example. If you use the high-level tasks/target
validate-docs, then copy
and paste to add new stanzas to these targets in file
Editors of DocBook documents (see previous paragraph for motive)
may find it useful to have a standalone XML validator so you can do your
primary editing without involvement of the build system. Use the Gradle
standaloneValidation for this. It will tell you
how to set a build property to tell it where to install the validator, and
will give instructions on how to use it.
There are several properties that can be used to dramatically reduce
run times for partial doc builds. Read about these properties in comment
at the top of the file
build-docbook.xml in the
See the file
for details about our DocBook build system (though as I write this it is
somewhat out of date).
$Revision: 6366 $