 | Appendix C. Building HSQLDB Jars |  |
| Appendix B. HyperSQL Database Files and Recovery |  | Appendix D. HyperSQL with OpenOffice |
| | Appendix C. Building HSQLDB Jars | |
| Appendix B. HyperSQL Database Files and Recovery | | Appendix D. HyperSQL with OpenOffice |
Table of Contents
The hsqldb.jar file supplied in the lib
directory of the zip release package is tested and built with Java 11. An
separate jar for Java 8 is also supplied in the same directory. The code
is also tested extensively with Java 6-8 as well as the latest Java
versions. If you want to run with a Java 6 JVM, or use an alternative jar
(hsqldb-min.jar, etc.), you must build the desired
jar with a JDK or download from hsqldb.org. You can also find official
jars built with Java 8 and Java 11 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 |
|---|---|
|
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.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 6 and run with 8). But the newer JDBC capabilities of HyperSQL and the JRE 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 6 or later. Build has been tested under JDK versions 6, 8, 9, 10, 11, etc. 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 direcly. If compilation with Java 6 is required, you should run the Ant switchtojdk6 target before compiling to modify the files that have code blocks specific to Java 8 or above (these are listed in the jdkcodeswitch.list 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 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.
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 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 (though as I write this it is
somewhat out of date).
$Revision: 6621 $
| | |
|
| Appendix B. HyperSQL Database Files and Recovery | | Appendix D. HyperSQL with OpenOffice |