HSQLDB example source code file (building.xml)

This example HSQLDB source code file (building.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - HSQLDB tags/keywords

ant, ant, docbook, docbook, fop, hsqldb, hsqldb, internet, java, jdk, jdk, the, these, user

The HSQLDB building.xml source code

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: building.xml,v 1.14 2005/05/16 13:44:42 unsaved Exp $ -->
<appendix id="building-appendix">
  <title id="building-title">Building HSQLDB

  <appendixinfo>
    <authorgroup>
      <author>
        <firstname>Fred

        <surname>Toussi

        <affiliation>
          <orgname>HSQLDB Development Group
        </affiliation>

        <email>ft@cluedup.com
      </author>
    </authorgroup>

    <edition>$Revision: 1.14 $

    <pubdate>$Date: 2005/05/16 13:44:42 $

    <keywordset>
      <keyword>Hsqldb

      <keyword>Building

      <keyword>Ant
    </keywordset>
  </appendixinfo>

  <section>
    <title>Purpose

    <para>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.</para>
  </section>

  <section>
    <title>Building with Ant, from the Apache Jakarta Project

    <titleabbrev>Building with Ant

    <para>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.</para>

    <section>
      <title>Obtaining Ant

      <para>Ant is a part of the Jakarta/Apache Project.

      <itemizedlist>
        <listitem>
          <para>
            <ulink url="http://ant.apache.org">Home of the Apache Ant
            project</ulink>
          </para>
        </listitem>

        <listitem>
          <para>The . Follow the
          directions for your platform.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>Building Hsqldb with Ant

      <para>Once you have unpacked the zip package for hsqldb, under the
      <filename>/hsqldb folder, in /build
      there is a <filename>build.xml file that builds the
      <filename>hsqldb.jar with Ant (Ant must be already
      installed). To use it, change to <filename>/build then
      type:</para>

      <informalexample>
        <screen> ant -projecthelp
      </informalexample>

      <para>This displays the available ant targets, which you can supply as
      command line arguments to ant. These include</para>

      <variablelist>
        <varlistentry>
          <term>hsqldb

          <listitem>
            <para>to make the hsqldb.jar
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>explainjars

          <listitem>
            <para>Lists all targets which build jar files, with an explanation
            of the purposes of the different jars.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>clean

          <listitem>
            <para>to clean up the /classes directory that is created
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>cleanall

          <listitem>
            <para>to remove the old jar as well
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>javadoc

          <listitem>
            <para>to build javadoc
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>hsqldbmain

          <listitem>
            <para>to build a smaller jar for HSQLDB that does not contain
            utilities</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>hsqljdbc

          <listitem>
            <para>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:*).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>hsqldbmin

          <listitem>
            <para>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*.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>hsqldbtest

          <listitem>
            <para>to build a larger jar for hsqldb that contains tests
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>...

          <listitem>
            <para>Many more targets are available. Run ant
            -projecthelp</literal> and ant
            explainjars</literal>.
          </listitem>
        </varlistentry>
      </variablelist>

      <para>HSQLDB can be built in any combination of three JRE (Java Runtime
      Environment) versions and many jar file sizes. The smallest jar
      size(<filename>hsqljdbc.jar) contains only the HSQLDB JDBC
      Driver client. The default size (<filename>hsqldb.jar) also
      contains server mode support and the utilities. The largest size
      (<filename>hsqldbtest.jar)includes some test classes as well.
      Before building the <filename>hsqldbtest.jar package, you
      should download the junit jar from <ulink url="http://www.junit.org" />
      and put it in the <filename>/lib directory, alongside
      <filename>servlet.jar, which is included in the .zip
      package.</para>

      <para>Just run ant explainjars for a concise list of
      all available jar files.</para>

      <para>If you want your code built for debugging, as opposed to high
      performance, make a file named <filename>build.properties in
      your build directory with the contents <informalexample>
          <screen>build.debug: true
        </informalexample>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.</para>

      <para>The preferred method of rebuilding the jar is with Ant. After
      installing Ant on your system use the following command from the
      <filename>/build directory:

      <informalexample>
        <screen>ant explainjars
      </informalexample>

      <para>The command displays a list of different options for building
      different sizes of the HSQLDB Jar. The default is built using:</para>

      <example>
        <title>Buiding the standard Hsqldb jar file with Ant

        <screen>ant hsqldb
      </example>

      <para>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.
      </para>

      <para>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.<informalexample>
          <screen>ant switchtojdk12
