|
commons-parent
This page provides information about the
commons-parent
Commons components use Maven as their primary build system and commons-parent is the parent pom for the components' Maven build. Using a parent pom reduces the build configuration required for each individual component and standardizes the builds across Commons components. BuildThe following is a list of the main build features provided by commons-parent:
ReleaseThe following is a list of the main release features provided by commons-parent through the release profile.
Additionally the RAT (release audit) report is automatically produced when generating a component's site. The RAT report checks the source files for appropriate License Headers. Commons Release Plugin. By default in the parent, the commons-release-plugin is disabled as to not stop folks' release practices. That said, for people interested in configuring the newly released (April 2018) release plugin, one needs to configure the following properties, for single module builds:
<properties>
<commons.release.isDistModule>true</commons.release.isDistModule>
<commons.distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo</commons.distSvnStagingUrl>
</properties>foo represents our component. Furthermore, during a release build, we ask that the svn
folder be empty. We then generate our release build by runnning:
mvn -Duser.name=${my_apache_id} -Prelease -Ptest-deploy clean package site deploytarget/commons-release-plugin/scm. And, to perform a full release, we run:
mvn -Duser.name=${my_apache_id} -Prelease clean package site deployRELEASE-NOTES.txt from the
root of the project.
Site GenerationThe following is a list of the main site features provided by commons-parent:
Java VersionConfiguring the Java Source/Target options
commons-parent
configures the
So, for example, to configure a component to have source/target set to 1.4 add the following
lines to the component's
<properties>
<maven.compiler.source>1.4</maven.compiler.source>
<maven.compiler.target>1.4</maven.compiler.target>
</properties>
${maven.compiler.source} and ${maven.compiler.target}; however the
Commons Parent POM originally incorrectly used ".compile." rather than ".compiler."
This was fixed in version 31 of the Commons Parent pom.
See https://issues.apache.org/jira/browse/COMMONSSITE-69
MANIFEST.MF
In order to help check what source/target options were used when building a release, the property values used to
configure the source/target options in the
maven-compiler-plugin
(i.e.
X-Compile-Source-JDK:
X-Compile-Target-JDK:
Testing with different Java versions
Using the target option ensures that the However, it may be that one or more Maven plugins require a later version of Java than the component. For this reason commons-parent provides profiles for compiling/testing under different Java versions (correct as of version 36):
In order for these profiles to work, you need to configure the relevant
Note: the maven-bundle-plugin
outputs all property values which start with a capital letter as headers to the jar's
To ensure that the properties are only present if they are actually needed, you can
define the property in the relevant profile in your
<settings>
<profiles>
<!-- Sample profiles showing different ways of defining the properties -->
<profile>
<id>java-1.5</id>
<properties>
<!-- sample Windows definition -->
<JAVA_1_5_HOME>C:\jdk1.5.0_22</JAVA_1_5_HOME>
</properties>
</profile>
<profile>
<id>java-1.6</id>
<properties>
<!-- Sample Unix definition -->
<JAVA_1_6_HOME>/home/jenkins/tools/java/latest1.6</JAVA_1_6_HOME>
</properties>
</profile>
<profile>
<id>java-1.7</id>
<properties>
<!-- sample definition using an OS environment variable -->
<JAVA_1_7_HOME>${env.JAVA_1_7_HOME}</JAVA_1_7_HOME>
</properties>
</profile>
<!-- No need to define every possible java profile, only the ones you want to use (and have JDKs for) -->
</profiles>
</settings>
An alternative is to define the home directories as OS environment variables. For example:
JAVA_1_8_HOME=$(/usr/libexec/java_home -v 1.8) # MacOS only
JAVA_1_8_HOME=/path/to/java8/home # Other Unix OSes
export JAVA_1_8_HOME
Once you have configured settings.xml or defined the OS variables you can, for example, compile and test with Java 1.6 using the following command:
mvn clean test -Pjava-1.6
You can also provide the appropriate property definition on the command-line. (However for frequent use it is easier to update the settings file or ensure the OS defines the appropriate variables) This overrides any property setting in the settings.xml file, which in turn overrides the OS environment variable. For example:
mvn clean test -Pjava-1.6 -DJAVA_1_6_HOME=/home/jenkins/tools/java/latest1.6
OSGi InformationOSGi Metadata
In order to use a Commons component (or any libaray) in an
OSGi container (for example
Apache Felix) then OSGi
metadata needs to be included in the Generating the OSGi Metadata
commons-parent
is configured to automatically add the OSGi metadata to the component jar's mvn package
Most components only need to configure the
<properties>
<commons.componentid>beanutils</commons.componentid>
</properties>
Custom OSGi configuration
There are a number of other OSGi properties in the commons-parent
PropertiesThe parent pom defines many properties. These provide the defaults for various aspects of the pom configuration. In most cases, the defaults are the best choice, but in some cases it may be necessary to override the value of a property - for example if a new version of a plugin has been released, and the parent POM has not yet been updated. Overriding propertiesProperties defined in the parent POM can be overriden on the command line, for example: mvn apache-rat:rat -Dcommons.rat.version=0.11 Version propertiesMost of the plugin versions defined in the parent POM are defined using properties. For example, commons.rat.version defines the version of Apache RAT. Please see the POM for the list. [The properties are currently located at the end of the POM.] Configuration propertiesThere are some properties which control the behavior of the plugins, for example:
ProfilesJava profilescommons-parent contains some java profiles to compile/test using different versions of Java. See here for details of using the Java profiles. jacoco profile
Enable this profile to run the Jacoco tool.
This requires at least Java 1.5.
The profile is not enabled by default.
If the file cobertura profile
Enable this profile to run the Cobertura tool.
The profile is not enabled by default.
If the file japicmp profile (since CP41)
Enable this profile to run the japicmp cmp goal during the verify phase.
If any change breaks source compatibilty, this will fail the build.
This profile will also generate a source compatibilty report during the site lifecycle.
This plugin requires building with at least Java 1.7. (source and target can be lower versions)
The profile is not enabled by default.
If the file clirr profile (since CP41)
Enable this profile to generate the clirr report during the site lifecycle.
The profile is not enabled by default.
If the file site-basic profile (since CP37)This profile disables as many of the optional reports as it can. It is intended for quickly checking the component documentation. The following properties are defined:
<skipTests>true</skipTests>
<maven.javadoc.skip>true</maven.javadoc.skip>
<cobertura.skip>true</cobertura.skip>
<findbugs.skip>true</findbugs.skip>
<checkstyle.skip>true</checkstyle.skip>
<clirr.skip>true</clirr.skip>
<changes.jira.skip>true</changes.jira.skip>
<rat.skip>true</rat.skip> <!-- from version 0.12 -->
<jacoco.skip>true</jacoco.skip>
<skipSurefireReport>true</skipSurefireReport>
Individual reports can be re-enabled as follows:
animal-sniffer profile (since CP37)This profile is enabled by default. It runs the Animal Sniffer plugin on the main code during the "process-classes" phase. The main code base is checked against the API signature for the compiler target version. Restrictions: does not currently check test code; may not find all invalid API usage. The code still needs to be built and tested with the target compiler version before a release. However it should provide an early warning to developers using a more recent version of Java.
The plugin can be temporarily disabled by using the command-line option
The profile creates the property
A simple way to run the check is as follows release profile
commons-parent
contains a Running the following command will, in addition to creating the jar as normal, will also:
mvn -Prelease package
You can also combine the release-notes profile
This uses the mvn changes:announcement-generate -Prelease-notes [-Dchanges.version=nnn] Defining changes.version allows one to create the RN without first removing the SNAPSHOT suffix from the POM. javasvn profileOptional profile to use javasvn instead of the SVN CLI for the buildNumber plugin Other profiles, not intended for direct useThe pom also includes some helper profiles that are automatically enabled as needed
|