A collection of Gradle plugins
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
gradle
plugins
subprojects/guide
.gitignore
.travis.yml
LICENSE
README.adoc
build.gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle

README.adoc

kordamp-gradle-plugins

Build Status Apache License 2 download donations Patreon orange


A set of opinionated Gradle plugins that provide common behavior observed in Maven, and more!

Usage

Option #1

buildscript {
    repositories {
        jcenter()
        maven {  url 'https://plugins.gradle.org/m2/' }
    }
    dependencies {
        classpath 'org.kordamp.gradle:{plugin-id}:0.5.0'
    }
}
apply plugin: '{plugin-id}'

Option #2

plugins {
    id '{plugin-id}' version '0.5.0'
}

Where {plugin-id} stands for any of the ids described in the following section. Most times it’s enough to simply apply the org.kordamp.gradle.project at the root. All plugins may be applied independently as well.

Plugins

Base

id: org.kordamp.gradle.base

Responsibilities:

  • Creates an extension named config that serves as the central point of configuration for all other plugins. This extension has the following properties

Name Type Default Value Description

release

boolean

false

Customizes Jar manifest and metainf if active

info

Information

The entry point for the project’s info DSL

apidoc

Apidoc

Configures the org.kordamp.gradle.apidocs plugin

bintray

Bintray

Configures the org.kordamp.gradle.bintray plugin

groovydoc

Groovydoc

Configures the org.kordamp.gradle.groovydoc plugin

jacoco

Jacoco

Configures the org.kordamp.gradle.jacoco plugin

javadoc

Javadoc

Configures the org.kordamp.gradle.javadoc plugin

license

License

Configures the org.kordamp.gradle.license plugin

minpom

Minpom

Configures the org.kordamp.gradle.minpom plugin

publishing

Publishing

Configures the org.kordamp.gradle.publishing plugin

source

Source

Configures the org.kordamp.gradle.source-jar plugin

stats

Stats

Configures the org.kordamp.gradle.source-stats plugin

sourceHtml

SourceHtml

Configures the org.kordamp.gradle.source-html plugin

DSL

The DSL defines the following elements

info {
    name
    description
    inceptionYear
    vendor
    tags

    links {
        website
        issueTracker
        scm
    }

    organization {
        name
        url
    }

    specification {
        enabled
        title
        version
        vendor
    }

    implementation {
        enabled
        title
        version
        vendor
    }

    credentials {
        github {
            username
            password
        }
        sonatype {
            username
            password
        }
    }

    people {
        person {
            id
            name
            email
            url
            roles
            timezone
            organization {
                name
                url
            }
            properties
        }
    }
}

apidoc {
    enabled
}

bintray {
    enabled
    credentials {
        username
        password
    }
    name
    repo
    userOrg
    githubRepo
}

groovydoc {
    enabled
    includes
    excludes
    replaceJavadoc
    options {
        windowTitle
        docTitle
        header
        footer
        overviewText
        links
        noTimestamp
        noVersionStamp
        includePrivate
        use
    }
}

jacoco {
    enabled
    mergeExecFile
    mergeReportHtmlFile
    mergeReportXmlFile
}

javadoc {
    enabled
    includes
    excludes
    title
    options { ... }
}

license {
    enabled
    licenses {
        license {
            id
            primary
            name
            url
            distribution
            comments
            aliases
        }
    }
}

minpom {
    enabled
}

publishing {
    enabled
}

source {
    enabled
}

stats {
    enabled
    counters
    formats
    paths
}

sourceHtml {
    conversion {
        srcDirs
        destDir
        includes
        outputFormat
        tabs
        style
        lineAnchorPrefix
        horizontalAlignment
        showLineNumbers
        showFileName
        showDefaultTitle
        showTableBorder
        includeDocumentHeader
        includeDocumentFooter
        addLineAnchors
        useShortFileName
        overwrite
    }
    overview {
        destDir
        pattern
        windowTitle
        docTitle
        docDescription
        icon
        stylesheet
    }
}
Table 1. General Properties
Name Type Required Default Value Description

name

String

no

project.name

Mapped to the <name> block in POM

description

String

yes

Mapped to the <description> block in POM

inceptionYear

String

no

current year

Mapped to the <inceptionYear> block in POM

vendor

String

no*

tags

List<String>

no

The value for vendor may be omitted if a value for organization.name is given.

Table 2. Links
Name Type Required Default Value Description

website

String

yes

empty

