Building HSQLDB Jars

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

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.

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.

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

 ant -projecthelp

build.debug: false

ant explainjars

ant hsqldb

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.

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.

 ...

 //#ifdef JAVA8

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

 //#else

 /*

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

 */

 //#endif

 ...

The next step is to run CodeSwitcher.

 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.

     ...

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

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

	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.

See the file doc-src/readme-docauthors.txt for details about our DocBook build system.