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.
Gradle honors JAVA_HOME |
|
---|---|
Gradle can find the Java to use by finding out where
|
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
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 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 (2.7.3) 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 | |
---|---|
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: 6752 $