Mapped to the <url> block in POM. Mapped to bintray.pkg.websiteUrl

issueTracker

String

no*

empty

Mapped to bintray.pkg.issueTracker

scm

String

no*

empty

Mapped to the <scm> block in POM. Mapped to bintray.pkg.websiteUrl

Values for issueTracker and scm should be defined if the org.kordamp.gradle.bintray plugin is used.

Table 3. Organization
Name Type Required Default Value Description

name

String

no

The name of the organization

url

String

no

The URL of the organization (website perhaps).

This block is optional.

Table 4. Specification
Name Type Required Default Value Description

enabled

boolean

no

true

JAR manifest entries will be updated if true

title

String

no

project.name

Mapped to Specification-Title manifest entry

version

String

no

project.version

Mapped to Specification-Version manifest entry

vendor

String

no

info.vendor

Mapped to Specification-Vendor manifest entry

Table 5. Implementation
Name Type Required Default Value Description

enabled

boolean

no

true

JAR manifest entries will be updated if true

title

String

no

project.name

Mapped to Implementation-Title manifest entry

version

String

no

project.version

Mapped to Implementation-Version manifest entry

vendor

String

no

info.vendor

Mapped to Implementation-Vendor manifest entry

This block is optional.

Table 6. Credentials
Name Type Required Default Value Description

 github

Credentials

no*

Username/Password for connecting to GitHub

 sonatype

Credentials

no*

Username/Password for connecting to Maven Central

The sonatype entry may be used by the org.kordamp.gradle.bintray plugin to configure auto-sync with Maven Central when pushing a publication. This block is optional.

People

This block defines data associated with a particular person.

This block is optional.

Table 7. Person
Name Type Required Default Value Description

id

String

no*

Mapped to the <id> block in POM

name

String

no*

Mapped to the <name> block in POM

email

String

no

Mapped to the <email> block in POM

url

String

no

Mapped to the <url> block in POM

organization

Organization

no

Mapped to the <organizationName> and <organizationUrl> blocks in POM

roles

List<String>

no

Mapped to the <roles> block in POM

timezone

String

no

Mapped to the <timezone> block in POM

properties

Map<String, Object>

no

[:]

Mapped to the <properties> block in POM

At least id or name must be defined. If a developer role exists then the person instance is mapped to a <developer> block in the POM. If a contributor role exists then the person instance is maped to a <contributor> block in the POM.

Table 8. Apidoc
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.apidoc plugin if false

This block is optional.

Table 9. Bintray
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.bintray plugin if false

credentials

Credentials

yes

Values map to bintray.user and bintray.key

repo

String

yes

Mapped to bintray.pkg.repo

userOrg

String

yes

Mapped to bintray.pkg.userOrg

name

String

no

project.name

Mapped to bintray.pkg.name

githubRepo

String

yes

Mapped to bintray.pkg.githubRepo

The value of info.tags is mapped to bintray.pkg.labels.

Values for info.links are mapped to their matching entries in bintray.pkg.

Table 10. Groovydoc
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.groovydoc plugin if false

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier.

options.windowTitle

String

no

"${project.name} ${project.version}"

options.docTitle

String

no

"${project.name} ${project.version}"

options.header

String

no

"${project.name} ${project.version}"

options.footer

String

no

options.overviewText

TextResource

no

options.links

Set<Link>

no

[]

options.noTimestamp

boolean

no

options.noVersionStamp

boolean

no

options.includePrivate

boolean

no

true

options.use

boolean

no

true

This block is optional.

Table 11. Jacoco
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.jacoco plugin if false

mergeExecFile

File

no

${project.buildDir}/jacoco/root.exec

Location for the root merge execution data file

mergeReportHtmlFile

File

no

${project.buildDir}/reports/jacoco/root/html

Location for root HTML reports

mergeReportXmlFile

File

no

${project.buildDir}/reports/jacoco/root/jacocoTestReport.xml

Location for the root XML report

This block is optional.

Table 12. Javadoc
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.javadoc plugin if false

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

title

String

no

options

MinimalJavadocOptions

no

Supports all options from org.gradle.external.javadoc.StandardJavadocDocletOptions.

This block is optional.

Table 13. License
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.javadoc plugin if false

License.licenses

This block maps to the <licenses> block in POM. At least one nested license block must be defined.

Table 14. License.licenses.license
Name Type Required Default Value Description

id

LicenseId

no*

primary

boolean

no*

false

Identifies this as the main license if there are more than one

