<?xml version="1.0" encoding="UTF-8"?>
<article>
    <articleinfo>
        <productname>Open Source Native XML Database</productname>
        <title>Building eXist</title>
        <author>
            <firstname>Wolfgang</firstname>
            <surname>Meier</surname>
            <email>wolfgang at exist-db.org</email>
        </author>
    </articleinfo>

    <ci:include xmlns:ci="http://apache.org/cocoon/include/1.0" src="sidebar.xml"/>

    <section>
        <title>Using the Build System</title>

        <para>You can rebuild all eXist packages from the standard distribution or the subversion
            repository. You can even create a new distribution from the one you installed. For
            example, assume you installed eXist using the installer GUI, but you need to have an
            exist.war package for deployment within a different servlet engine. Just call the main
            build script (<filename>build.sh</filename> or <filename>build.bat</filename>) and pass
            it the target <option>dist-war</option>:</para>

        <synopsis>build.sh dist-war</synopsis>

        <para>This will create a fresh <filename>.war</filename> archive in the
            <filename>dist</filename> directory.</para>

        <note>
            <para>To be able to use the build system, you need to include the "source" module when
                selecting installable packages in the installer GUI.</para>
        </note>

        <para>eXist relies on Ant for all compile and build tasks. Ant is included in the
            distribution (directory <filename>tools/ant</filename>). As already mentioned above,
            there are two shell scripts to start Ant: <filename>build.sh</filename> or
                <filename>build.bat</filename>. The shell scripts will take care to create a proper
            command line to launch Java with the Ant version included in the distribution.</para>

        <para>Calling Ant without further argument will compile the sources and create the main
            jar-files (<filename>exist.jar</filename>, <filename>exist-optional.jar</filename>,
                <filename>start.jar</filename>).</para>

        <synopsis>build.sh -projecthelp</synopsis>

        <para>lists the available build targets. Passing one of these as argument to ant will call
            execute the corresponding target. The main targets are:</para>

        <table>
            <title>Useful Build Targets</title>

            <tgroup cols="2">
                <tbody>
                    <row>
                        <entry>jar</entry>
                        <entry>The default: compiles the source and creates eXist's main jar
                        files</entry>
                    </row>
                    <row>
                        <entry>samples</entry>
                        <entry>Builds the examples and packs them into examples.jar</entry>
                    </row>
                    <row>
                        <entry>javadocs</entry>
                        <entry>Call javadoc to create the API docs</entry>
                    </row>
                    <row>
                        <entry>docs</entry>
                        <entry>Create a static HTML version of the documentation</entry>
                    </row>
                    <row>
                        <entry>dist-war</entry>
                        <entry>Packages eXist into a .war file for deployment within a servlet
                            engine</entry>
                    </row>
                    <row>
                        <entry>installer</entry>
                        <entry>Creates a new installer package based on IzPack</entry>
                    </row>
                    <row>
                        <entry>test</entry>
                        <entry>Runs all tests in the test suite. This may take several
                        minutes.</entry>
                    </row>
                    <row>
                        <entry>xquery</entry>
                        <entry>Regenerate the XQuery parser code with ANTLR (only required if you
                            change
                        <filename>src/org/exist/xquery/parser/XQuery.g</filename>).</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </section>

    <section>
        <title>Using the Subversion Repository</title>

        <para>Since spring 2006, the entire code base of eXist is managed by the <ulink
                url="http://sourceforge.net/svn/?group_id=17691">Subversion repository at
                Sourceforge</ulink>. Before that we used CVS, which had a few issues, especially due
            to the separation into a developer's and anonymous server. Using Subversion should be
            much simpler, faster and more reliable.</para>

        <para>Fortunately, you don't need to be a hardcore Java developer to use the SVN version of
            eXist. In general, we try to keep the development version in a consistent state. The
            code should always compile and run the test cases, though temporary failures are
            possible, especially while a larger update is in progress.</para>

        <para>The repository root URL is:</para>

        <synopsis>https://svn.sourceforge.net/svnroot/exist</synopsis>

        <important>
            <para>Please note you have to use https, not http.</para>
        </important>

        <para>The current development trunk is at:</para>

        <synopsis>https://svn.sourceforge.net/svnroot/exist/trunk/eXist-1.0</synopsis>

        <para>This is the URL you will normally use for a checkout of the main eXist development
            tree.</para>

        <section>
            <title>Checking Out from the Repository</title>

            <para>There are many Subversion clients to choose from. If you want to actively
                contribute to eXist or otherwise work on eXist's source code, we recommend to use
                eclipse to check out the sources (see below) and setup a project. Otherwise, you can
                use any other SVN client. On Linux, I prefer the plain command line. For example,
                the following command checks out the main development trunk into a directory called
                eXist-trunk:</para>

            <synopsis>svn co https://svn.sourceforge.net/svnroot/exist/trunk/eXist-1.0 eXist-trunk</synopsis>

            <para>A good choice on the Windows platform is <ulink
                    url="http://tortoisesvn.tigris.org/">Tortoise SVN</ulink>. Tortoise is an
                extension to the windows shell. The following screenshot shows the checkout dialog:</para>

            <screenshot><graphic fileref="resources/tortoise.png"/></screenshot>

            <para>The repository already contains project configuration files for eclipse, so
                setting up the project should be pretty simple: you normally don't need to change
                much in order to dive into the source code (though you may need some customizations
                to build and run directly from within eclipse).</para>

            <para>To access a Subversion repository from within eclipse, you need to install the
                    <ulink url="http://subclipse.tigris.org/">subclipse</ulink> plugin first! Please
                follow the <ulink url="http://subclipse.tigris.org/install.html">install
                    instructions</ulink> available there.</para>

            <para>Once you installed subclipse, change to the perspective: "SVN Repository
                Exploring". In the "SVN Repository" tab of the left view, right click into the empty
                space and select <guimenu>New</guimenu>, then <guimenu>Repository
                Location</guimenu>. In the appearing dialog, enter the URL of the eXist development
                trunk: </para>

            <screenshot><graphic fileref="resources/subclipse1.png"/></screenshot>

            <para>The URL will now be listed in the "SVN Repository" view. Right click the URL and
                select <guimenu>Checkout</guimenu>. A progress window appears, saying that eclipse
                is "getting remote info". Once it finished, you should see the following dialog:</para>

            <screenshot><graphic fileref="resources/subclipse2.png"/></screenshot>

            <para>Just press <guimenu>Finish</guimenu> unless you want to specify a different
                directory or checkout a certain tag.</para>
        </section>
    </section>

    <section>
        <title>Building eXist as a Cocoon Block</title>

        <important>
            <para>The build scripts described here are currently only available in SVN, revision
                4676 or newer.</para>
        </important>
        
        <para>The standard eXist distribution already ships with Apache Cocoon. However, the
            included version may not be up to date and it offers only a subset of the Cocoon modules
            available. If you work a lot with Cocoon, you might prefer to have eXist integrated into
            a full Cocoon build. This is possible and we provide a set of build scripts to "inject" eXist
            into a downloaded Cocoon source distribution.
        </para>

        <para>Cocoon has a modular architecture. Most of the advanced features are provided via
            so-called "blocks". eXist's ant scripts patch the Cocoon source tree to add a new eXist block.
        </para>

        <note>
            <para>The build scripts were tested with Cocoon version 2.1.9 and a clean Cocoon
                source tree.</para>

            <para>Unfortunately, patching Cocoon isn't that easy. Cocoon ships with a few libraries, which
                are incompatible with the ones used in eXist. This applies in particular to the XML:DB API
                sources. eXist uses the latest sources from CVS while Cocoon has jars built from an older
                version. Also, in order to run the webstart Java client, we need to sign a few jars.</para>
            <para>I don't think the patches will break any existing functionality in Cocoon. So far, I have
                not encountered any problems. However, it might not be possible to use XIndice and eXist at
                the same time, due to the XML:DB incompatibilities.</para>
        </note>

        <para>To build Cocoon with eXist as a block, do the following:</para>

        <procedure>
            <step>
                <para>Download the latest and greatest Cocoon source
                    distribution from the Apache
                    <ulink url="http://cocoon.apache.org">website</ulink>. Do not compile
                    Cocoon - you have to prepare it first!
                </para>
            </step>

            <step>
                <para>Unzip or untar the downloaded file into a directory of your choice.</para>
            </step>

            <step>
                <para>Change back to the directory where you installed eXist (referred to as
                    EXIST_HOME in the following). Open
                    <filename>build/scripts/cocoon/build.properties</filename> with a text
                    editor. Change the property <option>cocoon.home</option> to point to
                    the directory where you unpacked Cocoon (use / to separate path
                    components, not \).
                </para>
            </step>

            <step>
                <para>From inside the top directory of the eXist distribution (EXIST_HOME), launch
                    the following command:</para>

                <synopsis>./build.sh -f build/scripts/cocoon/build.xml</synopsis>

                <para>on Unix or</para>

                <synopsis>build.bat -f build/scripts/cocoon/build.xml</synopsis>

                <para>on Windows.</para>
            </step>

            <step>
                <para>The script will now start to patch the Cocoon source tree. Once it has finished,
                you should see a message with further instructions:</para>

                <screen>
[echo] Cocoon has been prepared. You may now change to
[echo] /home/wolf/IDEA/cocoon-2.1.9
[echo] and call build.sh or build.bat to build Cocoon.

BUILD SUCCESSFULL
                </screen>
            </step>

            <step>
                <para>Switch to the Cocoon install directory and call <filename>build.sh</filename>
                    or <filename>build.bat</filename>. The Cocoon build process starts. It may show
                    some warnings, but should otherwise build without obvious errors.
                </para>
            </step>

            <step>
                <para>To test your build, start Cocoon with:</para>

                <synopsis>cocoon.sh</synopsis>

                <para>or</para>

                <synopsis>cocoon.bat</synopsis>

                <para>Like all the other blocks that come with Cocoon, the eXist web pages are
                    available in the <filename>/samples/blocks/exist</filename> path. Point your
                    browser to:
                </para>

                <para><ulink url="http://localhost:8888/samples/blocks/exist/">
                    http://localhost:8888/samples/blocks/exist/</ulink></para>

                <para>You should see eXist's usual welcome page. All the links and sample
                applications should work in this setup. You may also run the Java webstart
                    client by clicking on the corresponding link in the navigation sidebar.</para>
            </step>
        </procedure>
        
    </section>
</article>