Building ANTLR 4 with Maven

Sam Harwell - Dec. 23, 2012

Several phases of the Maven build exist for preparing proper releases. Each of the following variables must be configured or explicitly overridden/ignored.

1. Initial Setup

Before the first time Maven is used to build ANTLR 4 from source, the following command should be executed in the top-level directory of the source tree.

mvn -N install

2. Quick Start Examples

Each of these examples is written as a "quick start" case, and assumes the following:

• You are building only the minimal set of artifacts required for using ANTLR 4 (i.e. not using the release profile described below)
• You are building the project with Maven 3+ and JDK 6+

2.1. For All Platforms

mvn -Duser.name="Your Name" -DskipTests=true install

3. Unit Test Configuration

3.1. Skipping Unit Tests

Unit tests may be skipped by passing the following flag to Maven. Note that the unit test classes are still compiled when this flag is specified.

-DskipTests=true

3.2. JDK_SOURCE_ROOT for TestPerformance

One of the unit tests (TestPerformance) requires configuring the JDK_SOURCE_ROOT for Maven. You should extract the contents of src.zip included in the JDK distribution of Java 6, and pass the following flag to Maven. The JDK_SOURCE_ROOT folder should contain the subfolder java/lang with the Java files for the Java 6 package java.lang.

-DJDK_SOURCE_ROOT=/path/to/jdk_src

3.3. In-Process Testing

The following flag configures the unit tests to execute in-process (via a new ClassLoader) rather than creating new Java processes. This results in a 50+% reduction in the time it takes to execute the unit tests, and allows for fully-functional debugging for all of the unit tests (normally code executed in the forked Java processes cannot be debugged directly).

-Dantlr4.testinprocess=true

4. Complete Build (Release Profile)

To improve development time while working on ANTLR 4, by default Maven builds only the minimal set of Jar files necessary for using ANTLR 4. By passing -Psonatype-oss-release to Maven, the complete set of files are built. However, this configuration requires additional configuration as shown in the subsections below. The following table summarizes the files built with and without this option.

-Psonatype-oss-release

4.1. GraphViz for Generated Diagrams

The release profile uses GraphViz to generate SVG graphics from dot files for the generated Javadocs. The dot executable should be in your system path for this. Windows users can simply use the Windows installer for GraphViz 2.28 or newer and the path will be automatically configured.

4.2. Artifact Signing (GPG)

By default Maven will sign the build artifacts with GPG, and assumes you have your system configured according to Sonatype's Blog entry "How to Generate PGP Signatures with Maven". One of the following should be used each time Maven is used to build the project.

1. Skip the phase by passing -Dgpg.skip=true to Maven (required for users without GPG installed or configured).
2. Configure the GPG passphrase by passing -Dgpg.passphrase=passphrase to Maven (or simply -Dgpg.passphrase if your private key does not require a passphrase).
3. Run the Maven build without specifying one of the above, in which case signing will be enabled and Maven will ask you to enter the passphrase during the signing phase.

4.3. Bootstrap Classpath

The release profile is configured to pass the -bootclasspath option to javac to ensure that the compiled artifacts and test suites will run with Java 6, even when compiled with Java 7.

Maven needs the path to a copy of rt.jar (Windows, Linux) or Classes.jar (OSX) from Java 6. This may be configured by any of the following methods:

1. (Windows, Linux) Set the JAVA6_HOME environment variable to the home folder of a Java 6 runtime installation. When using this option, the library rt.jar should be available in %JAVA6_HOME%\lib\rt.jar (Windows) or $JAVA6_HOME/lib/rt.jar (Linux).
2. (Windows, Linux) Pass the option -Djava6.home=path to Maven. The path should be in the same form as listed for the JAVA6_HOME enviroment variable, and takes precedence over the environment variable if both are specified.
3. (Windows, Linux, OSX) Pass the option -Dbootclasspath.java6=path to Maven. This should be the full path to rt.jar (Windows, Linux) or Classes.jar (OSX).
4. For users without a copy of Java 6 installed, the Java 6 validation may be skipped by passing the option  -Dbootclasspath.compile=path -Dbootclasspath.testCompile=path to Maven. This should be the full path to rt.jar (Windows, Linux) or Classes.jar (OSX) for some version of Java newer than Java 6.

4.4. Additional Build Options

These options are not required for building ANTLR 3, but can be useful in certain scenarios. This is not a complete list of options which affect the build, but should include the most commonly used (or "interesting") options.