This step is not necessary to use the standard out of the box version of James. A pre-built binary version of James is available from the James download directory. But if you wish to customize the James source code, it will be necessary for you to build the distribution yourself.

Getting the Source Code

There are two ways to get the James source code.

1. Download the source distribution - the source is available from the James release mirrors. Simply choose the version of James you'd like to download, and pick the source distribution appropriate for your platform.

2. Get the source code using CVS - this method gives you access to the cutting edge code base. Instructions on how to use CVS to get the James source code (the jakarta-james distribution) can be found here.

Required Tools

To run the build you need two third-party tools.

1. Java Development Kit - You must have a JDK of Java version 1.3 or higher installed to build the James distribution. The exact JDKs available depend on the platform. A JDK must be downloaded and installed before the build can run.

2. Ant - This is a Java-tailored, XML-configured, extensible build or make system. The James source tree includes Ant v1.5. You can get the latest version of Ant here. Since Ant is currently included in the source distribution, it is not necessary to download it separately.

Building the Distribution

In the top level directory of the source distribution James includes two helper scripts for running the build. The script build.bat should be used on Windows systems, while build.sh is appropriate for Unix systems. Each script takes an optional set of arguments that tell the script exactly what to build.

To use these scripts, simple set the environment variable JAVA_HOME to the base directory of the JDK. Then run the build script, optionally with any of the following command line arguments:

  • clean - deletes the build directory, making the system ready for a clean build.
  • compile - compiles the source code.
  • dist - generates all the James distributions, packed.
  • dist-lite - generates all the James distributions, unpacked. This is the default argument.
  • javadocs - builds the James javadocs.
  • usage - prints out the usage instructions for the script.
  • website - builds the entirety of the James website.
  • xdocs - creates the documentaion for James.

All build products are output in the dist subdirectory of the James source distribution directory. There is also a build subdirectory of the James source distribution directory that is created during the build process. Both of these directories will be deleted if you run build with the clean argument.

Warning! Any changes you've made in the 'dist' directory will be lost after a recompilation. If you are making changes to the config.xml or other files, we recommend you backup and then change the copies in src to avoid losing work.