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:
Get a standard distribution from the download page. Install it into a directory of your choice. Make sure you include the source package.
Open a command line prompt and change to the directory where you just installed eXist. Call
or
once. This will generate a .war archive into directory dist.
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.
Building eXist is quite easy and requires 3 simple steps:
The SVN URL for the development trunk is:
The URL for the latest stable release is:
You usually want to use the stable release branch on a production system. The stable branch is the basis for all official releases during the lifecycle of a major version.
You need an SVN client to check out the source code. Examples for SVN clients are Tortoise SVN on the windows platform or the command line SVN tools on Unix (see below). The oXygen XML editor ships with its own SVN client.
Before starting the build, your JAVA_HOME environment variable should be set to point to the root directory of the JAVA JDK (note: JDK, not JRE!). Open a console or a DOS box on windows and type:
on windows or
on unix.
Change into the eXist directory you just checked out and call
on windows or on unix:
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.
To be able to use the build system, you need to include the "source" module when selecting installable packages in the installer GUI.
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:
| jar | The default: compiles the source and creates eXist's main .jar files |
| samples | Builds the examples and packs them into examples.jar |
| javadocs | Creates the API docs into webapp/api |
| docs | Creates a static HTML version of the documentation into docs.zip |
| dist-war | Packages eXist into a .war file for deployment within a servlet engine |
| extensions | Creates the necessary .jar files for eXist's extensions. Read extensions/modules/build.properties to select the extensions to build. |
| installer | Creates a new installer package based on IzPack |
| test | Runs all tests in the test suite and outputs the HTML result into test/junit/html. This may take several minutes. |
| xquery | Regenerate the XQuery parser code with ANTLR (only required if you change src/org/exist/xquery/parser/XQuery.g). |
| clean | Cleans the files and directories generated by a previous build. |
You might want to set some custom settings (in particular your HTTP proxy when external libraries are required) before running build.sh or build.bat. See build.properties.
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:
Please note you have to use https, not http.
The current development trunk is at:
This is the URL you will normally use for a checkout of the main eXist development tree.
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 , then . 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 . A progress window appears, saying that eclipse is "getting remote info". Once it finished, you should see the following dialog:
Just press unless you want to specify a different directory or checkout a certain tag.
The build scripts will not work with Cocoon 2.2. We are currently looking for an experienced Cocoon user to help us updating the scripts.
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.
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.
The build scripts were tested with Cocoon version 2.1.9 and a clean Cocoon source tree.
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.
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.
To build Cocoon with eXist as a block, do the following:
Download the latest and greatest Cocoon source distribution from the Apache website. Do not compile Cocoon - you have to prepare it first!
Unzip or untar the downloaded file into a directory of your choice.
Change back to the directory where you installed eXist (referred to as EXIST_HOME in the following). Open build/scripts/cocoon/build.properties with a text editor. Change the property cocoon.home to point to the directory where you unpacked Cocoon (use / to separate path components, not \).
From inside the top directory of the eXist distribution (EXIST_HOME), launch the following command:
on Unix or
on Windows.
The script will now start to patch the Cocoon source tree. Once it has finished, you should see a message with further instructions:
Switch to the Cocoon install directory and call build.sh or build.bat. The Cocoon build process starts. It may show some warnings, but should otherwise build without obvious errors.
To test your build, start Cocoon with:
or
Like all the other blocks that come with Cocoon, the eXist web pages are available in the /samples/blocks/exist path. Point your browser to:
http://localhost:8888/samples/blocks/exist/
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.
