About-maven-plugin

From Evgeny Goldin

Jump to: navigation, search

Contents

Introduction

"about-maven-plugin" adds textual "about" file to build artifacts created, linking each binary artifact to the build environment and sources it was created with.

The file added contains details about build date and time, last commit made in the project, Java / Maven versions used for the build and other optional elements like project dependencies, local paths, Maven, system and environment variables. If the project was built by Jenkins, TeamCity or Hudson build server then corresponding job details are also added to the file generated.

For example, this jar file contains the following data in "about~com.github.goldin~about-maven-plugin~0.2.4.txt":

 Created with http://evgeny-goldin.com/wiki/about-maven-plugin, version "0.2.3.8"
===============================================================================
 TeamCity Info
===============================================================================
 Server         : [http://evgeny-goldin.org/teamcity/]
 Job            : [http://evgeny-goldin.org/teamcity/viewLog.html?buildId=6194]
 Log            : [http://evgeny-goldin.org/teamcity/viewLog.html?buildId=6194&tab=buildLog]
 Server Version : [7.1 (build 23265)]
 Project        : [maven-plugins]
 Configuration  : [Build, Deploy]
 Build Number   : [857]
===============================================================================
 Git Info
===============================================================================
 Repositories   : [origin	git@github.com:evgeny-goldin/maven-plugins.git (fetch)
                   origin	git@github.com:evgeny-goldin/maven-plugins.git (push)]
 Branch         : [master]
 Git Status     : [# On branch master
                   nothing to commit (working directory clean)]
 Commit         : [eb8f3cd][eb8f3cd689921d25571d480be2fb065a4ef3fa79]
 Commit Date    : [Thu, 10 May 2012 22:24:03 +0200]
 Commit Author  : [Evgeny Goldin <evgenyg@gmail.com>]
 Commit Message : [<version>0.2.4</version>
                   <gcommons-version>0.5.4</gcommons-version>]
===============================================================================
 Build Info
===============================================================================
 Host           : [evgeny-goldin.org]
 Build Time     : Started         - [10 May, Thursday, 2012, 23:42:11 (Israel Daylight Time:GMT+0300)]
 Build Time     : "About" created - [10 May, Thursday, 2012, 23:43:17 (Israel Daylight Time:GMT+0300)]
 User           : [evgenyg]
 Java           : [1.6.0_30][Sun Microsystems Inc.][Java HotSpot(TM) 64-Bit Server VM]
 OS             : [Linux][amd64][2.6.35-32-server]
===============================================================================
 Maven Info
===============================================================================
 MAVEN_OPTS     : [-Xmx512m -XX:MaxPermSize=256m]
 Version        : [3.0.4]
 Project        : [MavenProject: com.github.goldin:about-maven-plugin:0.2.4]
 Goals          : [clean, source:jar, install]
 Name           : [com.github.goldin:about-maven-plugin:0.2.4]
 Coordinates    : [com.github.goldin:about-maven-plugin:0.2.4]
 Dependencies   : [com.github.goldin:about-maven-plugin:maven-plugin:0.2.4
                   +- com.github.goldin:maven-common:jar:0.2.4:compile
                   |  +- org.apache.maven:maven-core:jar:3.0.4:compile
                   |  |  +- org.apache.maven:maven-settings:jar:3.0.4:compile
                   |  |  +- org.apache.maven:maven-settings-builder:jar:3.0.4:compile
                   ...
                   |  +- org.sonatype.sisu:sisu-inject-bean:jar:2.3.0:compile
                   |  +- org.jfrog.maven.annomojo:maven-plugin-anno:jar:1.4.1:compile
                   |  \- com.jcraft:jsch:jar:0.1.48:compile
                   \- junit:junit:jar:4.10:compile]
===============================================================================
 Maven Properties
===============================================================================
 [aether-version]          :[1.13.1]
 [annomojo-version]        :[1.4.1]
 [ant-version]             :[1.8.3]
 [gcommons-version]        :[0.5.4]
 [gcontracts-version]      :[1.2.5]
 [gmaven-version]          :[1.4]
 [groovy-version]          :[1.8.6]
 [java-version]            :[1.6]
 [junit-version]           :[4.10]
 [maven-version]           :[3.0.4]
 [previous-plugins-version]:[0.2.3.8]
 [spring-batch-version]    :[2.1.8.RELEASE]
 [spring-version]          :[3.1.1.RELEASE]
===============================================================================


This file was created by providing the second example from the following section.


Examples

Updating existing archives

First example configures the plugin to add an "about" file to "META-INF" of all "*.jar" and "*.zip" archives found in "${project.build.directory}". The following data will be stored in it:

  • SCM details: last Git commit / SVN revision, its message and author.
  • Local build paths.
  • Maven properties.
  • Maven dependencies.
  • System properties.
  • Environment variables.

The plugin is also configured not to fail if any error occurs or no archive files are found.

<plugin>
    <groupId>com.github.goldin</groupId>
    <artifactId>about-maven-plugin</artifactId>
    <version>0.2.5</version>
    <executions>
        <execution>
            <id>create-about</id>
            <goals>
                <goal>create-about</goal>
            </goals>
            <phase>verify</phase>
            <configuration>
                <include>*.jar, *.zip</include>
                <dumpSCM>true</dumpSCM>
                <dumpPaths>true</dumpPaths>
                <dumpMaven>true</dumpMaven>
                <dumpDependencies>true</dumpDependencies>
                <dumpSystem>true</dumpSystem>
                <dumpEnv>true</dumpEnv>
                <failOnError>false</failOnError>
                <failIfNotFound>false</failIfNotFound>
            </configuration>
        </execution>
    </executions>
</plugin>


Creating "about" files in a predefined location without updating any archives

It is possible not to update existing archives, which may be time-consuming. You can instruct the plugin to merely create "about" files in a predefined location so they're archived together with the rest of your data. The second example below shows one such configuration - the plugin only runs if "${project.build.outputDirectory}" directory exists and it creates the "about" file in "${project.build.outputDirectory}" so it'll be packed together with any project artifacts. It dumps Maven properties and dependencies but doesn't dump system properties, environment variables or any local paths for security reasons. In fact, that's exactly how "about" files are added to all my Maven plugins.


<plugin>
    <groupId>com.github.goldin</groupId>
    <artifactId>about-maven-plugin</artifactId>
    <version>0.2.5</version>
    <executions>
        <execution>
            <id>copy-about</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>create-about</goal>
            </goals>
            <configuration>
                <runIf>{{ new File( project.build.outputDirectory ).directory }}</runIf>
                <dumpDependencies>true</dumpDependencies>
                <dumpMaven>true</dumpMaven>
                <fileName>${project.build.outputDirectory}/about~${project.groupId}~${project.artifactId}~${project.version}.txt</fileName>
                <updateArchives>false</updateArchives>
            </configuration>
        </execution>
    </executions>
</plugin>


Details

Provided By
Mailing List Nabble
Source Code GitHub
License
Tests GitHub
GroovyDoc <groovydoc>
Issue Tracker YouTrack
Build Server Maven
TeamCity
Maven Coordinates
  • com.github.goldin:about-maven-plugin:0.2.5
Goal
  • create-about
Default Phase
  • package
Maven Repository Artifactory Online


<configuration>

Name Default value Description
<runIf> Controls whether or not plugin should be executed, accepts a Groovy expression.
<updateArchives> "true" Controls whether or not plugin should update an existing archives or just create the "about" file.
<prefix> "META-INF" Archive directory where "about" file is created. Use "<prefix>/</prefix>" if "about" file should be added to archive's root.
<fileName> "about-${project.groupId}-${project.artifactId}-${project.version}.txt" Name of the file created.
  • If "<updateArchives>" is "true" (default value) then "about" file is added as "<prefix>/<fileName>" to every archive.
  • If "<updateArchives>" is "false" then "about" file is created as:
    • "${project.build.outputDirectory}/<fileName>" if it's a relative path
    • "<fileName>" if it's an absolute path
<dumpSCM> "true" Whether SCM details should be added to "about" file.
  • Git and SVN systems are recognized automatically but their command-line clients are expected to be installed on a build machine (this will be changed in future versions).
  • Make sure the corresponding ".git" and ".svn" folders are available when your project is built.
    In TeamCity it requires "VCS checkout mode" to be "Automatically on agent" in "Version Control Settings".
<dumpMaven> "false" Whether Maven properties should be added to "about" file.
<dumpEnv> "false" Whether environment variables should be added to "about" file.
<dumpSystem> "false" Whether Java system properties should be added to "about" file.
<dumpPaths> "false" Whether various build paths (Maven home, build directory, etc) should be added to "about" file.
<dumpDependencies> "false" Whether project transitive dependencies, result of running "mvn dependency:tree", should be added to "about" file.
<addContent> Arbitrary content to add to "about" file, Groovy expression is supported.
<endOfLine> "windows" If "windows" - end of line in the file created is "\r\n". For any other value it is "\n".
<directory> "${project.build.directory}" Directory where archives to update are located.
<include> "*.jar" Comma-separated list of archive patterns to update.
<exclude> Comma-separated list of archive patterns to exclude from update.
<failOnError> "true" Whether build execution should fail if plugin execution fails for any reason.

You may want to specify "false" if build stability is of high importance (in other words, you don't care if anything went wrong with "about" file as long as the build keeps running).

<failIfNotFound> "true" Whether build execution should fail if no archives were found in "<directory>" matching the "<include>" pattern.
Personal tools