ant switchtojava1target
ant hsqldb
</screen>
        </informalexample>
    </section>
  </section>

  <section>
    <title>Building with DOS Batch Files

    <para>UNIX users must use Ant to build hsqldb.

    <para>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</para>

    <para>If you are compiling for JDK's other than 1.4.x, you should use the
    appropriate <filename>switchToJDK11.bat or
    <filename>switchToJDK12.bat to adapt the source files to the
    target JDK before running the appropriate
    <filename>buildJDK11.bat or buildJDK12.bat
    JDK and JRE versions.</para>
  </section>

  <section>
    <title>Hsqldb CodeSwitcher

    <para>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.</para>

    <para>CodeSwitcher is used internally in HSQLDB build scripts. You do not
    have to use it separately to compile HSQLDB.</para>

    <para>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.</para>

    <example>
      <title>Example source code before CodeSwitcher is run

      <programlisting>
        ...

    //#ifdef JAVA2

        properties.store(out,"hsqldb database");

    //#else

    /*

        properties.save(out,"hsqldb database");

    */

    //#endif

        ...</programlisting>
    </example>

    <para>The next step is to run CodeSwitcher.

    <example>
      <title>CodeSwitcher command line invocation

      <screen>
    java org.hsqldb.util.CodeSwitcher . -JAVA2</screen>
    </example>

    <para>The '.' means the program works on the current directory (all
    subdirectories are processed recursively). <literal>-JAVA2 means
    the code labelled with JAVA2 must be switched off.</para>

    <example>
      <title>Source code after CodeSwitcher processing

      <programlisting>
        ...

    //#ifdef JAVA2

    /*

        pProperties.store(out,"hsqldb database");

    */

    //#else

        pProperties.save(out,"hsqldb database");

    //#endif

        ...</programlisting>
    </example>

    <para>For detailed information on the command line options run
    <classname>java org.hsqldb.util.CodeSwitcher. Usage examples
    can be found in the switchtojdk1*.bat files in the
    <filename>/build directory.
  </section>

  <section>
    <title>Building documentation

    <para>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
    <literal>docbook-xsl-stylesheets rpm. Then add an entry to
    <filename>build.properties in your build directory with
    contents like <informalexample>
        <screen>docbook.xsl.home: /usr/share/sgml/docbook/docbook-xsl-stylesheets
      </informalexample> Where you specify your local path to the base
    directory of your Docbook stylesheet installation. Build like <example>
        <title>Building HTML User Guides

        <screen>ant docbooks-html
ant docbooks-chunk</screen>
      </example>

    <para>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 <filename>build.properties in your
    build directory with contents like <informalexample>
        <screen>fop.home /usr/local/fop-0.20.5
      </informalexample> Where you specify your local path to the base
    directory of your FOP installation. <example>
        <title>Building User Guides in all formats

        <screen>ant docbook
      </example> 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.</para>

    <important>
      <para>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 <literal>docbook-dtds or
      <literal>docbook rpm. Then make one edit to the file
      <filename>docsrc/guide/guide.xml in your HSQLDB distribution.
      Change the line containing <screen>"http://www.oasis-open.org/docbook/xml/4.2CR1/docbookx.dtd" [
      to <screen>"file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" [
      where the second filepath is the path to the
      <filename>docbookx.dtd file within your Docbook
      installation.</para>
    </important>
  </section>
</appendix>