name

String

yes

Maps to the <name> block

url

String

no

Maps to the <url> block

distribution

String

no

'repo'

Maps to the <distribution> block

comments

String

no

Maps to the <comments> block

aliases

List<String>

no

[]

List of license aliases

This entry maps to a <license> block nested inside <licenses> in POM.

Prefer setting a value for the id property if using the org.kordamp.gradle.bintray and/or org.kordamp.gradle.license plugins. Only a single license entry must have primary = true. If no license has this setting then the first one in the list will be treated as the primary license. If more than one license has this setting the the first one of that set will be treated as the primary license.

Table 15. Minpom
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.minpom plugin if false

This block is optional.

Table 16. Publishing
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.publishing plugin if false

This block is optional.

Table 17. Source
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.source-jar plugin if false

This block is optional.

Table 18. Stats
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.source-stats plugin if false

counters

Map<String, String>

no

[:]

Additional org.kordamp.gradle.plugin.stats.Counter implementations, keyed by extension.

formats

List<String>

no

[]

List of output formats. Valid values are xml, html, txt.

paths

Map<String, Map<String, String>>

no

[:]

Maps of additional source paths that contain sources to be counted.

This block is optional.

Table 19. SourceHtml
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.source-html plugin if false

conversion.srcDirs

FileCollection

no

conversion.destDir

File

no

"${project.buildDir}/docs/source-html"

conversion.includes

String

no

'/.java,/.groovy'

conversion.outputFormat

String

no

'html'

conversion.tabs

int

no

4

conversion.style

String

no

'kawa'

Valid values are 'kawa', 'monochrome', 'eclipse'

conversion.lineAnchorPrefix

String

no

''

conversion.horizontalAlignment

String

no

'left'

conversion.showLineNumbers

boolean

no

true

conversion.showFileName

boolean

no

true

conversion.showDefaultTitle

boolean

no

true

conversion.showTableBorder

boolean

no

false

conversion.includeDocumentHeader

boolean

no

true

conversion.includeDocumentFooter

boolean

no

true

conversion.addLineAnchors

boolean

no

true

conversion.useShortFileName

boolean

no

true

conversion.overwrite

boolean

no

true

overview.destDir

File

no

"${project.buildDir}/docs/source-html"

overview.pattern

String

no

'*/.html'

overview.windowTitle

String

no

"$project.name $project.version"

overview.docTitle

String

no

"$project.name $project.version"

overview.docDescription

String

no

overview.icon

File

no

overview.stylesheet

File

no

This block is optional.

BuildInfo

id: org.kordamp.gradle.build-info

Responsibilities:

  • Defines a set of build related properties and attaches them to rootProject.ext.buildinfo. These properties are

Name Type Description

 buildTimeAndDate

java.util.Date

A java.util.Date instance representing the current time

 buildDate

String

The value of buildTimeAndDate formatted with "yyyy-MM-dd"

 buildTime

String

The value of buildTimeAndDate formatted with "HH:mm:ss.SSSZ"

 buildBy

String

The value of the user.name System property

 buildRevision

String

The value of the latest commit hash

 buildJdk

String

Concatenation of the following System properties [java.version, java.vendor, java.vm.version]

 buildCreatedBy

String

The Gradle version used in the build

Note
This plugin implicitly applies net.nemerosa:versioning to obtain SCM information.

SourceJar

id: org.kordamp.gradle.source-jar

Responsibilities:

  • Creates a Jar task that packages all sources.

Javadoc

id: org.kordamp.gradle.javadoc

Responsibilities:

  • Creates a javadoc task for all Java sources.

  • Creates a javadocJar task that packages the output of the javadoc task.

Groovydoc

id: org.kordamp.gradle.groovydoc

Responsibilities:

  • Creates a groovydoc task for all Groovy sources

  • Creates a groovydocJar task that packages the output of the groovydoc task.

Apidocs

id: org.kordamp.gradle.apidoc

Responsibilities:

  • Creates a aggregateApidocs task that collects Javadoc from all projects.

  • Creates a aggregateApidocsJar task that packages the collected Javadoc from all projects.

MinPom

id: org.kordamp.gradle.minpom

Responsibilities:

  • Creates a minpom task.

  • Creates a minimum pom.xml file.

  • Creates a minimum pom.properties.

Jar

id: org.kordamp.gradle.jar

