| Appendix C. Building HSQLDB Jars |
Appendix B. HyperSQL Database Files and Recovery |  | Appendix D. HyperSQL with OpenOffice

# Building HSQLDB Jars

### How to build customized or specialized jar files

### Blaine Simpson

The HSQL Development Group

### Fred Toussi

The HSQL Development Group

$Revision: 6787 $

2024-10-25

## Purpose

The `hsqldb.jar` file supplied in the lib directory of the zip release package is built and tested with Java 11. An separate jar for Java 8 is also supplied in the same directory. The jars have been tested extensively with the latest Java versions. You can also find the official jars 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.

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

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

- Home of the Apache Ant project
- The Installing Ant page of the Ant Manual. Follow the directions for your platform.

### 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 8 and run with 11 but the Java module capabilities of HyperSQL 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 8 or later. Build has been tested under JDK versions 8, 11, and 21. 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 directly.

## HyperSQL CodeSwitcher

CodeSwitcher is a tool to manage conditional compilation of Java source code. 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 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. The current version of HSQLDB does not use the CodeSwitcher.

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

Java 11 is the only supported JDK for building the 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 style sheet bundle (this option is offered the first time that you run the `installDbImages` task).

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

$Revision: 6787 $

Appendix B. HyperSQL Database Files and Recovery |  | Appendix D. HyperSQL with OpenOffice