Why Build from Source?

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.

You can read on this page how to build from the command line and from eclipse IDE.

Get 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 SVN - this method gives you access to the cutting edge code base. Instructions on how to use SVN to get the James source code can be found here. Apache James Server beta1 repository is http://svn.apache.org/repos/asf/james/server/tags/james-server-3.0-beta1/.
  3. For information, you can download all Apache James sources (server, mailbox, imap, mailet...) if you check out http://svn.apache.org/repos/asf/james/current/. Watch out!: you will get a release, but what we call a "trunk", that is on constant development and debugging.

We consider in this document that you have checked-out James source code in JAMES_SRC_HOME directory.

Consult the architecture page if you want to learn more on the internal source structure.

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.6 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. Maven 3.0.2 - This is a Java-tailored, XML-configured, extensible build or make system. You need maven (3.0.2+) in order to build James. You can get maven 3.0.2 from here. Installation instructions for maven are also available on the same page http://maven.apache.org/download.html.

Set (on windows) or export (on Unix) MAVEN_OPTS to tune the memory needed by maven with "MAVEN_OPTS=-Xmx1024m -XX:MaxPermSize=128m"

Build James Source from Command Line

In the JAMES_SRC_HOME top level directory (where the parent pom.xml resides), invoke maven with 'mvn' with any of the following command line arguments:

  • clean - deletes the target directory, making the system ready for a clean build.
  • compile - compiles the source code.
  • test - run unit tests for James.
  • package - generates all the James distributions, packed. From the root directory, cd to 'container-spring/target' to have the build distribution. Notice, for the latest trunk(revision 1430655+), a specific profile argument need to be set: '-Pwith-assembly'. The location of final distributions is also changed to 'JAMES_SRC_HOME/server/app/target'.
  • javadocs:javadocs - builds the James javadocs.
  • site - builds the entirety of the James website.

For example, invoke mvn package to get a zip/tar of James distribution.

All built products are output in the container-spring/target subdirectory of the James source directory. This directory 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 running James for this directory we recommend you backup to avoid losing work.

You can also invoke the command line from a shell. Go to the server project cli folder and type mvn exec:java -Dexec.args="-h localhost -p 9999 help"

Build James Source from Eclipse

Import projects in Eclipse with m2eclipse

You should have Eclipse IDE with m2eclipse plugin installed.

You now need to import the maven projects in the Eclipse workspace.

Therefore, click on the File menu and select Import. Choose Existing Maven Project and click on Next button.

Select Projects to Import

Select the JAMES_SRC_HOME directory where you have checked out the source code.

Eclipse should present you with the list of James server modules.

Select the modules you want to import (by default, all) and click on Finish to execute the import.

You can also import other projects from imap, mailbox and protocols to have a more complete view on the used sources code.

Enable Workspace Resolution

Check that 'Workspace resolution' is enable in m2eclipse plugin.

Your changes in code will be directly taken into account.

Prepare projects

Now you have James projects in Eclipse workspace.

You still have to prepare the following to be able to run from Eclipse:

  1. Copy the context folder, log4j.properties and META-INF folder from container-spring\src\main\config\james directory to a source folder of container-spring project (you can use for example a new folder called stage as Eclipse source folder).
  2. Copy all files (except context folder log4j.properties and META-INF/persistence.xml) from container-spring\src\main\config\james folder to a conf folder (conf folder must be a sub-folder of the JAMES_SRC_HOME directory where you made the check-out). As non-root privilege user, you may need to change the SMTP/IMAP/POP3 ports to values higher than 1024.
  3. For ease, you can also create 2 new eclipse projects to edit the files and visualize the created mails/store/...: james-server-container-spring-conf and james-server-container-spring-var.

Run James from Eclipse

That's it. Run or Debug James in Eclipse (right-click on the Main class) and Have Fun!.

If you change a JPA Entity class, your will need to run 'mvn package' or add the following option to the VM argument of your run configuration '-javaagent:my_home_folder/.m2/repository/org/apache/openjpa/openjpa/2.0.1/openjpa-2.0.1.jar'

Build James from NetBeans

This was done using NetBeans 7, which comes bundeled with Maven 3, needed to build James 3. Older versions of NetBeans should be able to build James fine, provided that you configure them to use an instance of Maven 3, if they do not have it. I used james 3.0-beta1 release and it builded in 7:40 min on my notebook running Debian Squeeze.

Getting the sources from the repository

Building James with NetBeans is very easy as it comes with Subersion and Maven support already build in. Maven is bundeled with the IDE, but Subverion is not, so you will have to install Subversion yourself and NetBeans will be able to use it. You can get more details on how to install and where to get Subversion from the NetBeans Help menu by clicking on Help Contents and from there go to the IDE Basics->Version Control and File Hierarchy->Subversion topic.

For Linux users, Subversion is probably packaged by your distribution so use your distribution tools to install it (aptitude, yum, etc.)

Once you have Subversion, go to Team->Subversion->Checkout menu entry.
You will see an dialog window used to enter the information about the Subversion repository you are going to use. It looks like this: .
In the Repository URL field enter the location for James repository and click Next. You can use the following URL to get the trunk or developement version: http://svn.apache.org/repos/asf/james/server/trunk.
After this you will be presented with another dialog window where you can configure which folders to check out and where to save them on your machine. .
If you supplied the above URL you can click Finish to get trunk version and start hacking. You can choose another folder by clicking Browse. A new dialog window will open and from there you cand browse the whole subversion repository. I wanted to build James 3.0beta so I choosed james-serve-3.0-beta1 under james/server/tags/ folder. .

After you click Finish NetBeans will checkout the sources. It will detect the Maven project and ask you if you wish to open the project. If you open the project you will see in the Projects Window (CTRL+1 if not visible) something similar to the next image:
.

Building the project

Building the project does not require too much work. Just go to Run->Build Project menu option. Make sure that James is the main project (if you have other projects open) or NetBeans will build that project instead of James. Once the build is finished you will find the binary distribution in container-spring/target directory. .

Build James Source from other IDEs

We will be happy to include on this page any other tutorial you could send use about developing James with your favorite Integrated Development Environment.