Table of Contents
From version 2.0, the supplied hsqldb.jar
    file is built with Java 1.6. If you want to run with a 1.5 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.
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.
| ![[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  | 
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
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 .
Navigate Windows Explorer to the build
          directory within your HyperSQL installation.
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
From Eclipse, use pulldown menu / / .
Right-click on Program in the left navigator Right-click Project in the left navigator panel and select . (Depending on the state of your workspace, instead of in the context-sensitive menu, there may be a New_configuration or similar item nested under Program, in which case you should select that).
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).
Make sure that the Main tab is selected.
For the  field, use the
           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.
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 / 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.
You can invoke graphical and non-graphical 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 or
          gradle-gui command in the next step with
          ./ (e.g., like
          ./gradlew).
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.
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]](../images/db/note.png) | Note | 
|---|---|
| Gradle's -v switch reports version details more directly
          than the  | 

Sample Gradle GUI Screen
Procedure B.3. First Time using Gradle Gui
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.
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).
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).
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  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.
| ![[Note]](../images/db/note.png) | 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  | 
You should use version 1.7.x of Ant (Another Neat Tool) to do Ant builds with HyperSQL.
Ant is a part of the Jakarta/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 | 
| 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
            -pandant 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:
The Ant method always builds a jar with the JDK that is used by Ant and specified in its JAVA_HOME environment variable.
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
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).
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.
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.
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 stylesheet 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
    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. 
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: 5675 $