Building HSQLDB Jars

How to build customized or specialized jar files

Blaine Simpson

The HSQL Development Group

Fred Toussi

The HSQL Development Group

$Revision: 6366 $

2021-07-21

Table of Contents

Purpose
Building with Gradle
Building with Ant
Obtaining Ant
Building HSQLDB with Ant
Building with IDE Compilers
HyperSQL CodeSwitcher
Building Documentation

Purpose

The 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 explainjars reports the versions of Java and Ant actually used.

If you want to change Ant or Gradle build settings, edit the text file 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).

Building with Gradle

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.

[Note]Gradle honors JAVA_HOME

Gradle can find the Java to use by finding out where java is available from, but if environmental variable JAVA_HOME is set, that will override. Therefore, if you have multiple JREs or JDKs installed, or don't know if multiple are installed, you should set environmental variable JAVA_HOME to definitively eliminate all ambiguity.

[Important]Rare Gotcha

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 JAVA_HOME to the root directory where your Java SDK is installed. (See previous note for justification). So as not to get bogged down in the details here, if you don't know how to set an environmental variable, I ask you to utilize a search engine.

You can invoke Gradle builds from the command-line.

  1. Get a command-line shell. Windows users can use either Start/Run... or Start/Start Search, and enter "cmd". Non-windows users will know how to get a shell.

  2. In the shell, cd to the build directory 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 Explorer, etc.).

  3. 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 ./gradlew).

  4. In the shell, run gradlew for a build.

    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.

    [Note]Note

    Gradle's -v switch reports version details more directly than the explainjars task does, from the operating system version to the Groovy version (the language interpreter used for Gradle instructions).

For example, the command below builds the hsqldb.jar file:

 gradlew hsqldb

The Gradle invocations actually run Ant build targets. Some of the targets are listed in the next section.

Building with Apache Ant

You should use version 1.9 or 1.10 of Ant (Another Neat Tool) to do Ant builds with HyperSQL.

Obtaining Ant

Ant is a part of the 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

hsqldb

to build the hsqldb.jar file. This contains the engine and the GUI database manager.

explainjars

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

clean

to clean up the /classes directory that is created during a build.

clean-all

to remove the old jar and doc files as well as clean.

javadoc

to build javadoc for all public classes accessible to user applications.

dbmanswing

to build the dbmanagerswing.jar file

hsqldbmain

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

hsqldbmin

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

sqltool

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 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 (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 http://www.junit.org 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 build.properties 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 C.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.

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.

Building with IDE Compilers

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).

HyperSQL 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 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.

Example C.3. CodeSwitcher command line invocation

 java org.hsqldb.util.CodeSwitcher . -JAVA8

The '.' means the program works on the current directory (all subdirectories are processed recursively). -JAVA8 means 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 /build directory.

Building Documentation

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 particular

  • Obtain the HyperSQL documentation source. We no longer include our Guide source files in our main distribution zip file, in order to keep it small. You may want to build from the trunk branch or the latest release tag. You can download a static snapshot tarball from https://sourceforge.net/p/hsqldb/svn/HEAD/tree/ or you can use a Subversion client such as TortoiseSVN to export a snapshot or check out a work area.
  • You must locally install the DocBook set of image files, which are available for download from Sourceforge. The gen-docs task/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 -P switch to set the property, instead of editing, if they prefer).
  • You can optionally install the entire DocBook style sheets (instead of just the DocBook images within it), character entity definitions, and RNG schema file, to speed up doc build times and minimize dependency of future builds upon network or Internet. An intermediate approach would be to install these resources onto an HTTP server or shared network drive of your own. See the comments at the top of the file build.xml in the HyperSQL build directory about where to obtain these things and how to hook them in. The same Gradle task installDbImages explained above can download and install the entire stylesheet bundle (this option is offered the first time that you run the installDbImages task).
[Tip]Tip

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.

The task/target 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 doc-src for each new document, with the main DocBook source file within having same name as the directory plus .xml. See the peer directory util-guide or guide as an example. If you use the high-level tasks/target gen-docs or validate-docs, then copy and paste to add new stanzas to these targets in file build.xml.

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 target 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 build directory.

  • validation.skip
  • html.skip
  • chunk.skip
  • fo.skip
  • pdf.skip
  • doc.name
  • doc.target

See the file doc-src/readme-docauthors.txt for details about our DocBook build system (though as I write this it is somewhat out of date).


$Revision: 6366 $