Fred Toussi HSQLDB Development Group ft@cluedup.com $Revision: 1.14 $ $Date: 2005/05/16 13:44:42 $ Hsqldb Building Ant

From 1.8.0, the supplied hsqldb.jar file is built with Java 1.5. If you want to run the engine under JDK1.3 or earlier, you should rebuild the jar with Ant.

Building with Ant Ant (Another Neat Tool) is used for building hsqldb. The version currently used to test the build script is 1.6.1 but versions since 1.5.1 should also be compatible.

Ant is a part of the Jakarta/Apache Project. Home of the Apache Ant project The Installing Ant page of the Ant Manual . Follow the directions for your platform.

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 make the hsqldb.jar 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 cleanall to remove the old jar 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 (does not support direct connection to HSQLDB URLs of the form jdbc:hsldb:mem:*, jdbc:hsqldb:file:*, nor jdbc:hsqldb:res:*). hsqldbmin to build a small jar that supports HSQLDB URLs of the form jdbc:hsqldb:mem:*, jdbc:hsqld:file*, jdbc:hsqldb:res:*; but not network URLs like jdbc:hsql* or jdbc:http*. hsqldbtest to build a larger jar for hsqldb that contains tests ... Many more targets are available. Run ant -projecthelp and ant explainjars. HSQLDB can be built in any combination of three JRE (Java Runtime Environment) versions and many jar file sizes. The smallest jar size(hsqljdbc.jar) contains only 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 and put it in the /lib directory, alongside servlet.jar, which is included in the .zip package. Just run ant explainjars for a concise list of all available jar files. If you want your code built for debugging, as opposed to high performance, make a file named build.properties in your build directory with the contents build.debug: true The resulting Java binaries will be larger and slower, but exception stack traces will contain source code line numbers, which can be extremely useful for debugging. The preferred method of rebuilding the jar is with Ant. After installing Ant on your system use the following command from the /build directory: ant explainjars The command displays a list of different options for building different sizes of the HSQLDB Jar. The default is built using: ant hsqldb The Ant method always builds a jar with the JDK that is used by Ant and specified in its JAVA_HOME environment variable. Building with JDK 1.4.x or 1.5.x will result in a jar that is not backward compatible. From version 1.7.2, use of JDK 1.1.x is not recommended for building the JAR, even for running under JDK 1.1.x -- use JDK 1.3.1 for compatibility with 1.1.x. This is done in the following way. JDK 1.3.1 should be used as the JAVA_HOME for ant. You then issue the following commands. The first command will make the sources compatible with JDK 1.3, the second command modifies the sources further so that the compiled result can run under jdk 1.1 as well. The third command builds the jar. ant switchtojdk12 ant switchtojava1target ant hsqldb

UNIX users must use Ant to build hsqldb. For DOS/Windows users, a set of MSDOS batch files is provided as an example. These files produce only the default jar size. The path and classpath variables for the JDK should of course be set before running any of the batch files. These files are not currently maintained and will probably need some additions and changes to work correctly. Please see the build.xml file for up-to-date file If you are compiling for JDK's other than 1.4.x, you should use the appropriate switchToJDK11.bat or switchToJDK12.bat to adapt the source files to the target JDK before running the appropriate buildJDK11.bat or buildJDK12.bat JDK and JRE versions.

CodeSwitcher is a tool to manage different version of Java source code. It allows to compile HSQLDB 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 HSQLDB build scripts. You do not have to use it separately to compile HSQLDB. 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. ... //#ifdef JAVA2 properties.store(out,"hsqldb database"); //#else /* properties.save(out,"hsqldb database"); */ //#endif ... The next step is to run CodeSwitcher. java org.hsqldb.util.CodeSwitcher . -JAVA2 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. ... //#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 switchtojdk1*.bat files in the /build directory.

To build the User Guide in HTML format, you must have the Docbook stylesheets installed locally. The Docbook stylesheets are available on the Internet. On Linux, just install the docbook-xsl-stylesheets rpm. Then add an entry to build.properties in your build directory with contents like docbook.xsl.home: /usr/share/sgml/docbook/docbook-xsl-stylesheets Where you specify your local path to the base directory of your Docbook stylesheet installation. Build like ant docbooks-html ant docbooks-chunk To build the User Guide in PDF format, you must also have the Java FOP system installed locally. FOP is available for free download on the Internet. Add an entry to build.properties in your build directory with contents like fop.home /usr/local/fop-0.20.5 Where you specify your local path to the base directory of your FOP installation. ant docbook Don't pay too much attention to error messages by FOP, because they are really warnings, but do check the output. If there are problems with the PDF output, try using a newer version of FOP. By default, your docs will fail to build if you do not have Internet connectivity. This is because our primary Docbook source file references the Docbook DTDs via Internet URL. You can build without Internet connectivity by installing the Docbook DTDs and editing our primary Docbook source file. Docbook is available on the Internet. On Linux, just install the docbook-dtds or docbook rpm. Then make one edit to the file docsrc/guide/guide.xml in your HSQLDB distribution. Change the line containing "http://www.oasis-open.org/docbook/xml/4.2CR1/docbookx.dtd" [ to "file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" [ where the second filepath is the path to the docbookx.dtd file within your Docbook installation.