|
commons-parent
This page provides information about the
commons-parent
pom.xml
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>
mvn -Duser.name=${my_apache_id} -Prelease -Ptest-deploy clean package site deploy
mvn -Duser.name=${my_apache_id} -Prelease clean package site deploySite GenerationThe following is a list of the main site features provided by commons-parent:
Java VersionConfiguring the Java Source/Target optionscommons-parent configures the source and target options in the maven-compiler-plugin to use the ${maven.compiler.source} and ${maven.compiler.target} properties respectively. So, for example, to configure a component to have source/target set to 1.4 add the following lines to the component's pom.xml:
<properties>
<maven.compiler.source>1.4</maven.compiler.source>
<maven.compiler.target>1.4</maven.compiler.target>
</properties>
MANIFEST.MFIn 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. ${maven.compiler.source} and ${maven.compiler.target}) are also written out to the component jar's MANIFEST.MF file with the following header names:
X-Compile-Source-JDK:
X-Compile-Target-JDK:
Testing with different Java versionsUsing the target option ensures that the .class file format is compatible with the required Java version - but it does not prevent/catch the use of methods/classes which were introduced in later Java versions (this is because the build will use the current Java libraries by default). One way to ensure that components don't accidentally use classes/methods from a later version of Java is to compile and test using the actual target Java version. 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 JAVA_1_N_HOME properties in your settings.xml file. [There is no need to configure properties for profiles you don't need.] Each property should be set to the directory where the relevant version of the JDK is installed. Note: the Maven compiler plugin has documentation on how this works. Note: the maven-bundle-plugin outputs all property values which start with a capital letter as headers to the jar's MANIFEST.MF file. The commons-parent pom uses the <_removeheaders> instruction to suppress the specific JAVA_* properties used by the pom. 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.xml, for example:
<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 MetadataIn 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 MANIFEST.MF file of the component's jar. Generating the OSGi Metadatacommons-parent is configured to automatically add the OSGi metadata to the component jar's MANIFEST.MF using the maven-bundle-plugin when the package phase is executed: mvn package Most components only need to configure the <commons.componentid> property in their pom.xml in the following way:
<properties>
<commons.componentid>beanutils</commons.componentid>
</properties>
Custom OSGi configurationThere are a number of other OSGi properties in the commons-parent pom.xml which are used to configure the maven-bundle-plugin. These have sensible defaults, but can be overriden in a component's pom.xml if required. These are:
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 behaviour 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 profileEnable this profile to run the Jacoco tool. This requires at least Java 1.5. The profile is not enabled by default. If the file src/site/resources/profile.jacoco exists then the profile is enabled. This allows components to always enable the profile cobertura profileEnable this profile to run the Cobertura tool. The profile is not enabled by default. If the file src/site/resources/profile.cobertura exists then the profile is enabled. This allows components to always enable the profile 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 src/site/resources/profile.japicmp exists then the profile is enabled. This allows components to always enable the profile 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 src/site/resources/profile.clirr exists then the profile is enabled. This allows components to always enable the profile 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: mvn site -Psite-basic -Dclirr.skip=false 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 -Danimal.sniffer.skip. It can be completely disabled for a component (not recommended) by creating an empty file: src/site/resources/profile.noanimal The profile creates the property animal-sniffer.signature (e.g. java16) from the property maven.compiler.target (e.g. 1.6). For temporary testing purposes, the property animal-sniffer.signature can be overridden on the command-line. The configuration for the plugin defines the signature version using the property commons.animal-sniffer.signature.version. This is defined with the value of 1.0 as almost all signatures are released with that version. If necessary, the property can be overridden on the command line or in the component POM. [For example, the java16 signature comes in 2 versions]. The Codehaus website has documentation on the available signatures A simple way to run the check is as follows mvn process-classes release profilecommons-parent contains a release profile for producing releases. Running the following command will, in addition to creating the jar as normal, will also:
mvn -Prelease package You can also combine the -Prelease option with deploy target and the -Ptest-deploy profile to simulate staging to the repository. release-notes profileThis uses the src/changes.xml file to generate the file RELEASE-NOTES.txt. Requires file src/changes/release-notes.vm. A sample template is available from: https://svn.apache.org/repos/asf/commons/proper/commons-parent/trunk/src/changes/release-notes.vm 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. Other profiles, not intended for direct useThe pom also includes some helper profiles that are automatically enabled as needed
|