Appendix B. Building HyperSQL Jars
Keywords: HSQLDB, HyperSQL, Building, Ant, Gradle

| Appendix B. Building HyperSQL Jars |
Appendix A. Lists of Keywords |  | Appendix C. HyperSQL with OpenOffice

# Building HyperSQL Jars

### How to build customized or specialized jar files

### Fred Toussi

The HSQL Development Group

$Revision: 4909 $

2012-08-06 00:10:58+0100

## Purpose

From version 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 SDK.

The Gradle task / Ant target `explainjars` reports the versions of Java and Ant actually used.

## Building with Gradle

As noted above, Java SDK 5 or later is required.

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

### Invoking a Gradle Build Graphically

Whether from an IDE, a shortcut or launch icon, to run a Gradle graphical build you just need to execute either the file `gradle-gui.cmd` (on Windows) or `gradle-gui` (all other platforms), both of which reside in the `build` directory of your HyperSQL distribution.

I will explain how to invoke a graphical Gradle build from Windows Explorer and from Eclipse IDE. Users of other operating systems should be able to infer how to use their own file manager in the same way as shown for Internet Explorer. Users who want a desktop shortcut, quick-launch icon should first get Gradle working from a file manager (like Windows Explorer), then seek out instructions for making shortcuts, etc. for your operating system or desktop manager. (Try a web search).

Some IDEs, like IntelliJ have direct support for Gradle. The Spring Framework team is working on a sophisticated plugin for using Gradle with their IDE. But I'm going to document a very basic setup done with Eclipse because it's serviceable and a very similar procedure is likely to work with all other IDEs.

If you do use and enjoy Gradle, then I urge you to make the product better by registering a free account for yourself at the Gradle Jira site and vote for critical usability issues like GRADLE-427, GRADLE-1855, GRADLE-1870, GRADLE-1871, to help to improve the product.

Procedure B.1. Invoking Gradle GUI from Windows Explorer

1. Start up Windows explorer. Depending on your Windows version, it will be in the Start Menu, or in the menu you get when you right-click Start.

2. Navigate Windows Explorer to the `build` directory within your HyperSQL installation.

3. Find an icon or line (depending on your Windows Explorer view) for the file `gradle-gui.cmd`. If there is no listing for `gradle-gui.cmd`, but two listings for `gradle-gui`, then you want the one signified by text, icon, or mouse-over tooltip, as a batch or CMD file. Double-click this item.

Procedure B.2. Setting up Gradle Graphical Builds from Eclipse IDE

1. From Eclipse, use pulldown menu Run / External Tools / External Tools Configurations....

2. Right-click on Program in the left navigator Right-click Project in the left navigator panel and select New. (Depending on the state of your workspace, instead of New in the context-sensitive menu, there may be a New_configuration or similar item nested under Program, in which case you should select that).

3. To the right, change the value in the Name: field to `HSQLDB Gradle` (or whatever name you want for this launcher config (this Gradle launcher is only for your HSQLDB project).

4. Make sure that the Main tab is selected.

5. For the Location: field, use the Browse Workspace... button to navigate to and select the `gradle-gui.cmd` (Windows) or `gradle-gui` (other) file in the `build` directory of your HyperSQL project.

   Configuring Gradle GUI Launcher in Eclipse

   Depending on your Eclipse version and workspace setup, the value populated into the Location: field after you select the program may appear very differently than in this screen shot.

6. Click the Run button. The Gradle Gui should run. (If you just Apply and Close here instead of Run, the new Gradle launch item will not be added to the pulldown and toolbar menus).

After doing the Eclipse setup, you can use pulldown menu Run / External Tools or the equivalent tool bar button button to launch the Gradle Gui.

Invoking Gradle GUI from Eclipse

You can do this and close it after each use, or, to avoid startup lag, minimize it when it's not in use.

### Invoking a Gradle Build from the Command Line

You can invoke graphical and non-graphical 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` or `gradle-gui` command in the next step with `./` (e.g., like `./gradlew`).

4. In the shell, run either `gradle-gui` for a graphical build; or `gradlew` for a text-based build.

The `gradle-gui` file is our own wrapper script for `gradlew --gui`. Be aware that both `gradle-gui` and `gradlew --gui` suffer from the limitation that the `--gui` switch is mutually exclusive with most or all other arguments (including tasks). I have registered GRADLE bugs 1861 and 1863 about this.

### Using Gradle

#### Using Text-based Gradle

If you ran just `gradlew` or `gradlew.bat`, 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` or `gradle.bat` command repeatedly, with different switches and arguments.

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

#### Using the Gradle GUI

Sample Gradle GUI Screen

Procedure B.3. First Time using Gradle Gui

1. It takes the Gradle gui a while to start up, because, similar to an IDE, it is generating a list of details about available tasks.

2. In the main window, in the top panel, with the Task Tree tab selected, you have the list of public tasks, sorted alphabetically. Down bottom is displayed the output of the last task(s) execution. (After startup it will show the output of the task `tasks`).

3. Scroll to the `help` task and click it once to select it, then click the green Execute toolbar button above. (You could also have double-clicked the item, but you can use the selection procedure to pick multiple tasks with Control or Shift keys to execute multiple tasks in a single run-- and the tasks will execute in the same order that you had selected them).

4. Scroll through and read the output of the `help` task in the bottom panel. Where this help screen speaks about verbosity switches, you can accomplish the same thing by using the Setup tab. Whenever Gradle output (in the bottom panel) talks about running `gradlew <sometask>...`, you can execute the specified task(s) by selecting and executing them like we just did.

| Gradle GUI Limitations
The Gradle GUI is fairly new and lacks some of the power available to text-based users. Most significantly, in my opinion, is the following item for which I have opened Gradle issues 1855. There is no convenient way to set build properties. 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 Apache Ant

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

### Obtaining Ant

Ant is a part of the Jakarta/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
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
clean-all | to remove the old jar and doc files as well
javadoc | to build javadoc
hsqldbmain | to build a smaller jar for HSQLDB that does not contain utilities
hsqljdbc | to build an extremely small jar containing only the client-side JDBC driver (can connect only to a HyperSQL Server).
hsqldbmin | to build a small jar that supports in-process catalogs, but neither running nor connecting to 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 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 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 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 Gradle or 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 Compilers

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 Gradle or Ant. Only if compilation with Java 1.5 is required, you should first run the Gradle task (or Ant target) 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 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 B.2. Example source code before CodeSwitcher is run

            ...

        //#ifdef JAVA2

            properties.store(out,"hsqldb database");

        //#else

        /*

            properties.save(out,"hsqldb database");

        */

        //#endif

            ...

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

        /*

            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 http://hsqldb.svn.sourceforge.net/viewvc/hsqldb/base/trunk/ or under http://hsqldb.svn.sourceforge.net/viewvc/hsqldb/base/tags/ , or you can export a snapshot or check out a work area using a Subversion client.
- 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
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 decrease 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: 4864 $

Appendix A. Lists of Keywords |  | Appendix C. HyperSQL with OpenOffice