buildmetadata-maven-plugin

POM Configuration Collector

Use the following to add the plugin to your POM to collect the build information:

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>buildmetadata-maven-plugin</artifactId>
  <version>1.7.0</version>
  <executions>
    <execution>
      <phase>initialize</phase>
      <goals>
        <goal>provide-buildmetadata</goal>
      </goals>
    </execution>
  </executions>
</plugin>

If you are using Git, you may want to add the remoteVersion to compare with. In the following example we compare to origin/master:

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>buildmetadata-maven-plugin</artifactId>
  <version>1.7.0</version>
  <executions>
    <execution>
      <phase>initialize</phase>
      <goals>
        <goal>provide-buildmetadata</goal>
      </goals>
      <configuration>
        <remoteVersion>origin/master</remoteVersion>
      </configuration>
    </execution>
  </executions>
</plugin>

Please refer to Accessing Artifacts on information to download the plugin.

The file buildmetadata.properties is written to the META-INF folder by default. You may change the by changing the destination of the propertiesOutputFile property.

For multi projects it is especially useful to map the output file to packaging types. This is done by (following is the default configuration if it is not specified):

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>buildmetadata-maven-plugin</artifactId>
  <version>1.7.0</version>
  <configuration>
    <addProjectInfo>true</addProjectInfo>
    <propertyOutputFileMapping>
      <fileMapping>
        <packaging>war</packaging>
        <outputFile>${project.build.directory}/buildmetadata-maven-plugin-1.7.0/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>ear</packaging>
        <outputFile>${project.build.directory}/buildmetadata-maven-plugin-1.7.0/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>sar</packaging>
        <outputFile>${project.build.directory}/buildmetadata-maven-plugin-1.7.0/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>rar</packaging>
        <outputFile>${project.build.directory}/buildmetadata-maven-plugin-1.7.0/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>par</packaging>
        <outputFile>${project.build.directory}/buildmetadata-maven-plugin-1.7.0/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>atlassian-plugin</packaging>
        <outputFile>${project.build.outputDirectory}/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>jar</packaging>
        <outputFile>${project.build.outputDirectory}/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>ejb</packaging>
        <outputFile>${project.build.outputDirectory}/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>maven-archetype</packaging>
        <outputFile>${project.build.outputDirectory}/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>maven-plugin</packaging>
        <outputFile>${project.build.outputDirectory}/META-INF/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>eclipse-plugin</packaging>
        <outputFile>${project.build.directory}/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>eclipse-feature</packaging>
        <outputFile>${project.build.directory}/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>eclipse-repository</packaging>
        <outputFile>${project.build.directory}/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>eclipse-update-site</packaging>
        <outputFile>${project.build.directory}/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>targetplatform</packaging>
        <outputFile>${project.build.directory}/build.properties</outputFile>
      </fileMapping>
      <fileMapping>
        <packaging>pom</packaging>
        <outputFile>${project.build.directory}/build.properties</outputFile>
      </fileMapping>
    </propertyOutputFileMapping>
  </configuration>
</plugin>

Packaging types not specified here default to propertiesOutputFile.

If you want to disable the propertyOutputFileMapping, set activatePropertyOutputFileMapping to false.

XML report

The properties file with the build metadata is short and easy to parse. But if you want to process the information to feed other processes, an XML format is more convenient.

The file is created per default in the target folder of your project. The properties file is created per default in the META-INF folder and therefore included in the artifact (if the artifact is an archive and contains a META-INF folder).

If you want to replace the properties file with the XML file, use the following configuration:

<plugin>
  <groupId>de.smartics.maven.plugin</groupId>
  <artifactId>buildmetadata-maven-plugin</artifactId>
  <version>1.7.0</version>
  <executions>
    <execution>
      <phase>initialize</phase>
      <goals>
        <goal>provide-buildmetadata</goal>
      </goals>
      <configuration>
        <createPropertiesReport>false</createPropertiesReport>
        <xmlOutputFile>${project.build.outputDirectory}/META-INF/buildmetadata.xml</xmlOutputFile>
      </configuration>
    </execution>
  </executions>
</plugin>

The XSDs for the generated XML file are part of the buildmetadata doctype.