Responsibilities:

  • Creates a jar task.

  • If the release property is enabled, configures manifest entries provided by BuildInfo.

  • If the release property is enabled, adds the output of the matching minpom task to metaInf.

Jacoco

id: org.kordamp.gradle.jacoco

Responsibilities:

  • Creates a JacocoReport task per each task of type Test.

  • Creates a JacocoMerge task on the rootProject with name jacocoRootMerge that aggregates all execution data.

  • Creates a JacocoReport`task on the `rootProject with name jacocoRootReport that aggregates all reports.

  • Settings can be specified using config.info.jacoco. See DSL for more options.

Publishing

id: org.kordamp.gradle.publishing

Responsibilities:

  • Configures a MavenPublication named "mainPublication".

  • Configures POM entries based on data available from config.info. See DSL for more options.

Bintray

id: org.kordamp.gradle.bintray

Responsibilities:

  • Configures a Bintray publication for "mainPublication".

  • Configuration values based on data available from `config.info.bintray. See DSL for more options.

  • Automatic synchronization with Maven Central if config.credentials.sonatype is provided.

Note
This plugin implicitly applies com.jfrog.bintray to obtain SCM information.

IntegrationTest

id: org.kordmap.gradle.integration-test

Responsibilities:

  • Create two additional configurations: integrationTestCompile and integrationTestRuntime. These configurations extend from testCompile and testRuntime respectively.

  • Create a SourceSet named integrationTest.

  • Create a Test task named integrationTest.

  • Create a TestReport task named integrationTestReport. This task is added as a dependency to check.

FunctionalTest

id: org.kordmap.gradle.functional-test

Responsibilities:

  • Create two additional configurations: functionalTestCompile and functionalTestRuntime. These configurations extend from compile and runtime respectively.

  • Create a SourceSet named functionalTest.

  • Create a Test task named functionalTest.

  • Create a TestReport task named functionalTestReport. This task is added as a dependency to check.

Note
You must add testing dependencies to functionalTestCompile as this configuration is independent from testCompile.

License

id: org.kordmap.gradle.license

Responsibilities:

  • Configures the license extension per project.

  • Expects the license header template to be located at rootProject.file('gradle/LICENSE_HEADER').

  • Automatically excludes /.png and META-INF/services/*.

  • Creates a task named aggregateLicenseReport on the root project that aggregates all license reports.

The following variables become available to the license header template

Name

Value

project

project.name

projectName

config.info.name

copyrightYear

config.info.inceptionYear [hyphenated with the current year if inceptionYear is earlier]

author

Name or Id of all people with role author or the first Person found in config.info.people

license

The SPDX id of the primary license

Note
This plugin implicitly applies com.github.hierynomus.license to all projects.

SourceStats

id: org.kordamp.gradle.source-stats

Responsibilities:

  • Create a SourceStatsTask named sourceStats per project.

  • Create a AggregateSourceStatsReportTask named aggregateSourceStats at the root project.

SourceHtml

id: org.kordamp.gradle.source-html

Responsibilities:

  • Adds a java2html configuration.

  • Creates a ConvertCodeTask named convertCodeToHtml task per project.

  • Creates a GenerateOverviewTask named generateSourceHtmlOverview task per project.

  • Creates a task named sourceHtml task that depends on convertCodeToHtml and generateSourceHtmlOverview.

  • Creates a ConvertCodeTask task on the rootProject with name aggregateConvertCodeToHtml that aggregates all source code.

  • Creates a GenerateOverviewTask`task on the `rootProject with name aggregateGenerateSourceHtmlOverview that generates an aggregate overview.

  • Creates a task named aggregateSourceHtml on the root project that depends on aggregateConvertCodeToHtml and aggregateGenerateSourceHtmlOverview.

Note
This plugin relies on the com.bmuschko.java2html plugin but does not apply it.

Guide

id: org.kordamp.gradle.guide

Responsibilities:

  • Creates an extension with name guide and type GuideExtension.

  • Applies and configures the asciidoctor plugin.

  • Creates a task named createGuide that assembles the documentation based on the output from asciidoctor and aggregateApidocs tasks.

  • Creates a task named zipGuide that packages the guide’s contents.

  • Creates a task named initGuide that initializes the director/file structure.

Note
This plugin implicitly applies the org.asciidoctor.convert plugin.

Project

id: org.kordamp.gradle.project

Responsibilities:

  • Applies all previous projects except IntegrationTest, FunctionalTest, Guide.

This plugin implicitly applies com.github.ben-manes.versions to all projects.