How To: Build MPXJ

Although MPXJ can be downloaded as a complete package from SourceForge, the development of the library continues between releases and is driven by user requests for new functionality, and bug fixes being applied to existing features. Many MPXJ users will work with and ship software based on intermediate versions of MPXJ built from the code in Git in order to take advantage of these enhancements before they become available in an official release. This approach is supported by the fact that code is only checked into Git if the suite of JUnit regression tests have been completed successfully: therefore the quality of the code taken from Git at any point can be guaranteed to be as good as that in an official release.

In order to take advantage of MPXJ functionality from Git, you will need to understand how to build the library, whether you are using it in the form of a Java JAR or a .NET DLL. The following sections explain how to do this.

Obtaining the source

The first step in the process of building your own version of MPXJ is to obtain the latest source from Git. The MPXJ Git repository is described here. If you are working with Git from the command line, you will need to execute the following command to clone the repository:

git clone git://git.code.sf.net/p/mpxj/mpxj mpxj-mpxj  

Building the Java JAR

The MPXJ build process is based on the use of an Ant script. If you aren't familiar with Ant, it is a script execution tool similar in concept to make or nmake. The prerequisites for building MPXJ are:

  • A Java Development Kit (JDK) - at the minimum Java 1.6 is required. A suitable JDK can be downloaded from Oracle
  • Apache Ant. I wrote these instructions using version 1.9.2, but the ant build script will probably work happily with older or newer versions. Ant can be downloaded from http://ant.apache.org
  • The latest version of MPXJ from Git. Details of the MPXJ Git repository and how to use it can be found here.

Here are the steps required to build MPXJ, they assume that both Java and Ant are available on the path.

  1. Change directory to the the MPXJ folder.
  2. At your command prompt, execute the command "ant clean". This will remove any temporary files or previous output from the build process.
  3. At your command prompt, execute the command "ant archive". This will build the JAR file.
  4. That's it! The file mpxj.jar should now be sat in the root of your MPXJ folder.

Building the .NET DLLs

Building the .NET DLL version of MPXJ uses the same steps described for building the Java JAR file, but with the additional prerequisite that IKVM is available on your system. The steps required are as follows.

  1. Download IKVM from http://www.ikvm.net and unzip the files into a convenient directory.
  2. Change directory to the MPXJ folder.
  3. Edit the build.xml file and ensure that the property named ikvm.dir is set to point to the location where you have unzipped IKVM.
  4. Now you can follow the steps described above to build the Java JAR file. The Ant script will recognise that IKVM is present and build the .NET DLL in the lib.net folder.

Building the Javadoc

The most recent Javadocs for MPXJ are always available at http://mpxj.sf.net, however if you wish to build a local copy for yourself, follow the instructions above to build the MPXJ JAR, then at the command prompt enter the command "ant document", which will then generate the Javadoc in the doc/api folder.

Generating the JAXB code

In order to read and write various XML file formats, MPXJ relies on code generated by the JAXB tool xjc from the XML schemas. Normally you will not need to regenerate this source, but if you are changing the JAXB implementation, or modifying the use of JAXB in some way, then you may need to regenerate this code. The following notes detail where the XML schemas used by MPXJ can be obtained:

  • Microsoft Project MSPDI: The XML schema file from which the JAXB code has been generated is supplied by Microsoft as part of the Microsoft Project SDK, which can be downloaded from MSDN.
  • Planner: The XML schema file for Planner is distributed with MPXJ in the JAXB subdirectory
  • Primavera PM XML: The XML schema file for PM XML is distributed as part of the Primavera media. The relevant archive can be downloaded from the Oracle E-Delivery web site,

If you obtain a copy of the XML schema file you want to work with, you can update the JAXB source using the xjc target found in the ant build.xml file. Note that the xjc target is platform specific, you will need to change the name of xjc tool to be xjc.bat, xjc.exe, or xjc.sh depending on your operating system. You will also need to set the properties indicated in build.xml to tell it where to find xjc and the XML schema file. If you are only regenerating source for one of the XML schemas, you can comment out the others in the Ant script to avoid unnecessary work.