Here is an example of SNAPSHOT build of the smartics-commons project:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<buildmetadata xmlns="http://www.smartics.de/project/process/implementation/buildmetadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.smartics.de/project/process/implementation/buildmetadata http://www.smartics.de/project/process/implementation/buildmetadata">
  <name>0.5.3-20131003r15895-locally-modified-SNAPSHOT</name>
  <version>0.5.3-SNAPSHOT</version>
  <groupId>de.smartics.util</groupId>
  <artifactId>smartics-commons</artifactId>
  <date>2013-10-03T15:46:26</date>
  <timestamp>1380807986504</timestamp>
  <build-year>2013</build-year>
  <copyright-year>2011-2013</copyright-year>
  <scm>
    <revision>15895</revision>
    <revision-date>2013-09-21T20:39:41</revision-date>
    <url>scm:svn:https://www.smartics.eu/svn/public/util/trunk/smartics-commons</url>
    <locally-modified-files>
      <file modtype="modified">pom.xml</file>
    </locally-modified-files>
  </scm>
  <runtime>
    <build-server>Midgard</build-server>
    <build-user>robert.reiner</build-user>
    <os>
      <arch>amd64</arch>
      <name>Windows 7</name>
      <version>6.1</version>
    </os>
    <java>
      <name>Java(TM) SE Runtime Environment</name>
      <version>1.6.0_25-b06</version>
      <vendor>Sun Microsystems Inc.</vendor>
      <vm>Java HotSpot(TM) 64-Bit Server VM</vm>
      <compiler>HotSpot 64-Bit Tiered Compilers</compiler>
    </java>
    <maven>
      <version>3.0.5</version>
      <execution-project>de.smartics.util:smartics-commons:jar:0.5.3-SNAPSHOT</execution-project>
      <is-excution-root>true</is-excution-root>
      <goals>
        <goal>clean</goal>
        <goal>package</goal>
      </goals>
      <filters/>
      <profiles>
        <profile source="settings.xml">nexus</profile>
        <profile source="settings.xml">smartics</profile>
      </profiles>
    </maven>
  </runtime>
  <misc>
    <metadata name="build.date.pattern">dd.MM.yyyy HH:mm:ss</metadata>
    <metadata name="build.scmLocallyModified">true</metadata>
  </misc>
</buildmetadata>

Use with JAR plugin

To use the build information with the JAR plugin that writes it to the manifest file, you may use the following code:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <version>2.3.1</version>
  <configuration>
    <archive>
      <manifest>
        <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
        <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
      </manifest>
      <manifestEntries>
        <Implementation-SCM-Revision-Number>${build.scmRevision.id}</Implementation-SCM-Revision-Number>
        <Implementation-SCM-Revision-Date>${build.scmRevision.date}</Implementation-SCM-Revision-Date>
        <Implementation-URL>https://www.smartics.eu/de.smartics.maven.plugin/buildmetadata-maven-plugin/1.7.0</Implementation-URL>
        <Implementation-Date>${build.date}</Implementation-Date>
        <Implementation-Timestamp>${build.timestamp.millis}</Implementation-Timestamp>
        <Implementation-DatePattern>${build.date.pattern}</Implementation-DatePattern>
        <Implementation-Full-Version>${build.version.full}</Implementation-Full-Version>
        <Built-Host>${build.host.name}</Built-Host>
        <Built-OS>${os.name} / ${os.arch} / ${os.version}</Built-OS>
        <Built-By>${build.user}</Built-By>
        <Maven-Version>${build.maven.version}</Maven-Version>
        <Java-Version>${java.version}</Java-Version>
        <Java-Vendor>${java.vendor}</Java-Vendor>
      </manifestEntries>
    </archive>
  </configuration>
</plugin>

We add the build date pattern here to be able to parse the date found in the manifest to present it localized to the user. But typically it is easier and faster to use the timestamp that is added as build.timestamp.millis.

The same holds true for other archiver like the ear and war plugin.

POM Configuration Report

Use the following to add the plugin as a report to your POM:

<reporting>
  <plugins>
    ...
    <plugin>
      <groupId>de.smartics.maven.plugin</groupId>
      <artifactId>buildmetadata-maven-plugin</artifactId>
      <version>1.7.0</version>
    </plugin>
  </plugins>
</reporting>

Control generated Information

Some properties let you control the information that is generated and added as a property to the build environment.

Since the command line, MAVEN_OPTS, and JAVA_OPTS may contain sensitive information (e.g. a password passed to a plugin), this information is hidden by default by the properties

Set the hideXXX property to false to add the corresponding values to the build metadata properties.

Copy Property to Build Properties

In case you want to copy a system property, an environment variable, or a Maven property to the build properties, use the properties element within the plugin's configuration.

The following property information may be provided:

Name	Description
name	The name of the system property or environment variable to copy. First the value is checked to be found as a system property, then as an environment variable. The fact that no value is found at either place is silently ignored.
mappedName	The name of the property to be used in the build meta data properties. This allows to change the name of the property.
value	The value provided for the property. No lookup is performed. Standard Maven properties are resolved.
section	Binds the property to be displayed in the given section. This value is only relevant for reports. This value is optional and if not given or invalid, the property is displayed with the misc section. The following values are allowed: `build.scm` - source code management information. `build.dateAndVersion` - information about build date and artifact version. `build.runtime` - information about the build runtime. `build.java` - information about the Java runtime running the build. `build.maven` - information about the Maven runtime running the build. `project` - information about the project or product. `build.misc` - miscellaneous build information (catch all category).
label	An optional label to be displayed instead of the name of the property.

The following example illustrates the usage:

<properties>
  <property>
    <name>user.home</name>
    <section>build.runtime</section>
  </property>
</properties>

The user.home property is associated with the runtime section. Since no label is given the value will be displayed with the property name as key.

<properties>
  <property>
    <name>unknown</name>
    <section>build.java</section>
  </property>
</properties>

The unknown property will not be found as a system property or environment variable and is therefore silently ignored.

<properties>
  <property>
    <name>file.separator</name>
    <section>build.invalid</section>
    <label>Separator for Files</label>
  </property>
</properties>

The file.separator property has a label of "Separator for Files" that is rendered as a key instead of the property name. Since the section is invalid, the property will be displayed with the misc section.

<properties>
  <property>
    <name>java.vendor.url</name>
    <section>build.java</section>
    <label>Vendor-URL</label>
  </property>
</properties>

The java.vendor.url will be displayed in the Java section with the label "Vendor-URL". If the value is an URL starting with http:// or https://, it is rendered as a link.

<properties>
  <property>
    <name>PATH</name>
  </property>
</properties>

This declaration copies the operating system environment variable PATH with no label to the misc section.

<properties>
  <property>
    <name>project.url</name>
    <mappedName>project.homepage</mappedName>
    <label>Project Homepage</label>
  </property>
</properties>

The URL of the project specified in the POM is copied to the build properties by the name project.homepage instead of project.url.

<properties>
  <property>
    <name>ohlohProjectId</name>
    <mappedName>project.id.ohloh</mappedName>
    <label>Ohloh</label>
  </property>
</properties>

Suppose the property ohlohProjectId is definied in the properties section of the POM. The example above copies the value to the build properties by the name project.id.ohloh instead of ohlohProjectId..

<properties>
  <property>
    <name>project.my.property</name>
  </property>
</properties>

Normally, if the property starts with project. it is assumed that the property is found in the POM like in project.version (which fetches the version of the project from the POM). If the property is not a property of the POM, it is looked up in the properties section. The example above will find the property project.my.property there.

<properties>
  <property>
    <name>project.coordinates</name>
    <value>${project.groupId}:${project.artifactId}:${project.version}</value>
    <label>Coordinates</label>
  </property>
</properties>

Normally, if the property starts with project. it is assumed that the property is found in the POM like in project.version (which fetches the version of the project from the POM). If the property is not a property of the POM, it is looked up in the properties section. The example above will find the property project.my.property there.

Please note that properties specified in the settings.xml or in activated profiles are considered due to Maven's property resolution.

Custom Build Meta Data Providers

To create your own build meta data provider, please refer to the provider documentation.

Control full Version String

Some properties let you control the construction of the full version string. The full version string has per default for instance the following form:

1.0.0-20100829r9217-locally-modified-SNAPSHOT

Validating checked out Sources

Building from locally modified sources the generated artifact cannot be tracked back to a given revision in the SCM.

If you want to fail the build on locally modified resources, use the property failOnLocalModifications set to true.

If you want to allow locally modified builds, use the property validateCheckout set to true (the default). This will provide the names of the changed files to the build properties.

#Created by buildmetadata-maven-plugin.build.date=17.07.2010 19\:13\:00
...

build.version=0.7.0-SNAPSHOT
build.version.full=0.7.0-20100717r8971-locally-modified-SNAPSHOT

...

build.scmLocallyModified=true
build.scmLocallyModified.files=[pom.xml\:modified]
...

Speeding up the Build

To speed up the build the file buildmetadata.properties is reused if it exists. If you want to force the retrieval of the information use the forceNewProperties property, which is set to false by default.

Set every add-information property for information not required to false, especially addScmInfo, and set validateCheckout to false, too.

Shortening the range of days for the changelog query (queryRangeInDays defaults to 30 days) may also speed up the build. Please refer to Revision Algorithm for details how the revision is calculated.

Per default an XML version of the buildmetadata properties file is generated. You may control the destination of the file by the property xmlOutputFile. In case you do not need the XML version, use the property createXmlReport to skip the generation.

Usage