Gradle-about-plugin

From Evgeny Goldin

Jump to: navigation, search

Contents

Introduction

This 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 / Gradle versions used for build and some other optional elements like project dependencies, local paths, system and environment variables. If the project was built by TeamCity or Jenkins then corresponding job details are also added to the file generated.


Example

Plugin's jar contains the following "about.txt" file: 


 Generated by http://evgeny-goldin.com/wiki/Gradle-about-plugin, version [0.2.6]
===============================================================================
 TeamCity Info
===============================================================================
 Version        : [8.0 EAP (build 27147)]
 Server         : [http://evgeny-goldin.org/teamcity/]
 Job            : [http://evgeny-goldin.org/teamcity/viewLog.html?buildId=17566]
 Log            : [http://evgeny-goldin.org/teamcity/viewLog.html?buildId=17566&tab=buildLog]
 Project        : [gradle-plugins]
 Configuration  : [Release Deploy]
 Build Number   : [28]
 Personal Build : [false]
===============================================================================
 Git Info
===============================================================================
 Version        : [1.7.2.5]
 Repositories   : [origin	git://github.com/evgeny-goldin/gradle-plugins.git (fetch)
                   origin	git://github.com/evgeny-goldin/gradle-plugins.git (push)]
 Branch         : []
 Status         : [# Not currently on any branch.
                   nothing to commit (working directory clean)]
 Commit         : [30db2f3][30db2f3b284fefe7d04f63079f13c5d599bb0979]
 Commit Date    : [Sat, 4 May 2013 18:18:31 +0200]
 Commit Author  : [Evgeny Goldin <evgenyg@gmail.com>]
 Commit Message : [version=0.2.8]
===============================================================================
 Build Info
===============================================================================
 Host          : [evgeny-goldin.org]/[176.9.101.146]
 Time          : [04 May, Saturday, 2013, 18:23:25 (Central European Summer Time:GMT+0200)]
 User          : [evgenyg]
 Java          : [1.7.0_21][Oracle Corporation][Java HotSpot(TM) 64-Bit Server VM]
 OS            : [Linux][amd64][2.6.32-5-amd64]
===============================================================================
 Gradle Info
===============================================================================
 Version       : [1.6-rc-1]
 GRADLE_OPTS   : [-DgroovydocDir=/home/evgenyg/java/tomcat/webapps/groovydoc/gradle-plugins]
 Project       : [project ':about']
 Tasks         : [duplicates, clean, groovydocAll, build, artifactoryPublish]
 Coordinates   : [com.github.goldin.plugins.gradle:about:0.2.8]
 Dependencies  : [--------------------------------------------------------------------------------
                  compile - Compile classpath for source set 'main'.
                  +--- org.gcontracts:gcontracts-core:1.2.12
                  |    \--- org.ow2.asm:asm:4.0
                  +--- org.codehaus.gpars:gpars:1.0.0
                  |    \--- org.codehaus.jsr166-mirror:jsr166y:1.7.0
                  +--- com.fasterxml.jackson.core:jackson-databind:2.2.0
                  |    +--- com.fasterxml.jackson.core:jackson-annotations:2.2.0
                  |    \--- com.fasterxml.jackson.core:jackson-core:2.2.0
                  \--- com.github.goldin.plugins.gradle:common:0.2.8
                       +--- org.gcontracts:gcontracts-core:1.2.12 (*)
                       +--- org.codehaus.gpars:gpars:1.0.0 (*)
                       +--- com.fasterxml.jackson.core:jackson-databind:2.2.0 (*)
                       \--- org.spockframework:spock-core:0.7-groovy-1.8
                            \--- org.hamcrest:hamcrest-core:1.3
                  --------------------------------------------------------------------------------
                  runtime - Runtime classpath for source set 'main'.
                  +--- org.gcontracts:gcontracts-core:1.2.12
                  |    \--- org.ow2.asm:asm:4.0
                  +--- org.codehaus.gpars:gpars:1.0.0
                  |    \--- org.codehaus.jsr166-mirror:jsr166y:1.7.0
                  +--- com.fasterxml.jackson.core:jackson-databind:2.2.0
                  |    +--- com.fasterxml.jackson.core:jackson-annotations:2.2.0
                  |    \--- com.fasterxml.jackson.core:jackson-core:2.2.0
                  \--- com.github.goldin.plugins.gradle:common:0.2.8
                       +--- org.gcontracts:gcontracts-core:1.2.12 (*)
                       +--- org.codehaus.gpars:gpars:1.0.0 (*)
                       +--- com.fasterxml.jackson.core:jackson-databind:2.2.0 (*)
                       \--- org.spockframework:spock-core:0.7-groovy-1.8
                            \--- org.hamcrest:hamcrest-core:1.3]
===============================================================================


Configuration used: 


apply plugin: 'about'
 
..
 
buildscript {
    repositories { maven { url 'http://jcenter.bintray.com' }}
    dependencies { classpath 'com.github.goldin.plugins.gradle:about:0.2.8' }
}
 
..
 
about { includeDependencies = [ 'compile', 'runtime' ]
        prefix              = '/' }
 
jar   { dependsOn 'about' }


Details

Tasks
  • 'about' - adds an "about" file
Source Code
License
GroovyDoc
Tests
Issue Tracker
Build Server
Repositories,
Coordinates 
buildscript {
    repositories { maven { url 'http://jcenter.bintray.com' }}
    dependencies { classpath 'com.github.goldin.plugins.gradle:about:0.2.8' }
}


about { .. } extension properties


Name Type Default value Description
prefix String 'META-INF' Archive directory where "about" file is stored. Use '/' if "about" file should be stored in archive's root.
endOfLine String 'linux' If 'windows' - end of line in the file created is '\r\n'. For any other value it is '\n'.
includeSCM boolean true Whether SCM details should be included in "about" file. Currently, only Git is supported (feel free to vote for Mercurial support) and git command-line client is expected to be installed on a build machine.

Make sure the corresponding '.git' directory is available when your project is built. In TeamCity it requires "VCS checkout mode" to be set to "Automatically on agent" in build configuration Version Control Settings.

includeEnv boolean false Whether environment variables should be included in "about" file.
includeSystem boolean false Whether Java system properties should be included in "about" file.
includeProperties boolean false Whether Gradle properties should be included in "about" file.
includePaths boolean false Whether various build paths (Gradle home, build directory, etc) should be included in "about" file.
includeDependencies Object false Whether project dependencies report, the one you see by running "gradle dependencies", should be included in "about" file.
  • If set to true - all project's configurations are included.
  • If set to List<String> - only configurations specified are included. For example: 
about { includeDependencies = [ 'compile', 'testCompile' ] }
failIfNotFound boolean true Whether execution should fail if no archives were found to update.
failOnError boolean true Whether execution should fail if updating archives fails.
zipTasks boolean true Whether project's Zip tasks should be instructed to include an "about" file.
patterns boolean true Whether a combination of directory + include / exclude patterns should be used to locate an archives to update.
tasks List<Zip> [] Project's Zip tasks to instruct with adding an "about" file. All tasks are instructed if empty.
fileName String 'about.txt' Name of "about" file created.
directory File project.buildDir Directory where archives to update are located.
include String '**/*.jar, **/*.war, **/*.ear, **/*.zip' Comma-separated list of archive patterns to update.
exclude String Comma-separated list of archive patterns to exclude from update.


When and how "about" file is added

There are two ways "about" files can be added to build archives (artifacts):

  • Before archives are created: project's tasks of type Zip are instructed to include an "about" file. This means any zip or jar archive produced by your build will contain this file. For that to work 'about' task needs to run before any other archiving task, such as 'jar'. This can be achieved with:

    jar.dependsOn 'about'

    or

    $ gradle about build

  • After archives are created: all archives matched by a combination of directory + include / exclude patterns are updated. This happens when 'about' is running too late:

    $ gradle build about


By default both techniques are attempted and the one that is used depends on how early or late in a lifecycle of your build 'about' task is called. The earlier approach is recommended as it avoids an overhead of updating an existing archives.

Retrieved from "http://evgeny-goldin.com/wiki/Gradle-about-plugin"
Personal tools