Building eXist-db

• 1. Building a WAR from the Standard Distribution
• 2. Building eXist from SVN
• 3. Using the Build System
• 4. Using the Subversion Repository
  • 4.1. Checking Out from the Repository
• 5. Signing jar files for webstart
  • 5.1. Quickstart
  • 5.2. Ant targets
  • 5.3. Reducing jar sizes with pack200 compression
  • 5.4. References
  • 5.5. Notes

1. Building a WAR from the Standard Distribution

If you would like to deploy eXist into an existing servlet engine (e.g. tomcat), you will need a .war file. We no longer distribute a .war build, but it is easy to create one from the standard distribution by repackaging (not building) it:

Note that generating a WAR archive does only repackage the files in the distribution, so if the distribution worked properly for you, the WAR should as well. You don't need to recompile eXist or sign any jars.

2. Building eXist from SVN

Building eXist is quite easy and requires 3 simple steps:

3. Using the Build System

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 (build.sh or build.bat) and pass it the target dist-war:

This will create a fresh .war archive in the dist directory.

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

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

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

4. Using the Subversion Repository

Since spring 2006, the entire code base of eXist is managed by the Subversion repository at Sourceforge. 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.

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.

The repository root URL is:

The current development trunk is at:

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

4.1. Checking Out from the Repository

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:

A good choice on the Windows platform is Tortoise SVN. Tortoise is an extension to the windows shell. The following screenshot shows the checkout dialog:

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).

To access a Subversion repository from within eclipse, you need to install the subclipse plugin first! Please follow the install instructions available there.

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 New, then Repository Location. In the appearing dialog, enter the URL of the eXist development trunk:

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

Just press Finish unless you want to specify a different directory or checkout a certain tag.

5. Signing jar files for webstart

The database can be easily accessed with the Java client, when the client is launched by clicking the Java Webstart "Launch" button on the right side of this page. Java webstart explicilty requires that all application code, the 'jar' files, are signed using a security certificate. Out of the box, when eXist-db is installed using the installer, all relevant jar files have already been signed, so webstart can be used directly. It is nessecary however to (re-)sign the jar files yourself if you want to (re-)build the eXist-db java code. This chapter explains how to do this.

5.1. Quickstart

To get started quickly, just execute the following command:

This command sequentially creates the key.store file and signs a selection of jar files:

Note that this command needs to be executed just once. In subsequent builds newly generated jars are signed automatically.

5.2. Ant targets

An overview of all available ant targets can be retrieved by executing the following command:

The following ant targets are available for signing jar files:

The target jnlp-keygen generates a new certificate file key.store. If this file is present the EXIST jar files are signed during each following build. The process of signing jar files can be stopped by removing this keystore file.

The ant script contains two additional targets: jetty-keygen which generates a keystore file for the jetty server and jnlp-pack200 which processes the signed jar files with pack200 technology. More about the latter in the next section.

5.3. Reducing jar sizes with pack200 compression

Pack200 is a compression technology introduced in Java 1.5.0. It has been designed for compressing jar files and works most efficiently on Java class files. Pack200 can reduce the size of a jar file up to 60% resulting into a significant reduction of the amount of downloaded webstart data.

The webstart jar files can be compressed with pack200 with the following command:

• unsign
• repack (normalization)
• sign
• compress with pack200
• compress with gzip

The pack200 compression feature works with Java SE 6 update 10 (Java6u10) or newer. Older Java6 versions will only receive the larger jar files.

5.4. References

• Java Web Start (Wikipedia)
• Java Web Start: Pack200 compression (Wikipedia)
• Pack200 (Wikipedia)
• Pack200 (Eclipse.org)
• Pack200 and Compression for network deployment (Sun, bit out dated)
• Introducing Java SE 6 update 10: Deployment Usability (Sun).
• Ant tasks: ASOCAT.

5.5. Notes

• Sometimes when the jar files are signed, eXist-db does not start anymore. In this situation unsign the jar files first. Calling target 'jnlp-pack200' does always unsign all jar files as first step.
• The pack200 target is not executed automatically. If eXist-db code is changed and recompiled, you might want to execute the jnlp-pack200 target again.