Apache Commons – Building Apache Commons Components
Introduction
This document provides information on setting up and executing builds for Apache Commons components and web sites. The contents include best practices and conventions that Commons components should follow. This information should be useful to committers setting up new components as well as to volunteers who want to build Commons components or web sites from source or to contribute patches to the build artifacts.
The assumption throughout is that we are working with a component named "Apache Commons Foo" that uses Maven as its build system, both for distribution binaries and for the web site.
Some knowledge of Maven is assumed in this document. Please refer to the Maven user guide for more information. Commons components now use version 3 of Maven, so this is the Maven version assumed throughout this document.
Commons Parent POM
Commons componenents share a common parent POM. This contains common setup to reduce the setup needed in each component POM and standardizes the builds across Commons components.
Local environment setup
To build Apache Commons components or web sites, you need to have Maven installed and the project source files checked out locally.
Getting and installing Maven
Follow the Maven download instructions to download and install Maven.
Checking out the Commons sources
Follow the
Commons subversion instructions to check out the Commons source
files. If you want to build Commons component web sites, you need to have
the commons-build module checked out as a peer to whatever
component(s) you are trying to generate the site for. If you check out
the full set of "trunks" using the svn externals "trunks-proper" or
"trunks-sandbox" this will happen automatically.
Configuring local properties
If you regularly want to build Commons components using a different version of Java
than that used to run Maven, you may wish to define the locations of the alternate
JDKs in the Maven settings.xml file.
See testing with different Java versions
for more details.
Alternatively, you can provide the location of the alternate JDK as a property on the Maven command-line, see below.
Maven Commands
Compile and test with a specific JDK
To compile and run a component's tests with JDK 1.5.
This assumes that the property JAVA_1_5_HOME has been defined in the Maven settings.xml
or has been defined as an OS environment variable (if both are defined, settings.xml takes precedence)
mvn clean test -Pjava-1.5
To compile (only) source and test files with Java 1.6 if settings.xml does not contain the property definitions (note this overrides any definition in settings.xml):
mvn [clean] test-compile -Pjava-1.6 -DJAVA_1_6_HOME=path-to-jdk-home
Running the Tests
To run a component's tests:
Creating a jar file
To create a component's jar:
Installing
To install a component in your local repository:
Source and binary distributions
To create the source and binary distributions for a component (and the javadoc and sources jars):
Generating the Site
To generate a components site: