 | Appendix B. Building HyperSQL Jars |  |
| Appendix A. Lists of Keywords |  | Appendix C. HyperSQL with OpenOffice |
| | Appendix B. Building HyperSQL Jars | |
| Appendix A. Lists of Keywords | | Appendix C. HyperSQL with OpenOffice |
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 or older 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 |
|---|---|
|
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.
| 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.jar
file |
|
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
-p and ant 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: 4864 $
| | |
|
| Appendix A. Lists of Keywords | | Appendix C. HyperSQL with OpenOffice |