Table of Contents
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.
| ![[Note]](../images/db/note.png) | Gradle honors JAVA_HOME | 
|---|---|
| Gradle can find the Java to use by finding out where
       | 
| ![[Important]](../images/db/important.png) | 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  | 
You can invoke Gradle builds from the command-line.
Get a command-line shell. Windows users can use either
         or , and enter "cmd". Non-windows
        users will know how to get a shell.
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.).
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).
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]](../images/db/note.png) | Note | 
|---|---|
| Gradle's -v switch reports version details more directly
          than the  | 
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 is a part of the Apache Project.
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.jarfile. 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.jarfile | 
| 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
            -pandant 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:
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.
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.
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). -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.
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 
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).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]](../images/db/tip.png) | 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.
$Revision: 6787 $