1. Introduction

This project provides a set of Gradle plugins that follow an opinionated way to build Java, Groovy, Scala or Kotlin projects. The conventions defined by these plugins closely follow common practices observed in many Open Source projects.

1.1. Rationale

The Gradle Build Tool is very flexible and extensible, allowing developers to micro-manage every single aspect of a particular build. However, with great power comes great responsibility and in this case higher maintenance as at some point, many Gradle builds turn out to be custom builds, that is, each one follows their own conventions and/or are written with a slightly different style, making it difficult to understand the pattern and apply the conventions to another build.

In contrast, the Apache Maven build tool follows a much stricter yet still somehow flexible path to define builds. Many developers have cited Maven’s "strictness" or "inflexibility" as a feature rather than a limitation of the tool. Personally I prefer a highly flexible tool (such as Gradle) while at the same time applying a structure on top that can still be bent to a certain degree. The plugins found in this project provide such a structure.

The following sections describe the conventions and each of the plugins.

In this guide you’ll see examples that run Gradle using the gm command. This command is provided by Gum, it let’s you run a build with either the Gradle wrapper (gradlew) or the Gradle command (gradle). If you’re unsure of the command to invoke then just use the wrapper or gradle directly.

2. Usage

There are two choices for applying any of the plugins described in this document

Option #1

Groovy
buildscript {
    repositories {
        gradlePluginPortal()
        // required for additional dependencies
        mavenCentral()
    }
    dependencies {
        classpath 'org.kordamp.gradle:{plugin-id}:0.54.0'
    }
}
apply plugin: '{plugin-id}'
Kotlin
buildscript {
    repositories {
        gradlePluginPortal()
        // required for additional dependencies
        mavenCentral()
    }
    dependencies {
        classpath("org.kordamp.gradle:{plugin-id}:0.54.0")
    }
}
apply(plugin = "{plugin-id}")

Option #2

Groovy
plugins {
    id '{plugin-id}' version '0.54.0'
}
Kotlin
plugins {
    id("{plugin-id}") version "0.54.0"
}

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

2.1. Requirements

Java 11 and Gradle 7 are the minimum requirements to use any of these plugins.

3. Project Structure

It’s expected of projects that make use of these plugins to follow a certain directory structure that enables them to gain higher benefits via conventions rather than writing lots of custom configuration elements.

To begin with, projects should have a multi-project nature, i.e. be comprised of a root project and at least one subproject or module. Why is this? This way a root project serves as the central point of configuration, while additional subprojects may be added at later stages during development. Thus the minimum structure could look like this

.
├── build.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── subprojects
    └── project1
        ├── build.gradle
        └── src
            └── main

There are many ways to structure a multi-project build. Some prefer adding all submodule directories at the root level, others prefer a two or more levels structure. None of the plugins enforce a particular directory structure, you’re free to pick the structure that suits your style better. Personally I prefer the following structure

.
├── build.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
├── docs
│   └── guide
│       ├── guide.gradle
│       └── src
│           └── docs
│               ├── asciidoc
│               └── resources
└── subprojects
    ├── project1
    │   ├── project1.gradle
    │   └── src
    │       └── main
    └── project2
        ├── project2.gradle
        └── src
            └── main

You’ll notice that source code projects are placed under subprojects while documentation projects are placed under docs. Also, the names of the build files have been changed to reflect the name of the project they belong to. This change must be reflected in the settings.gradle (Groovy) or settings.gradle.kts (Kotlin) file, using code similar to

Groovy
rootProject.name = 'root'

def includeProject = { String projectDirName, String projectName ->
    File baseDir = new File(settingsDir, projectDirName)
    File projectDir = new File(baseDir, projectName)
    String buildFileName = "${projectName}.gradle"

    assert projectDir.isDirectory()
    assert new File(projectDir, buildFileName).isFile()

    include projectName
    project(":${projectName}").projectDir    = projectDir
    project(":${projectName}").buildFileName = buildFileName
}

['docs', 'subprojects'].each { dirName ->
    File subdir = new File(rootDir, dirName)
    subdir.eachDir { dir ->
        File buildFile = new File(dir, "${dir.name}.gradle")
        if (buildFile.exists()) {
            includeProject dirName, dir.name
        }
    }
}
Kotlin
rootProject.name = "root"

fun includeProject(projectDirName: String, projectName: String) {
    val baseDir = File(settingsDir, projectDirName)
    val projectDir = File(baseDir, projectName)
    val buildFileName = "${projectName}.gradle.kts"

    assert(projectDir.isDirectory())
    assert(File(projectDir, buildFileName).isFile())

    include(projectName)
    project(":${projectName}").projectDir    = projectDir
    project(":${projectName}").buildFileName = buildFileName
}

listOf("docs", "subprojects").forEach { dirName ->
    val subdir = File(rootDir, dirName)
    subdir.walkTopDown().maxDepth(1).forEach { dir ->
        val buildFile = File(dir, "${dir.name}.gradle.kts")
        if (buildFile.exists()) {
            includeProject(dirName, dir.name)
        }
    }
}

Alternatively, you may apply the org.kordamp.gradle.settings plugin to your settings.gradle(.kts) file to obtain the same behavior:

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

rootProject.name = 'root'

projects {
    directories = ['docs', 'subprojects']
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

rootProject.name = "root"

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    directories.addAll(listOf("docs", "subprojects"))
}

With this structure in place the next step would be to setup the minimum configuration on the root project’s build file

Groovy
plugins {
    id 'org.kordamp.gradle.java-project' version '0.54.0'      (1)
}

config {
    release = (rootProject.findProperty('release') ?: false).toBoolean()  (2)

    info {                                                                (3)
        name        = 'Sample'
        vendor      = 'Acme'
        description = 'Sample project'

        links {
            website      = 'https://github.com/joecool/sample'
            issueTracker = 'https://github.com/joecool/sample/issues'
            scm          = 'https://github.com/joecool/sample.git'
        }

        people {
            person {
                id    = 'joecool'
                name  = 'Joe Cool'
                roles = ['developer']
            }
        }
    }

    licensing {                                                           (4)
        licenses {
            license {
                id = 'Apache-2.0'
            }
        }
    }
}

allprojects {
    repositories {
        mavenCentral()
    }
}
1 Download and apply plugins to root project
2 Conditionally enable some features related to publishing
3 General information for all projects
4 License details
Kotlin
plugins {
    id("org.kordamp.gradle.java-project") version "0.54.0"     (1)
}

config {
    release = rootProject.findProperty("release").toString().toBoolean()  (2)

    info {                                                                (3)
        name        = "Sample"
        vendor      = "Acme"
        description = "Sample project"

        links {
            website      = "https://github.com/joecool/sample"
            issueTracker = "https://github.com/joecool/sample/issues"
            scm          = "https://github.com/joecool/sample.git"
        }

        people {
            person {
                id    = "joecool"
                name  = "Joe Cool"
                roles = listOf("developer")
            }
        }
    }

    licensing {                                                           (4)
        licenses {
            license {
                id = org.kordamp.gradle.plugin.base.model.LicenseId.APACHE_2_0
            }
        }
    }
}

allprojects {
    repositories {
        mavenCentral()
    }
}
1 Download and apply plugins to root project
2 Conditionally enable some features related to publishing
3 General information for all projects
4 License details

This minimal configuration enables the following features:

  • Generate additional JAR manifest entries if 2 is enabled.

  • Generate a -sources JAR file with all sources per project.

  • Configure the javadoc task for each project using information found in the config block, such as author, copyright year, default settings.

  • Generate a -javadoc JAR file with the output of the javadoc task, per project.

  • Generate a task on the root project that collects all Javadoc.

  • Generate a task on the root project that packages the aggregated javadoc.

  • Configure the license plugin with the license details 4.

  • Configure the maven-publish plugin with data defined in 3 and 4. The -sources and -javadoc JARs are automatically added to the default publication.

  • Configure the jacoco plugin on each project.

  • Configure aggregate JaCoCo reports on the root project.

  • Generate a source stats task per project.

  • Generate a task at the root project to collect aggregate source stats.

  • Generates a task per project that creates pretty-printed sources (HTML).

  • Generate a task at the root project to collect pretty-printed sources.

The build file for the guide project can be as simple as

Groovy
apply plugin: 'org.kordamp.gradle.guide'
Kotlin
apply(plugin = "org.kordamp.gradle.guide")

And the build file for each subproject may look like

Groovy
apply plugin: 'java'

dependencies {
    // dependencies
}
Kotlin
apply(plugin = "java")

dependencies {
    // dependencies
}

There are 4 language specific project aggregators and 1 generic project aggregator

Type Plugin

Generic

org.kordamp.gradle.project

Java

org.kordamp.gradle.java-project

Groovy

org.kordamp.gradle.groovy-project

4. Config DSL

Most plugins take their configuration from a centralized point: the Config DSL. This feature is added by the org.kordamp.gradle.base which is automatically applied by most plugins.

The DSL is comprised of the following elements

config {
    info { ... }
    dependencyManagement { ... }
    bom { ... }
    buildInfo { ... }
    licensing { ... }
    plugins { ... }
    publishing { ... }
    stats { ... }
    testing { ... }
    artifacts {
        jar { ... }
        minpom { ... }
        source { ... }
    }
    docs {
        guide { ... }
        groovydoc { ... }
        javadoc { ... }
    }
    coverage {
        coveralls { ... }
        jacoco { ... }
    }
    quality {
        checkstyle { ... }
        codenarc { ... }
        errorprone { ... }
        pmd { ... }
        spotbugs { ... }
        sonar { ... }
    }
}

Each one of these elements (except for info) expose a property named enabled that can be used to turn on or off all of the behavior provided by the associated plugin. This property is set to true by default.

Most of the time it’s enough to configure the DSL on the root project, as settings are automatically applied to all subprojects. However it’s also possible to override a particular root setting should the need arises, just define a config block on the subproject’s build file and override the settings you need. Here’s for example how a child project may skip publications completely:

build.gradle (root)
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    info { ... }
    // additional configuration
}

allprojects {
    repositories {
        mavenCentral()
    }
}
build.gradle.kts (root)
plugins {
    id("org.kordamp.gradle.project") version "0.54.0"
}

config {
    info { ... }
    // additional configuration
}

allprojects {
    repositories {
        mavenCentral()
    }
}
build.gradle (child)
config {
    publishing { enabled = false }
}
build.gradle.kts (child)
config {
    publishing { enabled = false }
}

5. Plugins DSL

This DSL becomes available when org.kordamp.gradle.settings plugins is applied to a settings file (settings.gradle or settings.gradle.kts). It’s function is to group and apply plugins per project during project discovery as specified by the chosen project layout.

The DSL is comprised of the following elements

projects {
    plugins {
        all {
            excludePath(String pathOrRegex)
            id(String pluginId).includeIf(boolean)
            id(String pluginId).includeIf(Supplier<Boolean> condition)
        }
        dir(String dir) {
            id(String pluginId).includeIf(boolean value)
            id(String pluginId).includeIf(Supplier<Boolean> condition)
        }
        dirs(List<String> dirs) {
            excludedir(String dir)
            excludePath(String pathOrRegex)
            id(String pluginId).includeIf(boolean value)
            id(String pluginId).includeIf(Supplier<Boolean> condition)
        }
        path(String pathOrRegex) {
            id(String pluginId).includeIf(boolean value)
            id(String pluginId).includeIf(Supplier<Boolean> condition)
        }
        paths(List<String> pathsOrRegexes) {
            excludePath(String pathOrRegex)
            id(String pluginId).includeIf(boolean value)
            id(String pluginId).includeIf(Supplier<Boolean> condition)
        }
    }
}

Where each block will be applied according to these rules:

all

All projects in the build, including the root project.

dir

A project whose parent directory exactly matches the given argument.

dirs

Projects whose parent directory exactly matches any of the elements in the given list of values.

path

A project that exactly matches the argument by path, or projects whose path matches the argument as regex.

paths

Projects whose path either matches exactly any of the given elements, or the path matches any of the elements as regex.

excludeDir

A project to be excluded by directory. Argument must be an exact match.

excludePath

A project to be excluded by path. Argument must be an exact match or a regex.

These are the usage rules:

  • The value of id() is a given plugin id, such as org.kordamp.gradle.project.

  • The includeIf() condition (if specified) applies the plugin if true. Default is to apply the given plugin.

  • Every block accepts multiple invocations of id().

  • No additional elements besides id() (or exclude() when using dirs()) can appear.

  • The value of dir() and dirs() must match any of

    • Elements in projects.directories when projects.layout is equal to two-level.

    • The root directory when projects.layout is equal to standard.

    • The parent directory of a given project when projects.layout is equal to multi-level.

  • The value of path() and paths() must be any of

    • A full project path, such as :project1.

    • A regex that can be matched to a project path.

    • A single '*' will match all paths. Equivalent to using the all { } DSL block.

  • Plugins must be declared in a buildscript block as classpath entries, alongside the org.kordamp.gradle.settings.

5.1. Example

Given the following project structure

.
├── settings.gradle
├── build.gradle
├── docs
│   └── guide
│       └── guide.gradle
└── subprojects
    ├── project1
    │   └── project1.gradle
    ├── project2
    │   └── project2.gradle
    └── project3
        └── project3.gradle

And the following settings file

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
    dependencies {
        classpath "org.kordamp.gradle:settings-gradle-plugin:0.54.0"
        classpath "org.kordamp.gradle:java-project-gradle-plugin:0.54.0"
        classpath "org.kordamp.gradle:guide-gradle-plugin:0.54.0"
        classpath "org.kordamp.gradle:integrationtest-gradle-plugin:0.54.0"
        classpath "org.kordamp.gradle:functionaltest-gradle-plugin:0.54.0"
    }
}

apply plugin: 'org.kordamp.gradle.settings'

projects {
    layout = 'two-level'
    directories = ['docs', 'subprojects']

    plugins {
        path(':') {
            id 'org.kordamp.gradle.java-project'
        }
        path(':guide') {
            id 'org.kordamp.gradle.guide'
        }
        dir('subprojects') {
            excludeDir('project3')
            // alternatively
            // excludePath(':project3')
            id 'java-library'
            id 'org.kordamp.gradle.integration-test'
        }
        path(':project3') {
            id 'java-library'
            id 'org.kordamp.gradle.functional-test'
        }
    }
}
settings.gradle.kts
import org.kordamp.gradle.plugin.settings.ProjectsExtension
import org.kordamp.gradle.plugin.settings.SettingsPlugin

buildscript {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }

    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
        classpath("org.kordamp.gradle:java-project-gradle-plugin:0.54.0")
        classpath("org.kordamp.gradle:guide-gradle-plugin:0.54.0")
        classpath("org.kordamp.gradle:integrationtest-gradle-plugin:0.54.0")
        classpath("org.kordamp.gradle:functionaltest-gradle-plugin:0.54.0")
    }
}

apply<SettingsPlugin>()

configure<ProjectsExtension> {
    setLayout("two-level")
    directories.addAll(listOf("docs", "subprojects"))

    plugins {
        path(":") {
            // must apply this to root otherwise configurations will fail
            // if you define common dependencies in build.gradle.kts
            id("java")
            id("org.kordamp.gradle.java-project")
        }
        path(":guide") {
            id("org.kordamp.gradle.guide")
        }
        dir("subprojects") {
            exclude(":project3")
            id("java-library")
            id("org.kordamp.gradle.integration-test")
        }
        path(":project3") {
            id("java-library")
            id("org.kordamp.gradle.functional-test")
        }
    }
}

This configuration will perform the following:

  • Apply org.kordamp.gradle.project to the root.

  • Apply org.kordamp.gradle.guide to the :guide project.

  • Apply java-library to all projects under subprojects dir.

  • Apply org.kordamp.gradle.integration-test to :project1 and :project2 projects.

  • Apply org.kordamp.gradle.functional-test to the :project3 project.

5.2. Remarks

  1. The usage of this DSL is optional. Gradle might change how it performs plugin management and resolution at any time.

  2. Plugins defined and applied with this DSL are still visible to build files using the standard Gradle facilities such as plugins {} and apply plugin:.

  3. Plugins defined in settings.gradle(.kts) using the standard plugins {} from Gradle will not be visible to this DSL.

6. Projects DSL

This DSL becomes available when org.kordamp.gradle.base plugins is applied to a build file. It’s function is to group common configuration matching projects by path or directory. This DSL is another way to configure allprojects or subprojects.

The DSL is comprised of the following elements

gradleProjects {
    all {
        condition(Function<Project,Boolean>) {
           // configuration
        }
        dir(String) {
            // configuration
        }
        dirs(List<String>) {
            // configuration
        }
        path(String) {
            // configuration
        }
        paths(List<String>) {
            // configuration
        }
    }
    subprojects {
        condition(Function<Project,Boolean>) {
           // configuration
        }
        dir(String) {
            // configuration
        }
        dirs(List<String>) {
            // configuration
        }
        path(String) {
            // configuration
        }
        paths(List<String>) {
            // configuration
        }
    }
}

Where each block will be applied according to these rules:

all

Lazily matches and applies configuration to all projects, including the root project.

subprojects

Lazily matches and applies configuration to only subprojects.

condition

Projects that match the given condition.

dir

A project whose parent directory exactly matches the given argument.

dirs

Projects whose parent directory exactly matches any of the elements in the given list of values.

path

A project that exactly matches the argument by path, or projects whose path matches the argument as regex.

paths

Projects whose path either matches exactly any of the given elements, or the path matches any of the elements as regex.

The contents of the configuration block can be any valid build expression that can be applied to a Project.

6.1. Example

Given the following project structure

.
├── settings.gradle
├── build.gradle
├── docs
│   └── guide
│       └── guide.gradle
└── subprojects
    ├── project1
    │   └── project1.gradle
    ├── project2
    │   └── project2.gradle
    └── project3
        └── project3.gradle

And the following root build file

build.gradle
config {
    // ...
}

gradleProjects {
    all {
        path('*') {
            repositories {
                mavenCentral()
            }
        }

        dir('subprojects') {
            dependencies {
                testImplementation "junit:junit:$junitVersion"
            }
        }
    }
}
build.gradle.kts
import org.kordamp.gradle.plugin.base.ProjectsExtension

config {
    // ...
}

configure<ProjectsExtension> {
    all {
        path("*") {
            repositories {
                mavenCentral()
            }
        }

        dir("subprojects") {
            val junitVersion: String by project
            dependencies {
                testImplementation("junit:junit:$junitVersion")
            }
        }
    }
}

This configuration will perform the following

  • Configure the mavenCentral() repository on all projects (path = *).

  • Configure junit as dependency on :project1, :project2, and :project3 (all projects found under dir=subprojects)

6.2. Remarks

  1. The usage of this DSL is optional.

7. Plugins

7.1. Base

Enables the configuration DSL. Settings made via this DSL are consumed by multiple plugins.

7.1.1. DSL

config {
    release

    info {
        name
        description
        inceptionYear
        vendor
        tags

        links {
            enabled
            website
            issueTracker
            scm
        }

        scm {
            enabled
            url
            tag
            connection
            developerConnection
        }

        organization {
            name
            url
        }

        specification {
            enabled
            title
            version
            vendor
        }

        implementation {
            enabled
            title
            version
            vendor
            vendorId
            vendorUrl
        }

        credentials {
            inherits
            mergeStrategy
            github {
                username
                password
            }
            sonatype {
                username
                password
            }
            named {
                name
                username
                password
            }
        }

        repositories {
            inherits
            mergeStrategy
            repository {
                name
                url
                credentials {
                    username
                    passsword
                }
            }
        }

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

        issueManagement {
            system
            url
        }

        ciManagement {
            system
            url
        }

        mailingLists {
            inherits
            mergeStrategy
            mailingList {
                name
                subscribe
                unsubscribe
                post
                archive
                otherArchives
            }
        }
    }

    dependencyManagement {
        dependency(String)
    }
}

The release flag should be set to true (default is false) when a release (any kind of release, even snapshot) is needed. At the moment this flag controls enrichment of JAR manifests as explained in the Jar plugin. Other plugins may hook into this flag to provide additional configuration and behavior.

general

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.

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables this block.

website

String

yes

empty

Mapped to the <url> block in POM.

issueTracker

String

no*

empty

scm

String

no*

empty

Mapped to the <scm> block in POM.

scm

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables this block.

url

String

yes

empty

Mapped to the <scm><url> block in POM.OM.

connection

String

no*

empty

Mapped to the <scm><connection> block in POM.`

developerconnection

String

no*

empty

Mapped to the <scm><developerConnection> block in POM.

This block has precedence over links.scm.

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.

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

This block is optional.

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

vendorId

String

no

Mapped to Implementation-Vendor-Id manifest entry

url

String

no

Mapped to Implementation-Url manifest entry

This block is optional.

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

named

Credentials

no*

Defines a named credentials entry. Name may match a repository entry.

inherits

boolean

no

true

Whether to inherit values from a parent POM.

mergeStrategy

MergeStrategy

no

UNIQUE

One of PREPEND, APPEND, UNIQUE, OVERWRITE.

The value of inherits cannot be changed once it has been set.

The values of mergeStrategy control how multiple credentials will be handled

PREPEND

Child values (if any) will be placed before inherited values (if any).

APPEND

Child values (if any) will be placed after inherited values (if any).

UNIQUE

Child and inherited values will be merged by license id.

OVERWRITE

Child values will be used unless empty, in which case inherited values will be used.

Named credentials may match the name of a repository, in which case they will be used during artifact publication on the matching repository.

This block is optional.

repositories

This block defines data associated with a particular repository. Entries may be used during publication.

Name Type Required Default Value Description

inherits

boolean

no

true

Whether to inherit values from a parent POM.

mergeStrategy

MergeStrategy

no

UNIQUE

One of PREPEND, APPEND, UNIQUE, OVERWRITE.

The value of inherits cannot be changed once it has been set.

The values of mergeStrategy control how multiple repositories will be handled

PREPEND

Child values (if any) will be placed before inherited values (if any).

APPEND

Child values (if any) will be placed after inherited values (if any).

UNIQUE

Child and inherited values will be merged by license id.

OVERWRITE

Child values will be used unless empty, in which case inherited values will be used.

repository

Name Type Required Default Value Description

name

String

no*

The name of the repository

url

String

no*

The URL of the repository

credentials

Credentials

no*

Values mapped to credentials block

The credentials entry is optional. Credentials may be defined locally to the repository or globally using the credentials block. Local credentials have precedence over global credentials that match the repository name.

people

Name Type Required Default Value Description

inherits

boolean

no

true

Whether to inherit values from a parent POM.

mergeStrategy

MergeStrategy

no

UNIQUE

One of PREPEND, APPEND, UNIQUE, OVERWRITE.

The value of inherits cannot be changed once it has been set.

The values of mergeStrategy control how multiple people will be handled

PREPEND

Child values (if any) will be placed before inherited values (if any).

APPEND

Child values (if any) will be placed after inherited values (if any).

UNIQUE

Child and inherited values will be merged by license id.

OVERWRITE

Child values will be used unless empty, in which case inherited values will be used.

This block defines data associated with a particular person.

This block is optional if none of the following plugins are used: org.kordamp.gradle.javadoc, org.kordamp.gradle.groovydoc, org.kordamp.gradle.publishing.

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.

issueManagement

Name Type Required Default Value Description

system

String

no

The system value of the <issueManagement> block in POM

url

String

no

The url value of the <issueManagement> block in POM

ciManagement

Name Type Required Default Value Description

system

String

no

The system value of the <ciManagement> block in POM

url

String

no

The url value of the <ciManagement> block in POM

mailingLists

Name Type Required Default Value Description

inherits

boolean

no

true

Whether to inherit values from a parent POM.

mergeStrategy

MergeStrategy

no

UNIQUE

One of PREPEND, APPEND, UNIQUE, OVERWRITE.

The value of inherits cannot be changed once it has been set.

The values of mergeStrategy control how multiple mailing lists will be handled

PREPEND

Child values (if any) will be placed before inherited values (if any).

APPEND

Child values (if any) will be placed after inherited values (if any).

UNIQUE

Child and inherited values will be merged by license id.

OVERWRITE

Child values will be used unless empty, in which case inherited values will be used.

This block defines a list of MailingList entries.

mailingList

Name Type Required Default Value Description

name

String

no*

Mapped to the <name> block in POM

subscribe

String

no

Mapped to the <subscribe> block in POM

unsubscribe

String

no

Mapped to the <unsubscribe> block in POM

post

String

no

Mapped to the <post> block in POM

archive

String

no

Mapped to the <archive> block in POM

otherArchives

List<String>

no

Mapped to the <otherArchives> block in POM

At least name must be defined.

dependencyManagement

This block serves as a central point for declaring dependencies and platforms that can later be reused in other places such as the standard dependencies block. Dependency definitions require 4 elements:

name

short name of the dependency or platform.

groupId

the groupId part of the artifact’s coordinates.

artifactId

the artifactId part of the artifact’s coordinates.

version

the version part of the artifact’s coordinates.

platform

true if this dependency constitutes a platform, false otherwise (default).

Additionally a dependency may define a set of modules that go together, for example, for groovy you can have the grovy-core, groovy-xml, groovy-json modules. All modules and the owning dependency share the same groupId and version.

The dependencyManagement block will suggest/force dependency versions for all configurations. You can disable this feature by defining a System property org.kordamp.gradle.base.dependency.management with false as value.

This feature ships in preview mode and is disabled by default.
Dependencies defined in the dependencyManagement block cannot have classifiers and must be resolvable from a Maven compatible repository.
Methods
dependency(String gavNotation)

Defines a dependency. Argument must use the groupId:artifactId:version notation. Dependency name will be equal to artifactId.
Example:

dependency('com.googlecode.guava:guava:29.0-jre')
dependency(String name, String gavNotation)

Defines a dependency. Second argument must use the groupId:artifactId:version notation.
Example:

dependency('guava', 'com.googlecode.guava:guava:29.0-jre')
dependency(String name, String gavNotation, Action action)

Defines and configures a dependency. Second argument must use the groupId:artifactId:version notation.
Example:

dependency('groovy', 'org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
dependency(String name, String gavNotation, Closure action)

Defines and configures a dependency. Second argument must use the groupId:artifactId:version notation.
Example:

dependency('groovy', 'org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
platform(String gavNotation)

Defines a platform dependency. Argument must use the groupId:artifactId:version notation. Dependency name will be equal to artifactId.
Example:

platform('io.micronaut:micronaut-bom:2.0.2')
platform(String name, String gavNotation)

Defines a platform dependency. Second argument must use the groupId:artifactId:version notation.
Example:

platform('micronaut', 'io.micronaut:micronaut-bom:2.0.2')
dependency(String gavNotation, Action action)

Defines and configures a dependency by name.
Example:

dependency('org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
dependency(String gavNotation, Closure action)

Defines and configures a dependency by name.
Example:

dependency('org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
getDependency(String name)

Returns the named dependency (if it exists). Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

getDependency('guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
getDependency('com.googlecode.guava:guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependency(String nameOrGa)

Finds a dependency by name or GA if it exists, null otherwise.
Example:

findDependency('guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependency('com.googlecode.guava:guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependencyByName(String name)

Finds a dependency by name if it exists, null otherwise.
Example:

findDependencyByName('guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependencyByGA(String name, String moduleNAme)

Finds a dependency by groupId and artifactId if it exists, null otherwise.
Example:

findDependencyByGA('com.googlecode.guava', 'guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
getPlatform(String name)

Returns the named platform (if it exists). Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the platform.
Example:

getPlatform('micronaut') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
getPlatform('io.micronaut:micronaut-bom') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatform(String nameOrGa)

Returns the named platform (if it exists). The nameOrGa parameter may be the logical name or the groupId:artifactId of the platform.
Example:

findPlatform('micronaut') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatform('io.micronaut:micronaut-bom') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatformByName(String name)

Finds a platform by name if it exists, null otherwise.
Example:

findPlatformByName('micronaut') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatformByGA(String name, String moduleNAme)

Finds a platform by groupId and artifactId if it exists, null otherwise.
Example:

findPlatformByGA('io.micronaut', 'micronaut-bom') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
gav(String name)

Returns the given dependency in GAV notation if it exists. Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

gav('groovy') == 'org.codehaus.groovy:groovy:3.0.6'
gav('org.codehaus.groovy:groovy') == 'org.codehaus.groovy:groovy:3.0.6'
gav(String name, String moduleName)

Returns the given module dependency in GAV notation if it exists. Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

gav('groovy', 'groovy-json') == 'org.codehaus.groovy:groovy-json:3.0.6'
gav('org.codehaus.groovy:groovy', 'groovy-json') == 'org.codehaus.groovy:groovy-json:3.0.6'
ga(String name, String moduleName)

Returns the given module dependency in GA (groupId/artifactId) notation if it exists. Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

ga('micronaut', 'micronaut-core') == 'io.micronaut:micronaut-core'
ga('io.micronaut:micronaut-bom', 'micronaut-core') == 'io.micronaut:micronaut-core'
Instances of type org.kordamp.gradle.plugin.base.model.artifact.Dependency or org.kordamp.gradle.plugin.base.model.artifact.Platform can not be passed directly to Gradle’s dependency resolution mechanism. You must convert them to any of the accepted notations such as groupId:artifactId:version, use the gav() or ga() utility methods instead.
Example
build.gradle
config {
    dependencyManagement {
        // a dependency with modules
        dependency('groovy') {
            groupId    = 'org.codehaus.groovy'
            artifactId = 'groovy'
            version    = '3.0.6'
            modules    = [
                'groovy-test',
                'groovy-json',
                'groovy-xml'
            ]
        }
        // a dependency without modules
        dependency('junit:junit:4.13')
        // a platform
        platform('micronaut', 'io.micronaut:micronaut-bom:2.0.2')
    }
}

These dependencies can be used in combination with the applyToDefaults and applyTo extensions if the org.kordamp.gradle.java-project plugin is applied, for example

build.gradle
plugins {
    id 'org.kordamp.gradle.java-project'
}

config {
    dependencyManagement {
        // a dependency with modules
        dependency('groovy') {
            groupId    = 'org.codehaus.groovy'
            artifactId = 'groovy'
            version    = '3.0.6'
            modules    = [
                'groovy-test',
                'groovy-json',
                'groovy-xml'
            ]
        }
        // a dependency without modules
        dependency('junit:junit:4.13')
        // a platform
        platform('micronaut', 'io.micronaut:micronaut-bom:2.0.2')
    }
}

// consume dependencies
dependencies {
    // apply Micronaut platform to some configurations
    applyTo.c('api', 'annotationProcessor', 'compileOnly').platform('micronaut')
    // configure a dependency in the standard way
    api 'io.micronaut:micronaut-core'
    // configure a platform module by groupId:artifactId
    annotationProcessor config.dependencyManagement.ga('micronaut', 'micronaut-inject')
    // pull in a module from Groovy
    api config.dependencyManagement.gav('groovy', 'groovy-json')
    // configure a single dependency
    testImplementation config.dependencyManagement.gav('junit')
}

Will generate the following entries in the POM if publishing is enabled

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <!--
    coordinates and other elements omitted for brevity
   -->
  <properties>
    <micronaut.version>2.0.2</micronaut.version>
    <groovy.version>3.0.6</groovy.version>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-bom</artifactId>
        <version>${micronaut.version}</version>
        <scope>import</scope>
        <type>pom</type>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.micronaut</groupId>
      <artifactId>micronaut-core</artifactId>
    </dependency>
    <dependency>
      <groupId>org.codehaus.groovy</groupId>
      <artifactId>groovy-json</artifactId>
      <version>${groovy.version}</version>
    </dependency>
  </dependencies>
</project>
System Properties
org.kordamp.gradle.base.validate

Perform validation on DSL settings. Defaults to true.

org.kordamp.gradle.base.dependency.management

Suggest/force dependency versions. Defaults to false.

7.1.2. Tasks

Archives

Displays all configured archives in a project.

Name

archives

Type

org.kordamp.gradle.plugin.base.tasks.ArchivesTask

Example Output

For a project defined as follows

build.gradle
plugins {
    id 'java-library'
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    info {
        description      = 'Demo project'
        vendor           = 'Acme'
        links.scm        = 'https://github.com/acme/demo'
        organization.url = 'https://github.com/acme'
    }
    licensing  { enabled = false }
}

Invoking these command

$ gm :archives

Results in the following output

> Task :archives
Total archives: 2

artifact 0
    name: demo
    type: jar
    extension: jar
    date: Sun Jan 24 14:30:57 CET 2021
    file: /tmp/demo/build/libs/demo.jar
artifact 1
    name: demo
    type: jar
    extension: jar
    classifier: javadoc
    date: Sun Jan 24 14:30:57 CET 2021
    file: /tmp/demo/build/libs/demo-javadoc.jar
ClearKordampFileCache

Clears the Kordamp file cache.

Name

clearKordampFileCache

Type

org.kordamp.gradle.plugin.base.tasks.ClearKordampFileCacheTask

Configurations

Displays all configurations available in a project.

Name

configurations

Type

org.kordamp.gradle.plugin.base.tasks.ConfigurationsTask

Example Output

For a project defined as follows

build.gradle
plugins {
    id 'java-library'
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ gm :configurations

Results in the following output

> Task :configurations
Total configurations: 25

configuration 0:
    name: annotationProcessor

configuration 1:
    name: apiElements

configuration 2:
    name: archives

configuration 3:
    name: compile

configuration 4:
    name: compileClasspath

configuration 5:
    name: compileOnly

configuration 6:
    name: default

configuration 7:
    name: implementation

configuration 8:
    name: jacocoAgent

configuration 9:
    name: jacocoAnt

configuration 10:
    name: java2html

configuration 11:
    name: runtime

configuration 12:
    name: runtimeClasspath

configuration 13:
    name: runtimeElements

configuration 14:
    name: runtimeOnly

configuration 15:
    name: signatures

configuration 16:
    name: sourcesElements

configuration 17:
    name: testAnnotationProcessor

configuration 18:
    name: testCompile

configuration 19:
    name: testCompileClasspath

configuration 20:
    name: testCompileOnly

configuration 21:
    name: testImplementation

configuration 22:
    name: testRuntime

configuration 23:
    name: testRuntimeClasspath

configuration 24:
    name: testRuntimeOnly
ConfigurationSettings

Display settings of a Configuration

Name

configurationSettings

Type

org.kordamp.gradle.plugin.base.tasks.ConfigurationSettingsTask

Options
show-paths

Display path information (OPTIONAL).

configuration

The configuration to generate the report for.

configurations

The configurations to generate the report for.

You may specify either of the two, be advised that configurations has precedence over configuration. All configurations will be displayed if neither of these options is specified.

EffectiveSettings

Displays resolved settings

Name

effectiveSettings

Type

org.kordamp.gradle.plugin.base.tasks.EffectiveSettingsTask

Options
section

The section to generate the report for.

sections

The sections to generate the report for.

show-secrets

Show secret values instead of masked values. Value masking is applied to properties that contain any of the following words: secret, password, credential, token, apikey, login. The list of words can be overridden by setting a System property named kordamp.secret.keywords to a comma delimited String, such as password,secret.

You may specify either of the two, be advised that sections has precedence over section. All sections will be displayed if neither of these options is specified. Section names match entries found in the DSL.

Extensions

Displays all extensions applied to a project

Name

effectiveSettings

Type

org.kordamp.gradle.plugin.base.tasks.ExtensionsTask

Example Output

For a project defined as follows

build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ gm :extensions

Results in the following output

> Task :extensions
Total extensions: 12

extension 0:
    name: ext
    type: org.gradle.api.plugins.ExtraPropertiesExtension

extension 1:
    name: defaultArtifacts
    type: org.gradle.api.internal.plugins.DefaultArtifactPublicationSet

extension 2:
    name: config
    type: org.kordamp.gradle.plugin.base.ProjectConfigurationExtension

extension 3:
    name: gradleProjects
    type: org.kordamp.gradle.plugin.base.ProjectsExtension

extension 4:
    name: profiles
    type: org.kordamp.gradle.plugin.profiles.ProfilesExtension

extension 5:
    name: reporting
    type: org.gradle.api.reporting.ReportingExtension

extension 6:
    name: downloadLicenses
    type: nl.javadude.gradle.plugins.license.DownloadLicensesExtension

extension 7:
    name: license
    type: nl.javadude.gradle.plugins.license.LicenseExtension

extension 8:
    name: jacoco
    type: org.gradle.testing.jacoco.plugins.JacocoPluginExtension

extension 9:
    name: coveralls
    type: org.kt3k.gradle.plugin.CoverallsPluginExtension

extension 10:
    name: signing
    type: org.gradle.plugins.signing.SigningExtension

extension 11:
    name: versioning
    type: net.nemerosa.versioning.VersioningExtension
ExtensionSettings

Display settings of an Extension

Name

extensionSettings

Type

org.kordamp.gradle.plugin.base.tasks.ExtensionSettingsTask

Options
show-paths

Display path information (OPTIONAL).

extension

The extension to generate the report for.

extensions

The extensions to generate the report for.

You may specify either of the two, be advised that extensions has precedence over extension. All extensions will be displayed if neither of these options is specified.

ListIncludedBuilds

Lists all included builds in this project

Name

listIncludedBuilds

Type

org.kordamp.gradle.plugin.base.tasks.ListIncludedBuildsTask

Example Output

For a project defined as follows

.
├── build.gradle
└── settings.gradle
settings.gradle
includeBuild '../build1'
includeBuild '../build2'
build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ gm :listIncludedBuilds

Results in the following output

> Task :listIncludedBuilds
Total included builds: 2

build1:
    projectDir: /tmp/build1

build12:
    projectDir: /tmp/build2
ListProjects

Lists all projects

Name

listProjects

Type

org.kordamp.gradle.plugin.base.tasks.ListProjectsTask

Options
absolute

Should paths be printed as absolutes or not. Defaults to false.

Example Output

For a project defined as follows

.
├── build.gradle
├── settings.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    └── project2
        └── project2.gradle
settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'
build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}
subprojects/project1.gradle
apply plugin: 'java'
subprojects/project2.gradle
apply plugin: 'java'

Invoking these command

$ gm :listProjects

Results in the following output

> Task :listProjects
Total projects: 3

sample:
    root: true
    path: :
    projectDir: /tmp/sample
    buildFile: /tmp/sample/build.gradle
    buildDir: /tmp/sample/build

project1:
    path: :project1
    projectDir: subprojects/project1
    buildFile: subprojects/project1/project1.gradle
    buildDir: subprojects/project1/build

project2:
    path: :project2
    projectDir: subprojects/project2
    buildFile: subprojects/project2/project2.gradle
    buildDir: subprojects/project2/build
Package

Assembles the outputs of the project. This is an alias for assemble.

Name

assemble

Type

org.gradle.api.DefaultTask

Plugins

Displays all plugins applied to a project

Name

plugins

Type

org.kordamp.gradle.plugin.base.tasks.PluginsTask

Example Output

For a project defined as follows

build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ gm :plugins

Results in the following output

> Task :plugins
Total plugins: 30

plugin 0:
    id: help-tasks
    version: 8.4
    implementationClass: org.gradle.api.plugins.HelpTasksPlugin

plugin 1:
    id: build-init
    version: 8.4
    implementationClass: org.gradle.buildinit.plugins.BuildInitPlugin

plugin 2:
    id: wrapper
    version: 8.4
    implementationClass: org.gradle.buildinit.plugins.WrapperPlugin

plugin 3:
    id: lifecycle-base
    version: 8.4
    implementationClass: org.gradle.language.base.plugins.LifecycleBasePlugin

plugin 4:
    id: base
    version: 8.4
    implementationClass: org.gradle.api.plugins.BasePlugin

plugin 5:
    id: org.kordamp.gradle.base
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.base.BasePlugin
    enabled: true

plugin 6:
    id: org.kordamp.gradle.profiles
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.profiles.ProfilesPlugin
    enabled: true

plugin 7:
    id: org.kordamp.gradle.build-info
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.buildinfo.BuildInfoPlugin
    enabled: true

plugin 8:
    id: reporting-base
    version: 8.4
    implementationClass: org.gradle.api.plugins.ReportingBasePlugin

plugin 9:
    id: com.github.hierynomus.license-report
    version: 0.15.0
    implementationClass: com.hierynomus.gradle.license.LicenseReportingPlugin

plugin 10:
    id: com.github.hierynomus.license-base
    version: 0.15.0
    implementationClass: com.hierynomus.gradle.license.LicenseBasePlugin

plugin 11:
    id: com.github.hierynomus.license
    version: 0.15.0
    implementationClass: nl.javadude.gradle.plugins.license.LicensePlugin

plugin 12:
    id: org.kordamp.gradle.licensing
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.licensing.LicensingPlugin
    enabled: false

plugin 13:
    id: jacoco
    version: 8.4
    implementationClass: org.gradle.testing.jacoco.plugins.JacocoPlugin

plugin 14:
    id: org.kordamp.gradle.jacoco
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.jacoco.JacocoPlugin
    enabled: true

plugin 15:
    id: com.github.kt3k.coveralls
    version: 2.10.2
    implementationClass: org.kt3k.gradle.plugin.CoverallsPlugin

plugin 16:
    id: org.kordamp.gradle.coveralls
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.coveralls.CoverallsPlugin
    enabled: true

plugin 17:
    id: org.kordamp.gradle.publishing
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.publishing.PublishingPlugin
    enabled: true

plugin 18:
    id: signing
    version: 8.4
    implementationClass: org.gradle.plugins.signing.SigningPlugin

plugin 19:
    id: org.kordamp.gradle.minpom
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.minpom.MinPomPlugin
    enabled: true

plugin 20:
    id: org.kordamp.gradle.jar
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.jar.JarPlugin
    enabled: true

plugin 21:
    id: org.kordamp.gradle.source-jar
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.source.SourceJarPlugin
    enabled: true

plugin 22:
    id: org.kordamp.gradle.source-stats
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.stats.SourceStatsPlugin
    enabled: true

plugin 23:
    id: org.kordamp.gradle.testing
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.testing.TestingPlugin
    enabled: true

plugin 24:
    id: com.github.ben-manes.versions
    version: 0.38.0
    implementationClass: com.github.benmanes.gradle.versions.VersionsPlugin

plugin 25:
    id: org.kordamp.gradle.project
    version: 0.54.0
    implementationClass: org.kordamp.gradle.plugin.project.ProjectPlugin
    enabled: true

plugin 26:
    id: net.nemerosa.versioning
    version: 2.14.0
    implementationClass: net.nemerosa.versioning.VersioningPlugin
ProjectProperties

Displays all properties found in a project

Name

projectProperties

Type

org.kordamp.gradle.plugin.base.tasks.PropertiesTask

Options
section

The section to generate the report for.

show-secrets

Show secret values instead of masked values. Value masking is applied to properties that contain any of the following words: secret, password, credential, token, apikey. The list of words can be overriden by setting a System property named kordamp.secret.keywords to a comma delimited String, such as password,secret.

Valid values for section are: project, ext.

Example Output

For a project defined as follows

~/.gradle/gradle.properties
global_property = global
gradle.properties
version        = 0.0.0
group          = org.kordamp.sample.acme
local_property = local
build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

ext.build_property = 'build'

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ gm :projectProperties -Pproject_property=project

Results in the following output

> Task :projectProperties
project:
    name: sample
    version: 0.0.0
    group: org.kordamp.sample.acme
    path: :
    displayName: root project 'sample'
    projectDir: /tmp/sample
    buildFile: /tmp/sample/build.gradle
    buildDir: /tmp/sample/build

ext:
    build_property: build
    global_property: global
    local_property: local
    project_property: project
Repositories

Displays all repositories used for resolving project dependencies

Name

repositories

Type

org.kordamp.gradle.plugin.base.tasks.RepositoriesTask

Example Output

For a project defined as follows

build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

repositories {
    mavenCentral()
    flatDir { dirs 'lib' }
}

Invoking these command

$ gm :repositories

Results in the following output

> Task :repositories
Total repositories: 2

repository 0:
    type: maven
    name: MavenRepo
    url: https://repo.maven.apache.org/maven2/

repository 1:
    type: flatDir
    name: flatDir
    dirs:
        /tmp/sample/lib
TarSettings

Display TAR settings.

Name

tarSettings

Type

org.kordamp.gradle.plugin.base.tasks.TarSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

TaskSettings

Display settings of a Task

Name

taskSettings

Type

org.kordamp.gradle.plugin.base.tasks.TaskSettingsTask

Options
task

The task to generate the report for.

Verify

Assembles and tests the project. This is an alias for build.

Name

verify

Type

org.gradle.api.DefaultTask

ZipSettings

Display ZIP settings.

Name

zipSettings

Type

org.kordamp.gradle.plugin.base.tasks.ZipSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

7.1.3. Rules

Configurations
Pattern

<ConfigurationName>ConfigurationSettings

Type

org.kordamp.gradle.plugin.base.tasks.ConfigurationSettingsTask

Extensions
Pattern

<ExtensionName>ExtensionSettings

Type

org.kordamp.gradle.plugin.base.tasks.ExtensionSettingsTask

Tars
Pattern

<TarName>TarSettings

Type

org.kordamp.gradle.plugin.base.tasks.TarSettingsTask

Tasks
Pattern

<TaskName>TaskSettings

Type

org.kordamp.gradle.plugin.base.tasks.TaskSettingsTask

Zips
Pattern

<ZipName>ZipSettings

Type

org.kordamp.gradle.plugin.base.tasks.ZipSettingsTask

7.2. Bom

id

org.kordamp.gradle.bom

class

org.kordamp.gradle.plugin.bom.BomPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
maven-publish,
signing

Configures a MavenPublication for the project using the core maven-publish plugin. The name of the publication matches "main".

Data defined in the DSL’s config.info and config.license blocks will be used to fill out information required by the generated BOM file. Artifacts will be automatically signed if the uploadArchives task is present.

7.2.1. Example

Using the following project layout as an example

.
├── build.gradle
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
├── docs
│   └── guide
│       ├── guide.gradle
│       └── src
│           └── docs
│               ├── asciidoc
│               └── resources
└── subprojects
    ├── sample-bom
    │   └── sample-bom.gradle
    ├── project1
    │   ├── project1.gradle
    │   └── src
    │       └── main
    └── project2
        ├── project2.gradle
        └── src
            └── main

With the following content set in the sample-bom.gradle build file

sample-bom.gradle (child)
apply plugin: 'org.kordamp.gradle.bom'

config {
    bom {
        exclude('guide')
    }
}
sample-bom.gradle.kts (child)
apply(plugin = "org.kordamp.gradle.bom")

config {
    bom {
        exclude("guide")
    }
}

Results in the following BOM when invoking gradle :sample-bom:publish

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.kordamp.sample.acme</groupId>
  <artifactId>sample-bom</artifactId>
  <version>0.0.0</version>
  <packaging>pom</packaging>
  <name>Sample</name>
  <description>sample-bom</description>
  <url>https://github.com/joecool/sample</url>
  <inceptionYear>2018</inceptionYear>
  <licenses>
    <license>
      <name>Apache-2.0</name>
      <url>https://spdx.org/licenses/Apache-2.0.html</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  <developers>
    <developer>
      <id>joecool</id>
      <name>Joe Cool</name>
      <roles>
        <role>developer</role>
      </roles>
    </developer>
  </developers>
  <scm>
    <url>https://github.com/joecool/sample.git</url>
  </scm>
  <properties>
    <sample.version>0.0.0</sample.version>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.kordamp.sample.acme</groupId>
        <artifactId>project1</artifactId>
        <version>${sample.version}</version>
      </dependency>
      <dependency>
        <groupId>org.kordamp.sample.acme</groupId>
        <artifactId>project2</artifactId>
        <version>${sample.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

7.2.2. DSL

config {
    bom {
        autoIncludes
        enabled
        dependencies
        excludes
        includes
        properties
        parent
        overwriteInceptionYear
        overwriteUrl
        overwriteLicenses
        overwriteScm
        overwriteOrganization
        overwriteDevelopers
        overwriteContributors
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.bom plugin if false

autoIncludes

boolean

no

true

Disables default inclusion of all projects

dependencies

Map<String, Dependency>

no

[:]

Dependencies that should be added to the BOM

excludes

Set<String>

no

[]

Names of subprojects that should not be included

includes

Set<String>

no

[]

Names of subprojects that should be included

properties

Map<String, String>

no

[:]

Maps to <properties> block.

parent

String

no

Defines the coordinates of the parent POM

overwriteInceptionYear

boolean

no

false

Overwrite <inceptionYear> from parent POM

overwriteUrl

boolean

no

false

Overwrite <url> from parent POM

overwriteLicenses

boolean

no

false

Overwrite <licenses> from parent POM

overwriteScm

boolean

no

false

Overwrite <scm> from parent POM

overwriteOrganization

boolean

no

false

Overwrite <organization> from parent POM

overwriteDevelopers

boolean

no

false

Overwrite <developers> from parent POM

overwriteContributors

boolean

no

false

Overwrite <contributors> from parent POM

The format for parent may be any of the following ones:

  • Plain name of a project within the same multi-project, i.e. kordamp-core.

  • Project path within the same multi-project, i.e. :kordamp-core.

  • Full maven coordinates, i.e. org.kordamp:kordamp-core:1.2.3.

This block is optional.

Methods
exclude(String)

Skips the named project from being added to the BOM.

include(String)

Adds the named project to the BOM.

dependency(String gavNotation)

Defines a dependency. Argument must use the groupId:artifactId:version notation. Dependency name will be equal to artifactId.
Example:

dependency('com.googlecode.guava:guava:29.0-jre')
dependency(String name, String gavNotation)

Defines a dependency. Second argument must use the groupId:artifactId:version notation.
Example:

dependency('guava', 'com.googlecode.guava:guava:29.0-jre')
dependency(String name, String gavNotation, Action action)

Defines and configures a dependency. Second argument must use the groupId:artifactId:version notation.
Example:

dependency('groovy', 'org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
dependency(String name, String gavNotation, Closure action)

Defines and configures a dependency. Second argument must use the groupId:artifactId:version notation.
Example:

dependency('groovy', 'org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
platform(String gavNotation)

Defines a platform dependency. Argument must use the groupId:artifactId:version notation. Dependency name will be equal to artifactId.
Example:

platform('io.micronaut:micronaut-bom:2.0.2')
platform(String name, String gavNotation)

Defines a platform dependency. Second argument must use the groupId:artifactId:version notation.
Example:

platform('micronaut', 'io.micronaut:micronaut-bom:2.0.2')
dependency(String gavNotation, Action action)

Defines and configures a dependency by name.
Example:

dependency('org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
dependency(String gavNotation, Closure action)

Defines and configures a dependency by name.
Example:

dependency('org.codehaus.groovy:groovy:3.0.6') {
    modules = [
        'groovy-test',
        'groovy-json',
        'groovy-xml'
    ]
}
getDependency(String name)

Returns the named dependency (if it exists). Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

getDependency('guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
getDependency('com.googlecode.guava:guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependency(String nameOrGa)

Finds a dependency by name or GA if it exists, null otherwise.
Example:

findDependency('guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependency('com.googlecode.guava:guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependencyByName(String name)

Finds a dependency by name if it exists, null otherwise.
Example:

findDependencyByName('guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
findDependencyByGA(String name, String moduleNAme)

Finds a dependency by groupId and artifactId if it exists, null otherwise.
Example:

findDependencyByGA('com.googlecode.guava', 'guava') instanceof org.kordamp.gradle.plugin.base.model.artifact.Dependency
getPlatform(String name)

Returns the named platform (if it exists). Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the platform.
Example:

getPlatform('micronaut') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
getPlatform('io.micronaut:micronaut-bom') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatform(String nameOrGa)

Returns the named platform (if it exists). The nameOrGa parameter may be the logical name or the groupId:artifactId of the platform.
Example:

findPlatform('micronaut') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatform('io.micronaut:micronaut-bom') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatformByName(String name)

Finds a platform by name if it exists, null otherwise.
Example:

findPlatformByName('micronaut') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
findPlatformByGA(String name, String moduleNAme)

Finds a platform by groupId and artifactId if it exists, null otherwise.
Example:

findPlatformByGA('io.micronaut', 'micronaut-bom') instanceof org.kordamp.gradle.plugin.base.model.artifact.Platform
gav(String name)

Returns the given dependency in GAV notation if it exists. Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

gav('groovy') == 'org.codehaus.groovy:groovy:3.0.6'
gav('org.codehaus.groovy:groovy') == 'org.codehaus.groovy:groovy:3.0.6'
gav(String name, String moduleName)

Returns the given module dependency in GAV notation if it exists. Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

gav('groovy', 'groovy-json') == 'org.codehaus.groovy:groovy-json:3.0.6'
gav('org.codehaus.groovy:groovy', 'groovy-json') == 'org.codehaus.groovy:groovy-json:3.0.6'
ga(String name, String moduleName)

Returns the given module dependency in GA (groupId/artifactId) notation if it exists. Throws an exception otherwise.
The name parameter may be the logical name or the groupId:artifactId of the dependency.
Example:

ga('micronaut', 'micronaut-core') == 'io.micronaut:micronaut-core'
ga('io.micronaut:micronaut-bom', 'micronaut-core') == 'io.micronaut:micronaut-core'
Instances of type org.kordamp.gradle.plugin.base.model.artifact.Dependency or org.kordamp.gradle.plugin.base.model.artifact.Platform can not be passed directly to Gradle’s dependency resolution mechanism. You must convert them to any of the accepted notations such as groupId:artifactId:version, use the gav() or ga() utility methods instead.

7.3. BuildInfo

id

org.kordamp.gradle.build-info

class

org.kordamp.gradle.plugin.buildinfo.BuildInfoPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
net.nemerosa.versioning

applied by

org.kordamp.gradle.jar
org.kordamp.gradle.project
org.kordamp.gradle.publishing

Defines a set of build related properties. These properties are

Name Type Description

buildDate

String

The value of current timestamp formatted with "yyyy-MM-dd"

buildTime

String

The value of current timestamp formatted with "HH:mm:ss.nZ"

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]

buildOs

String

Concatenation of the following System properties [os.name, os.version, os.arch]

buildCreatedBy

String

The Gradle version used in the build

These properties are consumed by the org.kordamp.gradle.jar plugin when enhancing the MANIFEST.MF file of generated JARs.

7.3.1. DSL

config {
    buildInfo {
        enabled
        useCommitTimestamp
        skipBuildBy
        skipBuildDate
        skipBuildTime
        skipBuildRevision
        skipBuildJdk
        skipBuildOs
        skipBuildCreatedBy
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.build-info plugin if false

useCommitTimestamp

boolean

no

true

Uses the latest commit time instead of the current time

skipBuildBy

boolean

no

false

Skips calculating this value

skipBuildDate

boolean

no

false

Skips calculating this value

skipBuildTime

boolean

no

false

Skips calculating this value

skipBuildRevision

boolean

no

false

Skips calculating this value

skipBuildJdk

boolean

no

false

Skips calculating this value

skipBuildOs

boolean

no

false

Skips calculating this value

skipBuildCreatedBy

boolean

no

false

Skips calculating this value

7.4. Checkstyle

id

org.kordamp.gradle.checkstyle

class

org.kordamp.gradle.plugin.checkstyle.CheckstylePlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
checkstyle

Configures Checkstyle on Java projects and aggregate reports on the root project.

7.4.1. DSL

config {
    quality {
        checkstyle {
            enabled
            ignoreFailures
            includes
            excludes
            configFile
            configProperties
            maxErrors
            maxWarnings
            showViolations
            toolVersion
            excludedSourceSets
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.checkstyle plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

configFile

Set<String>

no

configProperties

Map<String, Object>

no

[:]

maxErrors

int

no

0

maxWarnings

int

no

Integer.MAX_VALUE

showViolations

boolean

no

yes

toolVersion

String

no

10.12.4

excludedSourceSets

Set<String>

no

[]

The value of configFile will be automatically calculated based on the following rules

  • Explicit value if set in the build file, with ${sourceSetName} as suffix.

  • Explicit value if set in the build file.

  • config/checkstyle/${project.name}-${sourceSetName}.xml

  • config/checkstyle/${project.name}.xml

  • config/checkstyle/checkstyle-${sourceSetName}.xml

  • config/checkstyle/checkstyle.xml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.4.2. Tasks

AggregateCheckstyle

Aggregates all checkstyle reports for all projects.
Consumes settings from config.quality.checkstyle.
This task is added to the root project.

Name

aggregateCheckstyle

Type

org.gradle.api.plugins.quality.Checkstyle

Properties
reports.html.destination

${project.buildDir}/reports/checkstyle/aggregate.html

reports.xml.destination

${project.buildDir}/reports/checkstyle/aggregate.xml

AllCheckstyle

Aggregates all checkstyle reports for a single project.
Consumes settings from config.quality.checkstyle.

Name

allCheckstyle

Type

org.gradle.api.plugins.quality.Checkstyle

Properties
reports.html.destination

${project.buildDir}/reports/checkstyle/${project.name}.html

reports.xml.destination

${project.buildDir}/reports/checkstyle/${project.name}.xml

InitCheckstyle

Creates a default Checkstyle configuration file.

Name

initCheckstyle

Type

org.kordamp.gradle.plugin.checkstyle.tasks.InitCheckstyleTask

Properties
destinationDir

${rootProject.projectDir}/config/checkstyle

overwrite

Overwrite existing file if there’s a match

7.5. Codenarc

id

org.kordamp.gradle.codenarc

class

org.kordamp.gradle.plugin.codenarc.CodenarcPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
codenarc

Configures Codenarc on Groovy projects and aggregate reports on the root project.

7.5.1. DSL

config {
    quality {
        codenarc {
            enabled
            ignoreFailures
            configFile
            maxPriority1Violations
            maxPriority2Violations
            maxPriority3Violations
            toolVersion
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.codenarc plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

configFile

Set<String>

no

maxPriority1Violations

int

no

maxPriority2Violations

int

no

maxPriority3Violations

int

no

toolVersion

String

no

3.3.0

excludedSourceSets

Set<String>

no

[]

The value of configFile will be automatically calculated based on the following rules

  • Explicit value if set in the build file, with ${sourceSetName} as suffix.

  • Explicit value if set in the build file.

  • config/codenarc/${project.name}-${sourceSetName}.groovy

  • config/codenarc/${project.name}.groovy

  • config/codenarc/codenarc-${sourceSetName}.groovy

  • config/codenarc/codenarc.groovy

  • config/codenarc/${project.name}-${sourceSetName}.xml

  • config/codenarc/${project.name}.xml

  • config/codenarc/codenarc-${sourceSetName}.xml

  • config/codenarc/codenarc.xml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.5.2. Tasks

AggregateCodenarc

Aggregates all codenarc reports for all projects.
Consumes settings from config.quality.codenarc.
This task is added to the root project.

Name

aggregateCodenarc

Type

org.gradle.api.plugins.quality.CodeNarc

Properties
reports.html.destination

${project.buildDir}/reports/codenarc/aggregate.html

reports.xml.destination

${project.buildDir}/reports/codenarc/aggregate.xml

AllCodenarc

Aggregates all codenarc reports for a single project.
Consumes settings from config.quality.codenarc.

Name

allCodenarc

Type

org.gradle.api.plugins.quality.CodeNarc

Properties
reports.html.destination

${project.buildDir}/reports/codenarc/${project.name}.html

reports.xml.destination

${project.buildDir}/reports/codenarc/${project.name}.xml

InitCodenarc

Creates a default Codenarc configuration file.

Name

initCodenarc

Type

org.kordamp.gradle.plugin.codenarc.tasks.InitCodenarcTask

Properties
destinationDir

${rootProject.projectDir}/config/codenarc

overwrite

Overwrite existing file if there’s a match

7.6. Coveralls

id

org.kordamp.gradle.coveralls

class

org.kordamp.gradle.plugin.coveralls.CoverallsPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
com.github.kt3k.coveralls

applied by

org.kordamp.gradle.project

Configures Coveralls on the root project.

All projects with tasks of type org.gradle.testing.jacoco.tasks.JacocoReport contribute to the sourceDirs property of the coveralls extension. The output of the aggregateJacocoReport is used as input for the coveralls task. The coveralls task will execute only if System.getenv().CI || System.getenv().GITHUB_ACTIONS.

7.6.1. DSL

config {
    coverage {
        coveralls {
            enabled
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.coveralls plugin if false

standalone

boolean

no

false

Disables dependency on :aggregateJacocoReport if true

7.7. Echo

id

org.kordamp.gradle.echo

class

org.kordamp.gradle.plugin.echo.EchoPlugin (groovydoc, source)

Outputs content during a build.

7.7.1. Tasks

Echo

Outputs content during a build.

Name

echo

Type

org.kordamp.gradle.plugin.echo.tasks.EchoTask

Properties
message

The message to write. Value can be provided with project/System property or environment variable. Project/System property: echo.message. Environment Variable: ECHO_MESSAGE.

7.8. Error Prone

id

org.kordamp.gradle.errorprone

class

org.kordamp.gradle.plugin.errorprone.ErrorPronePlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
net.ltgt.errorprone

Configures ErrorProne on Java projects (applies all settings to tasks of type JavaCompile.

7.8.1. DSL

config {
    quality {
        errorprone {
            enabled
            args
            disableAllChecks
            allErrorsAsWarnings
            allDisabledChecksAsWarnings
            disableWarningsInGeneratedCode
            ignoreUnknownCheckNames
            ignoreSuppressionAnnotations
            compilingTestOnlyCode
            excludedPaths
            errorProneVersion
            errorProneJavacVersion
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.errorprone plugin if false

args

List<String>

no

[]

Additional arguments to be passed to the ErrorProne javac plugin

disableAllChecks

boolean

no

false

allErrorsAsWarnings

boolean

no

false

allDisabledChecksAsWarnings

boolean

no

false

disableWarningsInGeneratedCode

boolean

no

true

ignoreUnknownCheckNames

boolean

no

false

ignoreSuppressionAnnotations

boolean

no

false

compilingTestOnlyCode

boolean

no

false

excludedPaths

String

no

errorProneVersion

String

no

2.23.0

errorProneJavacVersion

String

no

9+181-r4173-1

7.9. FunctionalTest

id

org.kordamp.gradle.functional-test

class

org.kordamp.gradle.plugin.functionaltest.FunctionalTestPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Responsibilities:

  • Create two additional configurations: functionalTestImplementation and functionalTestRuntimeOnly. These configurations extend from imlementation and runtimeOnly respectively.

  • Create a SourceSet named functionalTest pointing to ${config.testing.functional.baseDir}/[java|groovy].

  • Create a Test task named functionalTest pointing to ${config.testing.functional.baseDir}/[java|groovy].

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

You must add testing dependencies to functionalTestImplementation as this configuration is independent from testImplementation.

7.10. GroovyProject

id

org.kordamp.gradle.groovy-project

class

org.kordamp.gradle.plugin.project.groovy.GroovyProjectPlugin (groovydoc, source)

applies

org.kordamp.gradle.java-project

Configures a project with Groovy conventions.

This plugin adds the following plugins to the classpath without applying them:

7.10.1. Tasks

GroovyCompilerSettings

Display Groovy compiler settings.

Name

groovyCompilerSettings

Type

org.kordamp.gradle.plugin.project.groovy.tasks.GroovyCompilerSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

7.10.2. Rules

CompileGroovy
Pattern

compile<SourceSetName>GroovySettings

Type

org.kordamp.gradle.plugin.project.groovy.tasks.GroovyCompilerSettingsTask

7.11. Groovydoc

id

org.kordamp.gradle.groovydoc

class

org.kordamp.gradle.plugin.groovydoc.GroovydocPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
groovy

applied by

org.kordamp.gradle.groovy-project

Generates and packages Groovydoc documentation.

7.11.1. DSL

config {
    docs {
        groovydoc {
            enabled
            empty
            includes
            excludes
            replaceJavadoc
            options {
                windowTitle
                docTitle
                header
                footer
                overviewText
                links
                noTimestamp
                noVersionStamp
                includePrivate
                use
            }
            aggregate {
                enabled
                empty
                fast
                replaceJavadoc
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.groovydoc plugin if false

empty

boolean

no

false

Generates an empty JAR if true.

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

options

Name Type Required Default Value Description

windowTitle

String

no

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

docTitle

String

no

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

header

String

no

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

footer

String

no

overviewText

TextResource

no

links

Set<Link>

no

The default value contains links to the target Java and latest Groovy javadocs.

noTimestamp

boolean

no

noVersionStamp

boolean

no

includePrivate

boolean

no

true

use

boolean

no

true

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

empty

boolean

no

false

Generates an empty JAR if true.

fast

boolean

no

true

Does not execute child groovydoc tasks if true

replaceJavadoc

boolean

no

false

Disables aggregateJavadoc and applies the javadoc classifier

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.11.2. Tasks

AggregateGroovydoc

Aggregates Groovy API docs for all projects.
Consumes settings from config.groovydoc defined in the root project.
This task is added to the root project.

Name

aggregateGroovydoc

Type

org.gradle.api.tasks.javadoc.Groovydoc

Properties
destinationDir

${rootProject.buildDir}/docs/aggregate-groovydoc

AggregateGroovydocJar

An archive of the aggregate Groovy API docs.
This task is added to the root project.

Name

aggregateGroovydocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

groovydoc

destinationDir

${rootProject.buildDir}/build/libs

Groovydoc

Generates Groovydoc API documentation.
Consumes settings from config.groovydoc.

Name

groovydoc

Type

org.gradle.api.tasks.javadoc.Groovydoc

Properties
destinationDir

${project.buildDir}/docs/groovydoc

GroovydocJar

An archive of the Groovydoc API docs.

Name

groovydocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

groovydoc | javadoc

destinationDir

${project.buildDir}/build/libs

from

groovydoc.destinationDir

7.12. Guide

id

org.kordamp.gradle.guide

class

org.kordamp.gradle.plugin.guide.GuidePlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
org.kordamp.gradle.javadoc, (on root project)
org.kordamp.gradle.groovydoc, (on root project)
org.asciidoctor.jvm.convert

Generates a User Manual or Guide with Asciidoctor as the source format. Applies the org.asciidoctor.jvm.convert plugin.

The following attributes will be added to the default asciidoctor task if they have no explicit value defined:

Name Value

toc

'left'

doctype

'book'

icons

'font'

encoding

'utf-8'

sectlink

true

sectanchors

true

numbered

true

linkattrs

true

imagesdir

'images' (src/docs/resources/images)

linkcss

true

source-highlighter

'coderay'

coderay-linenums-mode

'table'

project-title

config.info.description

project-inception-year

config.info.inceptionYear

project-copyright-year

config.info.copyrightYear

project-author

config.info.resolveAuthors().join(', ')

project-url

config.info.url

project-scm

config.info.links.scm

project-issue-tracker

config.info.links.issueTracker

project-group

project.group

project-version

project.version

project-name

rootProject.name

build-by

rootProject.ext.buildinfo.buildBy

build-date

rootProject.ext.buildinfo.buildDate

build-time

rootProject.ext.buildinfo.buildTime

build-revision

rootProject.ext.buildinfo.buildRevision

build-jdk

rootProject.ext.buildinfo.buildJdk

build-created-by

rootProject.ext.buildinfo.buildCreatedBy

7.12.1. DSL

config {
    docs {
        guide {
            enabled
            publish {
                enabled
                branch
                message
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.guide plugin if false

publish

Name Type Required Default Value Description

enabled

boolean

no

false

Disables publication of guide if false

branch

String

no

'gh-pages'

Git branch

message

String

no

"Publish guide for ${project.version}"

Commit message

7.12.2. Extension

guide {
    javadocApiDir
    groovydocApiDir
}
Name Type Required Default Value Description

javadocApiDir

String

no

'api'

Director where javadoc will be copied

groovydocApiDir

String

no

'gapi'

Director where groovydoc will be copied

7.12.3. Tasks

InitGuide

Initializes directories and files required by the guide.

Name

initGuide

Type

org.gradle.api.DefaultTask

Properties
destinationDir

${project.projectDir}/src/docs/asciidoc

CreateGuide

Creates an Asciidoctor based guide. Depends on the output of the following tasks:

  • asciidoctor

  • aggregateJavadoc (if enabled)

  • aggregateGroovydoc (if enabled)

Name

createGuide

Type

org.gradle.api.tasks.Copy

Properties
destinationDir

${project.buildDir}/guide

from

${project.tasks.asciidoctor.outputDir}/html5

ZipGuide

An archive of the generated guide.

Name

zipGuide

Type

org.gradle.api.tasks.bundling.Zip

Properties
destinationDir

${project.buildDir}/distributions

from

${project.tasks.createGuide.destinationDir}

7.13. Inline

id

org.kordamp.gradle.inline

class

org.kordamp.gradle.plugin.inline.InlinePlugin (groovydoc, source)

This plugin should be applied to settings.gradle(.kts) only!

Enables invocation of any Gradle plugin by providing GAV coordinates plus a given task name. Core Gradle plugins are also supported in which case you only have to specify their plugin id, not their GAV coordinates.

The following formats for including plugins are supported:

  1. pluginId:task where pluginId is either a core Gradle plugin or an aliased plugin.

  2. pluginId:version:task where pluginId is a core Gradle plugin or an aliased plugin.

  3. groupId:artifactId:version:task.

  4. groupId:artifactId:task where version will be set as latest.release.

Aliased plugins require an additional resource that identifies their groupId and artifactId coordinates. This resource may be placed inside $HOME/.gradle/org.kordamp.gradle.inline/ as a properties file. The name of the file identifies the groupId. Every key in the file defines a pluginId while the value is the matching artifactId.

The following example shows how the jbang-gradle-plugin may be configured to take advantage of this feature

$HOME/.gradle/org.kordamp.gradle.inline/dev.jbang.properties
dev.jbang=jbang-gradle-plugin

Additionaly this plugin will also search the classpath for resources at META-INF/org.kordamp.gradle.inline that follow the same rules as above. Given that order matters it’s possible to define sorting order for all resolved groupIds by defining a value for the org.kordamp.gradle.inline.plugin.groups System property, which is a comma separated list of groupIds.

The inline plugin chooses the target Project on which plugins will be applied based on the following rules:

  • If the inline.target System property is set:

    • All projects if the value is all.

    • All projects except root if value is subprojects.

    • Project(s) whose name or path matches the value (exactly or as regex). Value may be command separated.

  • The project whose projectDir matches the start parameter -p or --project-dir when given.

  • The project whose buildFile matches the start parameter -b or --build-file when given.

  • The project whose projectDir matches the current directory.

  • The root project.

Plugin properties, such as those exposed by extensions added by plugins, may be adapted so that their values may be supplied using System and/or project properties. These are the default property adapters provided by the org.kordamp.gradle.inline plugin:

ApplicationPluginPropertyAdapter

Adapts the application plugin. Supported properties are:

  • application.mainClass - requires Gradle 6.4+; aliased to exec.mainClass.

  • application.mainModule - requires Gradle 6.4+

  • application.mainClassName - aliased to exec.mainClass.

  • application.applicationDefaultJvmArgs - aliased to exec.args.

Custom property adapters may be added to the classpath. Such adapters must implement PropertyAdapter and be registered as a service in META-INF/services/org.kordamp.gradle.plugin.inline.PropertyAdapter.

This plugin also lets you invoke tasks prefixed by a project path regex, in which case all projects whose paths match the given regex will be affected by the given goal.

7.13.1. Flags

The following flags may be set using System properties to alter the behavior of this plugin

org.kordamp.gradle.inline.enabled

Disable all capabilities of this plugin if set to false. Default is true.

org.kordamp.gradle.inline.project.regex

Disable evaluation of project regexes if set to false. Default is true.

org.kordamp.gradle.inline.plugins

Disable inlining plugins if set to false. Default is true.

org.kordamp.gradle.inline.adapt

Disable adapting task properties with PropertyAdapter instances if set to false. Default is true.

org.kordamp.gradle.inline.plugin.groups

List of groupIds to be queried in order for resolving pluginId aliases.

7.13.2. Example

Invoking the echo plugin

$ gm org.kordamp.gradle:echo-gradle-plugin:0.54.0:echo -Decho.message="Hello World"

Invoking the latest release of the echo plugin

$ gm org.kordamp.gradle:echo-gradle-plugin:echo -Decho.message="Hello World"

Invoking a given release of the echo plugin using an alias

$ gm org.kordamp.gradle.echo:0.54.0:echo -Decho.message="Hello World"

Invoking the latest release of the echo plugin using an alias

$ gm org.kordamp.gradle.echo:echo -Decho.message="Hello World"

Invoking the application plugin

$ gm application:run -Dapplication.mainClass=com.acme.Main

Invoking the distZip goal on all projects that have -app in their paths

$ gm :*-app:distZip

7.13.3. Plugin Aliases

The following are the aliases for all Kordamp plugins, some of which are not included in this plugin suite

META-INF/org.kordamp.gradle.inline/org.kordamp.gradle.properties
org.kordamp.gradle.base=base-gradle-plugin
org.kordamp.gradle.bom=bom-gradle-plugin
org.kordamp.gradle.buildinfo=buildinfo-gradle-plugin
org.kordamp.gradle.checkstyle=checkstyle-gradle-plugin
org.kordamp.gradle.codenarc=codenarc-gradle-plugin
org.kordamp.gradle.coveralls=coveralls-gradle-plugin
org.kordamp.gradle.echo=echo-gradle-plugin
org.kordamp.gradle.errorprone=errorprone-gradle-plugin
org.kordamp.gradle.functionaltest=functionaltest-gradle-plugin
org.kordamp.gradle.groovy-project=groovy-project-gradle-plugin
org.kordamp.gradle.groovydoc=groovydoc-gradle-plugin
org.kordamp.gradle.guide=guide-gradle-plugin
org.kordamp.gradle.integrationtest=integrationtest-gradle-plugin
org.kordamp.gradle.jacoco=jacoco-gradle-plugin
org.kordamp.gradle.jandex=jandex-gradle-plugin
org.kordamp.gradle.jar=jar-gradle-plugin
org.kordamp.gradle.java-project=java-project-gradle-plugin
org.kordamp.gradle.javadoc=javadoc-gradle-plugin
org.kordamp.gradle.jdeprscan=jdeprscan-gradle-plugin
org.kordamp.gradle.jdeps=jdeps-gradle-plugin
org.kordamp.gradle.licensing=licensing-gradle-plugin
org.kordamp.gradle.livereload=livereload-gradle-plugin
org.kordamp.gradle.markdown=markdown-gradle-plugin
org.kordamp.gradle.minpom=minpom-gradle-plugin
org.kordamp.gradle.oci=oci-gradle-plugin
org.kordamp.gradle.plugin=plugin-gradle-plugin
org.kordamp.gradle.pmd=pmd-gradle-plugin
org.kordamp.gradle.profiles=profiles-gradle-plugin
org.kordamp.gradle.project-enforcer=enforcer-gradle-plugin
org.kordamp.gradle.project=project-gradle-plugin
org.kordamp.gradle.publishing=publishing-gradle-plugin
org.kordamp.gradle.sonar=sonar-gradle-plugin
org.kordamp.gradle.source=source-gradle-plugin
org.kordamp.gradle.sourcestats=sourcestats-gradle-plugin
org.kordamp.gradle.spotbugs=spotbugs-gradle-plugin
org.kordamp.gradle.testing=testing-gradle-plugin
org.kordamp.gradle.yguard=yguard-gradle-plugin

7.14. Insight

id

org.kordamp.gradle.insight

class

org.kordamp.gradle.plugin.insight.InsightPlugin (groovydoc, source)

This plugin should be applied to settings.gradle(.kts) only!

Records information about the build and outputs reports at the end of the build.

7.14.1. DSL

insight {
    enabled

    colors {
        success
        failure
        skipped
        partial
    }

    report(Class<T extends BuildReport) {
        // report configuring action
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Whether report generation is enabled or not.

The enabled state may be set directly in the build file or using:

  • INSIGHT_ENABLED environment variable

  • insight.enabled System property or project property.

colors

Name Type Required Default Value Description

success

String

no

green

Color to use when state is SUCCESS

failure

String

no

red

Color to use when state is FAILURE

skipped

String

no

yellow

Color to use when state is SKIPPED

partial

String

no

cyan

Color to use when state is PARTIAL

Valid values are [black, red, green, yellow, blue, magenta, cyan, white].

Reports must implement the org.kordamp.gradle.plugin.insight.model.BuildReport interface. A report of type org.kordamp.gradle.plugin.insight.reports.SummaryBuildReport will be configured by default if no other reports are explicitly configured.

7.14.2. Reports

SummaryBuildReport

org.kordamp.gradle.plugin.insight.reports.SummaryBuildReport accepts the following configuration properties:

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables this report.

format

String

no

short

Displays project and task counts. Valid values are [short, long].

zeroPadding

boolean

no

false

Output 0 characters in task table.

maxProjectPathSize

int

no

36

Maximum size for displaying project path.

confTimeThreshold

double

no

0.5d

Time threshold used to flag slow configuration (in seconds).

execTimeThreshold

double

no

120d

Time threshold used to flag slow execution (in seconds).

displayProjectThreshold

int

no

2

Display project count threshold.

Project State

A Project may be in any of the following states:

SUCCESS

All its tasks succeeded.

FAILURE

At least one of its task failed.

SKIPPED

None of its tasks were executed.

PARTIAL

Some tasks were executed.

Formats
Short

The short format displays:

  • project path

  • project configuration time

  • project execution time.

Figure 1. shows a successful build for a project with 4 submodules

build summary short1
Figure 1. $ gm build

Figure 2. shows a failed build where a failed test in project1 prevents other projects from being executed

build summary short2
Figure 2. $ gm build

Figure 3. shows the same failure but project2 and project3 are marked as PARTIAL because some of their tasks were invoked.

build summary short3
Figure 3. $ gm clean build

Figure 4. shows another project where a subset of modules was invoked. The griffon-javafx project has long running tests and hit the default execution threshold of 2 minutes

build summary short4
Figure 4. $ gm :griffon-javafx:test
Long

The long format displays the same information as the short format plus a table of task states.

TOT

Total number of tasks in the project.

EXE

Number of tasks executed.

FLD

Number of tasks failed.

SKP

Number of tasks skipped.

UTD

Number of tasks that are up to date.

WRK

Number of tasks that did work.

CHD

Number of tasks retrieved from cache.

NSR

Number of tasks with no source.

ACT

Number of actionable tasks.

Examples

Figure 5. shows a successful build for a project with 4 submodules

build summary long1
Figure 5. $ gm build

Figure 6. shows a failed build where a failed test in project1 prevents other projects from being executed

build summary long2
Figure 6. $ gm build

Figure 7. shows the same failure but project2 and project3 are marked as PARTIAL because some of their tasks were invoked.

build summary long3
Figure 7. $ gm clean build

7.15. IntegrationTest

id

org.kordamp.gradle.integration-test

class

org.kordamp.gradle.plugin.integrationtest.IntegrationTestPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Responsibilities:

  • Create two additional configurations: integrationTestImplementation and integrationTestRuntimeOnly. These configurations extend from testImplementation and testRuntimeOnly respectively.

  • Create a SourceSet named integrationTest pointing to ${config.testing.integration.baseDir}/[java|groovy].

  • Create a Test task named integrationTest pointing to ${config.testing.integration.baseDir}/[java|groovy].

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

7.16. JaCoCo

id

org.kordamp.gradle.jacoco

class

org.kordamp.gradle.plugin.jacoco.JacocoPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
jacoco

applied by

org.kordamp.gradle.project

Configures JaCoCo on all subprojects that contains tests.
Configures aggregate reports on the root project.

7.16.1. DSL

config {
    coverage {
        jacoco {
            enabled
            aggregateExecFile
            aggregateReportHtmlFile
            aggregateReportXmlFile
            additionalSourceDirs
            additionalClassDirs
            toolVersion
            excludes
            includeProjectDependencies
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.jacoco plugin if false

aggregateExecFile

File

no

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

Location for the aggregate merge execution data file

aggregateReportHtmlFile

File

no

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

Location for aggregate HTML reports

aggregateReportXmlFile

File

no

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

Location for the aggregate XML report

additionalSourceDirs

FileCollection

no

[]

Additional source directories

additionalClassDirs

FileCollection

no

[]

Additional class directories

toolVersion

String

no

0.8.11

excludes

Set<String>

no

[]

includeProjectDependencies

boolean

no

false

The value for enabled will automatically be set to false if no tests (unit, integration, or functional) are found.

If includeProjectDependencies is set to true then class files from all projects that have been set as dependencies will also be included in the generated report. This setting applies for individual projects and is ignored on aggregate root reports as all project sources are already taken into account.

This block is optional.

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

7.16.2. Tasks

AggregateJacocoMerge

Aggregates all execution data into a single file.
Consumes settings from config.jacoco defined in the root project.
This task is added to the root project.

Name

aggregateJacocoMerge

Type

org.gradle.testing.jacoco.tasks.JacocoMerge

Properties
destinationFile

config.docs.jacoco.aggregateExecFile

AggregateJacocoReport

Aggregates all coverage reports into a single report.
Consumes settings from config.jacoco defined in the root project.
This task is added to the root project.

Name

aggregateJacocoReport

Type

org.gradle.testing.jacoco.tasks.JacocoReport

Properties
reports.html.destination

config.docs.jacoco.aggregateReportHtmlFile

reports.xml.destination

config..jacoco.aggregateReportXmlFile

reports.html.enabled

true

reports.xml.enabled

true

AllJacocoReports

Executes all JaCoCo reports found in a project (unit, integration, functional, etc).

Name

allTests

Type

org.gradle.api.DefaultTask

Jacoco<Test>Report

Generates code coverage report for a task of type Test.

Name

jacoco<Name>Report, where Name stands for the name of the matching Test task.

Type

org.gradle.testing.jacoco.tasks.JacocoReport

Properties
additionalSourceDirs

jacoco.additionalSourceDirs

sourceDirectories

jacoco.additionalSourceDirs

classDirectories

jacoco.additionalClassDirs

executionData

testTask

reports.html.destination

"${project.reporting.baseDir.path}/jacoco/${testTask.name}/html"

reports.xml.destination

"${project.reporting.baseDir.path}/jacoco/${testTask.name}/jacocoTestReport.xml"

reports.csv.enabled

false

reports.html.enabled

true

reports.xml.enabled

true

7.17. Jar

id

org.kordamp.gradle.Jar

class

org.kordamp.gradle.plugin.jar.JarPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
org.kordamp.gradle.build-info,
org.kordamp.gradle.minpom

applied by

org.kordamp.gradle.project
org.kordamp.gradle.publishing

Configures additional Manifest entries and files in the META-INF directory.

Any files that match LICENSE* will be added to META-INF automatically.

If config.minpom.enabled is true then the outputs of the minpom task will be mapped to META-INF/maven/${project.group}/${project.name}.

If config.release is true then the following entries are added to the Manifest of all generated JAR files:

Created-By

rootProject.extensions.config.buildInfo.buildCreatedBy

Built-By

rootProject.extensions.config.buildInfo.buildBy

Build-Jdk

rootProject.extensions.config.buildInfo.buildJdk

Build-Date

rootProject.extensions.config.buildInfo.buildDate

Build-Time

rootProject.extensions.config.buildInfo.buildTime

Build-Revision

rootProject.extensions.config.buildInfo.buildRevision

Build-Jdk-Spec

System.getProperty('java.specification.version')

If config.release is true and config.info.specification is enabled then the following entries are also added to the Manifest of all generated JAR files

Specification-Title

config.info.specification.title

Specification-Version

config.info.specification.version

Specification-Vendor

config.info.specification.vendor

If config.release is true and config.info.implementation is enabled then the following entries are also added to the Manifest of all generated JAR files

Implementation-Title

config.info.implementation.title

Implementation-Version

config.info.implementation.version

Implementation-Vendor

config.info.implementation.vendor

7.17.1. Reproducible Builds

It’s worth noting that enriching JAR manifests with environment and/or temporary related data will result in non-reproducible builds. All elements calculated by the otg.kordamp.gradle.buildInfo plugin will affect build reproducibility (except for buildRevision). You can disable any of these values from being injected by configuring a skip flag that matches the particular value to be skipped.

You may also skip checks on the Manifest file with the following

build.gradle
normalization {
    runtimeClasspath {
        ignore('/META-INF/MANIFEST.MF')
    }
}
build.gradle.kts
normalization {
    runtimeClasspath {
        ignore("/META-INF/MANIFEST.MF")
    }
}

Check out the org.kordamp.gradle.reproducible for additional settings required to ensure artifacts are reproducible.

7.17.2. DSL

config {
    artifacts {
        jar {
            enabled
            manifest {
                enabled
                addClasspath
                classpathPrefix
                classpathLayoutType
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.jar plugin if false

This block is optional.

manifest

Name Type Required Default Value Description

enabled

boolean

no

false

Enables or disables manifest customizations

addClasspath

boolean

no

false

Whether to create a Class-Path manifest entry

classpathPrefix

String

no

''

A text that will be prefixed to all Class-Path entries

classpathLayoutType

String

no

simple

The type of layout to use when formatting entries in the created Class-Path. Valid values are: [simple, repository] (the same as a Maven classpath layout)

7.18. JavaProject

id

org.kordamp.gradle.java-project

class

org.kordamp.gradle.plugin.project.java.JavaProjectPlugin (groovydoc, source)

applies

org.kordamp.gradle.project

applied by

org.kordamp.gradle.groovy-project

Configures a project with Java conventions.

This plugin adds the following plugins to the classpath without applying them:

7.18.1. Configurations

Optional

A configuration that behaves like Maven’s <optional> flag. Dependencies added to this configuration will be available to compileClasspath and runtimeClasspath but won’t be exported in the generated POM.

7.18.2. Extensions

applyToDefaults

Configures platform dependencies based on settings available from config.dependencyManagement. Since Gradle 6 platform dependencies must be applied per configuration, which results in verbose build files when a BOM/platform should be applied in common configurations. This extension lets you apply a BOM/platform to multiple configurations with a single method call. The following configurations will be used:

  • api

  • implementation

  • annotationProcessor

  • testImplementation

  • testAnnotationProcessor

  • compileOnly

  • testCompileOnly

  • runtimeOnly

  • testRuntimeOnly

Name

applyToDefaults

Type

org.kordamp.gradle.plugin.project.DefaultConfigurationsDependencyHandler

Applied to

org.gradle.api.artifacts.dsl.DependencyHandler

Methods
void platform(Object notation)

Declares a dependency on a platform.

void platform(Object notation, Action<? super Dependency> action)

Declares and configures a dependency on a platform.

void enforcedPlatform(Object notation)

Declares a dependency on an enforced platform.

void enforcedPlatform(Object notation, Action<? super Dependency> action)

Declares and configures a dependency on an enforced platform.

Where notation may be one of

  • java.lang.CharSequence with format groupId:artifactId:version.

  • java.util.Map with group, artifactId, version keys.

  • java.lang.CharSequence with the name of a platform declared in config.dependencyManagement.

Example

The following example shows how the Micronaut BOM can be used to configure all configurations

build.gradle
config {
    dependencyManagement {
        platform('micronaut', "io.micronaut:micronaut-bom:$micronautVersion")
    }
}

dependencies {
    applyToDefaults.enforcedPlatform('micronaut')

    // The following dependencies can now be resolved by their respective configurations
    // without specifying a version as the 'micronaut' platform will provide it
    annotationProcessor('io.micronaut:micronaut-inject-java')
    annotationProcessor('io.micronaut:micronaut-validation')
    api('io.micronaut:micronaut-validation')
    compileOnly('io.micronaut:micronaut-inject-groovy')
}
applyTo

Configures platform, module, and regular dependencies based on settings available from config.dependencyManagement.

Name

applyTo

Type

org.kordamp.gradle.plugin.project.ConfigurationsDependencyHandler

Applied to

org.gradle.api.artifacts.dsl.DependencyHandler

Methods
DependencyHandlerSpec configuration(String configuration)

Declares the target configuration on which platforms and dependencies will be applied

DependencyHandlerSpec configurations(String configuration, String…​ configurations)

Declares target configurations on which platforms and dependencies will be applied.

DependencyHandlerSpec configurations(Set<String> configurations)

Declares target configurations on which platforms and dependencies will be applied.

DependencyHandlerSpec c(String configuration)

Declares the target configuration on which platforms and dependencies will be applied.
Alias for configuration(configuration).

DependencyHandlerSpec c(String configuration, String…​ configurations)

Declares target configurations on which platforms and dependencies will be applied.
Alias for configurations(configuration,configurations).

DependencyHandlerSpec c(Set<String> configurations)

Declares target configurations on which platforms and dependencies will be applied.
Alias for configurations(configurations).

DependencyHandlerSpec has the following methods

void platform(Object notation)

Declares a dependency on a platform.

void platform(Object notation, Action<? super Dependency> action)

Declares and configures a dependency on a platform.

void enforcedPlatform(Object notation)

Declares a dependency on an enforced platform.

void enforcedPlatform(Object notation, Action<? super Dependency> action)

Declares and configures a dependency on an enforced platform.

void dependency(String nameOrGav)

Declares a dependency.

void dependency(String nameOrGav, Closure)

Declares and configures a dependency.

void module(String nameOrGa)

Declares a module dependency (from a platform).

void module(String nameOrGa, Closure)

Declares and configures a module dependency (from a platform).

Where notation may be one of

  • java.lang.CharSequence with format groupId:artifactId:version.

  • java.util.Map with group, artifactId, version keys.

  • java.lang.CharSequence with the name of a platform declared in config.dependencyManagement.

Example

The following example shows how the Micronaut BOM can be used to configure all configurations

build.gradle
config {
    dependencyManagement {
        dependency('junit:junit:4.13')
        platform('micronaut', "io.micronaut:micronaut-bom:$micronautVersion")
    }
}

dependencies {
    applyToDefaults.enforcedPlatform('micronaut')

    // The following dependencies can now be resolved by their respective configurations
    // without specifying a version as the 'micronaut' platform will provide it

    applyTo.configuration('annotationProcessor').module('micronaut', 'micronaut-inject-java')
    // apply to both annotationProcessor & api
    applyTo.c('annotationProcessor', 'api').module('micronaut', 'micronaut-validation')
    applyTo.c('api').module('micronaut', 'micronaut-runtime-groovy')
    applyTo.c('testImplementation').dependency('junit')
    // undeclared dependencies require the use of groupId:artifactId:version
    applyTo.c('testImplementation').dependency('org.hamcrest:hamcrest-core:2.2')
}

7.18.3. Tasks

Compile

Assembles main classes. This is an alias for classes.

Name

classes

Type

org.gradle.api.DefaultTask

JarSettings

Display JAR settings.

Name

jarSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.JarSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

JavaCompilerSettings

Display Java compiler settings.

Name

javaCompilerSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.JavaCompilerSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

Platforms

Displays all configured platforms in the project. Requires the use of the applyTo or applyToDefaults extensions.

Name

platforms

Type

org.kordamp.gradle.plugin.project.java.tasks.platformsTask

Example Output

For a project with the following dependencies

build.gradle
dependencies {
    applyToDefaults.enforcedPlatform("io.micronaut:micronaut-bom:$micronautVersion")

    annotationProcessor 'io.micronaut:micronaut-inject-java'
    annotationProcessor 'io.micronaut:micronaut-validation'

    compileOnly 'io.micronaut:micronaut-inject-groovy'

    api 'io.micronaut:micronaut-inject'
    api 'io.micronaut:micronaut-validation'
    api 'io.micronaut:micronaut-runtime-groovy'
}

Invoking this command

$ gm :platforms

Results in the following output

> Task :platforms
Total platforms: 1

Platform 0:
    platform: io.micronaut:micronaut-bom:2.0.2
    enforced: true
    configurations:
        api
        implementation
        annotationProcessor
        testImplementation
        testAnnotationProcessor
        compileOnly
        testCompileOnly
        runtimeOnly
        testRuntimeOnly
SourceSets

Displays all sourceSets available in a project.

Name

sourceSets

Type

org.kordamp.gradle.plugin.project.java.tasks.SourceSetsTask

Example Output

For a project defined as follows

build.gradle
plugins {
    id 'java-library'
    id 'org.kordamp.gradle.project' version '0.54.0'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking this command

$ gm :sourceSets

Results in the following output

> Task :sourceSets
Total sourceSets: 2

sourceSet 0:
    name: main

sourceSet 1:
    name: test
SourceSetSettings

Display settings of a SourceSet

Name

sourceSetSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.SourceSetSettingsTask

Options
show-paths

Display path information (OPTIONAL).

sourceSet

The sourceSet to generate the report for.

sourceSets

The sourceSets to generate the report for.

You may specify either of the two, be advised that sourceSets has precedence over sourceSet. All sourceSets will be displayed if neither of these options is specified.

TestSettings

Display test task settings.

Name

testSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.TestSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

WarSettings

Display WAR settings.

Name

warSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.WarSettingsTask

Options
show-paths

Display path information (OPTIONAL).

task

The task to generate the report for.

tasks

The tasks to generate the report for.

You may specify either of the two, be advised that tasks has precedence over task. All tasks will be displayed if neither of these options is specified.

7.18.4. Rules

CompileJava
Pattern

compile<SourceSetName>JavaSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.JavaCompilerSettingsTask

Jars
Pattern

<JarName>JarSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.JarSettingsTask

JavaExec
Pattern

<TaskName>Settings

Type

org.kordamp.gradle.plugin.project.java.tasks.JavaExecSettingsTask

SourceSets
Pattern

<SourceSetName>SourceSetSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.SourceSetSettingsTask

Tests
Pattern

<SourceSetName>TestSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.TestSettingsTask

Wars
Pattern

<WarName>JarSettings

Type

org.kordamp.gradle.plugin.project.java.tasks.WarSettingsTask

7.19. Javadoc

id

org.kordamp.gradle.javadoc

class

org.kordamp.gradle.plugin.javadoc.JavadocPlugin (javadoc, source)

applies

org.kordamp.gradle.base

applied by

org.kordamp.gradle.groovydoc
org.kordamp.gradle.java-project

Generates and packages Javadoc documentation.

7.19.1. DSL

config {
    docs {
        javadoc {
            enabled
            empty
            copyDocFiles
            includes
            excludes
            title
            options { ... }
            autoLinks {
                enabled
                configurations
                excludes
                useJavadocIo
                linksOffline
            }
            aggregate {
                enabled
                empty
                fast
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.javadoc plugin if false

empty

boolean

no

false

Generates an empty JAR if true.

copyDocFiles

boolean

no

true

Copies files found in doc-files subdirectories inside source folders.

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

title

String

no

options

MinimalJavadocOptions

no

Supports all options from StandardJavadocDocletOptions.

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

This block is optional.

Name Type Required Default Value Description

enabled

boolean

no

true

Disables generation of auto links if false

configurations

List<String>

no

['api', 'implementation', 'compileOnly', 'annotationProcessor', 'runtimeOnly']

Configurations to be checked for dependencies

excludes

Set<String>

no

[]

Dependencies to be excluded. Format: '${artifactId}-${version}'

useJavadocIo

boolean

no

true

Resolve links against https://static.javadoc.io/

Methods
void exclude(String)

Adds a link exclusion rule (Regex pattern).

void offlineLink(String, String)

Adds an offline link definition. The first argument is for the string to be embedded in the <a href> links, and the second tells the javadoc tool where to find either the package-list or element-list file.

Offline links are automatically calculated for project dependencies using absolute paths. These paths are skipped when the release flag is set to true.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

empty

boolean

no

false

Generates an empty JAR if true.

fast

boolean

no

true

Does not execute child javadoc tasks if true

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.19.2. Tasks

AggregateJavadoc

Aggregates Javadoc API docs for all projects.
Consumes settings from config.javadoc defined in the root project.
This task is added to the root project.

Name

aggregateJavadoc

Type

org.gradle.api.tasks.javadoc.Javadoc

Properties
destinationDir

${rootProject.buildDir}/docs/aggregate-javadoc

AggregateJavadocJar

An archive of the aggregate Javadoc API docs.
This task is added to the root project.

Name

aggregateJavadocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

javadoc

destinationDir

${rootProject.buildDir}/build/libs

Checks if generated Javadoc auto links are reachable.

Name

checkAutoLinks

Type

org.kordamp.gradle.plugin.javadoc.CheckAutoLinksTask

Javadoc

Generates Javadoc API documentation.
Consumes settings from config.javadoc.

Name

javadoc

Type

org.gradle.api.tasks.javadoc.Javadoc

Properties
destinationDir

${project.buildDir}/docs/javadoc

JavadocJar

An archive of the Javadoc API docs.

Name

javadocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

javadoc

destinationDir

${project.buildDir}/build/libs

from

javadoc.destinationDir

7.20. Licensing

id

org.kordamp.gradle.licensing

class

org.kordamp.gradle.plugin.licensing.LicensingPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
com.github.hierynomus.license

applied by

org.kordamp.gradle.project

Configures license checks and reports on the target project.
Configures aggregate license reports on the root project.

7.20.1. DSL

config {
    licensing {
        enabled
        includes
        excludes
        mappings
        excludedSourceSets
        licenses {
            inherits
            mergeStrategy
            license {
                id
                primary
                name
                url
                distribution
                comments
                aliases
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.licensing plugin if false

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

mappings

Map<String, String>

no

[:]

excludedSourceSets

Set<String>

no

[]

licenses

LicenseSet

yes

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

inherits

boolean

no

true

Whether to inherit values from a parent POM.

mergeStrategy

MergeStrategy

no

UNIQUE

One of PREPEND, APPEND, UNIQUE, OVERWRITE.

The value of inherits cannot be changed once it has been set.

The values of mergeStrategy control how multiple licenses will be handled

PREPEND

Child values (if any) will be placed before inherited values (if any).

APPEND

Child values (if any) will be placed after inherited values (if any).

UNIQUE

Child and inherited values will be merged by license id.

OVERWRITE

Child values will be used unless empty, in which case inherited values will be used.

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

license

Name Type Required Default Value Description

id

String

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. The value of id may be any of org.kordamp.gradle.plugin.base.model.LicenseId, including the literal values for the spdx property.
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 on that set will be treated as the primary license.

7.20.2. Example

Configuring the Apache Software License 2.0 can be done in the following way

build.gradle
config {
    licensing {
        licenses {
            license {
                id = 'Apache-2.0'
            }
        }
    }
}
build.gradle.kts
config {
    licensing {
        licenses {
            license {
                id = "Apache-2.0"
            }
        }
    }
}

Configuring a custom license can be done in the following way

build.gradle
config {
    licensing {
        licenses {
            license {
                name = 'Custom License'
                url  = 'http://www.acme.com/license.txt'
            }
        }
    }
}
build.gradle.kts
config {
    licensing {
        licenses {
            license {
                name = "Custom License"
                url  = "http://www.acme.com/license.txt"
            }
        }
    }
}

7.20.3. Extensions

LicenseExtension

This extension is added by the com.github.hierynomus.license plugin, enhanced with the following data

header

project.rootProject.file('gradle/LICENSE_HEADER') strictCheck::true

mapping.java

'SLASHSTAR_STYLE'

mapping.groovy

'SLASHSTAR_STYLE'

mapping.kt

'SLASHSTAR_STYLE'

mapping.scala

'SLASHSTAR_STYLE'

mapping.gradle

'SLASHSTAR_STYLE'

mapping.kts

'SLASHSTAR_STYLE'

mapping.yml

'SCRIPT_STYLE'

mapping.toml

'SCRIPT_STYLE'

The following extra properties become available to license templates

project

project.name

projectName

config.info.name

copyrightYear

config.info.copyrightYear

author

config.info.resolveAuthors().join(', ')

license

primaryLicense.id?.spdx()

The following exclusions patterns are added by default: '**/*.png', 'META-INF/services/*'.

DownloadLicensesExtension

This extension is added by the com.github.hierynomus.license plugin, enhanced with the following license aliases:

The Apache Software License, Version 2.0

The Apache Software License, Version 2.0, The Apache Software License, version 2.0, Apache Software License - Version 2.0, Apache Software License - version 2.0, the Apache License, ASL Version 2.0, The Apache License, Version 2.0, The Apache License Version 2.0, Apache License, Version 2.0, Apache License, version 2.0, Apache License Version 2.0, Apache License version 2.0, The Apache License 2.0, Apache 2.0 License, Apache License 2.0, Apache 2.0, Apache-2.0, Apache 2

Eclipse Public License v1.0

Eclipse Public License - Version 1.0, Eclipse Public License v1.0, Eclipse Public License 1.0, Eclipse Public License, EPL v1.0, EPL 1.0, EPL-1.0

Eclipse Public License v2.0

Eclipse Public License v2.0, Eclipse Public License 2.0, EPL v2.0, EPL 2.0, EPL-2.0

GNU Lesser General Public License v2.1 or later

GNU Library General Public License v2.1 or later, GNU Lesser General Public License v2.1 or later, GNU Lesser General Public License, Version 2.1, LGPL 2.1, LGPL-2.1

MIT License

The MIT License, The MIT license, MIT License, MIT license, MIT

BSD 2-Clause FreeBSD License

BSD 2-Clause FreeBSD License, The BSD License, The BSD license

BSD 3-Clause "New" or "Revised" License

BSD 3-Clause "New" or "Revised" License, 3-Clause BSD License, 3-Clause BSD license, Revised BSD License, Revised BSD license, BSD Revised License, BSD Revised license, New BSD License, New BSD license, BSD New License, BSD New license, BSD 3-Clause, BSD 3-clause

7.20.4. Tasks

AggregateLicenseReport

Generates an aggregate license report.
This task is added to the root project.

Name

aggregateLicenseReport

Type

org.kordamp.gradle.plugin.licensing.AggregateLicenseReportTask

Properties
outputDir

${rootProject.reporting.baseDir.path}/license

LicenseFormatGradle

Formats all Gradle build files (Groovy/Kotlin).

Name

licenseFormatGradle

Type

com.hierynomus.gradle.license.tasks.LicenseCheck

LicenseGradle

Checks the license header of all Gradle build files (Groovy/Kotlin).

Name

licenseFormatGradle

Type

com.hierynomus.gradle.license.tasks.LicenseFormat

LicenseFormatMaven

Formats all Maven build files (pom.xml).

Name

licenseFormatMaven

Type

com.hierynomus.gradle.license.tasks.LicenseCheck

LicenseMaven

Checks the license header of all Maven build files (pom.xml).

Name

licenseFormatMaven

Type

com.hierynomus.gradle.license.tasks.LicenseFormat

7.21. Minpom

id

org.kordamp.gradle.minpom

class

org.kordamp.gradle.plugin.minpom.MinPomPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

applied by

org.kordamp.gradle.jar
org.kordamp.gradle.project

Generates a minimum POM file and a companion pom.properties file that are usually packaged in the main JAR produced by the project.

7.21.1. Example

For a project defined as follows

Groovy
plugins {
    id 'groovy'
    id 'org.kordamp.gradle.minpom' version '0.54.0'
}

group   = 'com.acme'
version = '1.0.0'

dependencies {
    api 'org.codehaus.groovy:groovy-all:2.5.3'
}
Kotlin
plugins {
    `groovy`
    id("org.kordamp.gradle.minpom") version "0.54.0"
}

group   = "com.acme"
version = "1.0.0"

dependencies {
    api("org.codehaus.groovy:groovy-all:2.5.3")
}

Produces the following output

sample/build/pom/maven/pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.acme</groupId>
    <artifactId>sample</artifactId>
    <version>1.0.0</version>
    <dependencies>
        <dependency>
            <groupId>org.codehaus.groovy</groupId>
            <artifactId>groovy-all</artifactId>
            <version>2.5.3</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</project>
sample/build/pom/maven/pom.properties
# Generated by Gradle 8.4
version=1.0.0
groupId=com.acme
artifactId=sample

7.21.2. DSL

config {
    artifacts {
        minpom {
            enabled
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.minpom plugin if false

This block is optional.

7.21.3. Tasks

Minpom

Generates a minimum POM file.

Name

minpom

Type

org.kordamp.gradle.plugin.minpom.MinpomTask

Properties
projectArtifactId

project.name

projectGroupId

project.group

projectVersion

project.version

destinationDir

${project.buildDir}/pom/maven

7.22. Plugins

id

org.kordamp.gradle.plugin

class

org.kordamp.gradle.plugin.plugin.PluginPlugin (groovydoc, source)

applies

org.kordamp.gradle.base
java-gradle-plugin
com.gradle.publish-plugin

Configures a Gradle plugin project with java-gradle-plugin and publish-plugin using data defined in the info block of the config DSL. Artifacts will be automatically signed if the uploadArchives task is present.

This plugin must be explicitly applied to Gradle plugin projects only.

7.22.1. DSL

config {
    plugins {
        enabled
        plugin {
            id
            name
            description
            displayName
            implementationClass
            tags
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.plugin plugin if false

plugin

Name

Type

Required

Default Value

Description

id

String

yes

Defines the plugin’s id

name

String

yes

Defines the plugin’s name

description

String

no

Defines the plugin’s description

displayName

String

no

Defines the plugin’s display name

implementationClass

String

yes

Defines the plugin’s implementation Class

tags

List<String>

no

[]

This block defines a single plugin entry. You may define as many plugins as needed.

7.22.2. Tasks

ListPluginDescriptors

Lists plugin descriptors from plugin declarations.

Name

listPluginDescriptors

Type

org.kordamp.gradle.plugin.plugin.ListPluginDescriptorsTask

7.23. Pmd

id

org.kordamp.gradle.pmd

class

org.kordamp.gradle.plugin.pmd.PmdPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
pmd

Configures Pmd on Java projects and aggregate reports on the root project.

7.23.1. DSL

config {
    quality {
        pmd {
            enabled
            ignoreFailures
            ruleSetFiles
            incrementalAnalysis
            rulePriority
            toolVersion
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.pmd plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

ruleSetFiles

FileCollection

no

incrementalAnalysis

boolean

no

false

rulePriority

int

no

5

excludedSourceSets

Set<String>

no

[]

toolVersion

String

no

6.55.0

The value of ruleSetFiles will be automatically calculated based on the following rules

  • Explicit value if set in the build file, with ${sourceSetName} as suffix.

  • Explicit value if set in the build file.

  • config/pmd/${project.name}-${sourceSetName}.xml

  • config/pmd/${project.name}.xml

  • config/pmd/pmd-${sourceSetName}.xml

  • config/pmd/pmd.xml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.23.2. Tasks

AggregatePmd

Aggregates all pmd reports for all projects.
Consumes settings from config.quality.pmd.
This task is added to the root project.

Name

aggregatePmd

Type

org.gradle.api.plugins.quality.Pmd

Properties
reports.html.destination

${project.buildDir}/reports/pmd/aggregate.html

reports.xml.destination

${project.buildDir}/reports/pmd/aggregate.xml

AllPmd

Aggregates all pmd reports for a single project.
Consumes settings from config.quality.pmd.

Name

allPmd

Type

org.gradle.api.plugins.quality.Pmd

Properties
reports.html.destination

${project.buildDir}/reports/pmd/${project.name}.html

reports.xml.destination

${project.buildDir}/reports/pmd/${project.name}.xml

InitPmd

Creates a default Pmd configuration file.

Name

initPmd

Type

org.kordamp.gradle.plugin.pmd.tasks.InitPmdTask

Properties
destinationDir

${rootProject.projectDir}/config/pmd

overwrite

Overwrite existing file if there’s a match

7.24. Profiles

id

org.kordamp.gradle.profiles

class

org.kordamp.gradle.plugin.profiles.ProfilesPlugin (groovydoc, source)

applied by

org.kordamp.gradle.project

Provides conditional configuration blocks, similar to Apache Maven’s build profiles. Configuration blocks are applied immediately when their activation condition is met.

Are profiles really needed?

This is a question that many Gradle users have asked themselves, specially if coming from Maven. On the surface profiles are just a way to conditionally enable blocks of configuration. Given that Gradle relies on full programmatic DSLs (Groovy or Kotlin) one would think that profile support such as this is superfluous, just use a series of if conditions and move on.

True. Except when those conditions are

  • More complex than merely checking the existence of a project property.

  • Repeated in project after project in a given team or organization.

  • Subject to enviromental activation (OS, JDK, etc).

In this case a custom plugin is likely to emerge, thus the existence of this plugin. Besides, this plugin provides newcomers form Maven with a similar experience to get started off the ground. Later one can move to more idiomatic Gradle ways if the facilities provided bny this plugin prove to be too constrained or inadecuate.

7.24.1. DSL

profiles {
    profile(String) {
        activation {
            os { ... }
            jdk { ... }
            file { ... }
            property { ... }
            custom { ... }
        }
        allActivations {
            os { ... }
            jdk { ... }
            file { ... }
            property { ... }
            custom { ... }
        }
        anyActivations {
            os { ... }
            jdk { ... }
            file { ... }
            property { ... }
            custom { ... }
        }
        action {
            // regular project configuration
        }
    }
}

These are the rules that govern the DSL:

  • Every profile must have an unique id.

  • Only one of activation, allActivations, or anyActivations should be defined. In the case that multiple definitions were to be present, the last one overrides any previous blocks.

  • Every activation in allActivations must be true to activate the profile.

  • The first activation in anyActivations that evaluates to true will activate the profile.

  • Profiles may define no activations. They can only be activated by id.

  • There is no default profile activation like there is in Maven.

  • Profiles must have an action.

7.24.2. Activations

There are 5 types of activations available in the profiles DSL

os
os {
    name
    arch
    version
    release
    classifier
    classifierWithLikes
}

Where each property defines elements to be matched (exactly or as regex)

name

The expected OS name. Type = String.

arch

The expected OS architecture. Type = String.

version

The expected OS version. Type = String.

release

The expected OS release (Linux). Type = String.

classifier

The expected OS classifier. Type = String.

classifierWithLikes

Additional classifiers. Type = List<String>.

jdk
jdk {
    version
}
version

The version number to match. It may be a version prefix, such as 1.8, or a version range, such as [1.7,1.8). Type = String.

file
file {
    exists
    missing
}
exists

The given file must exist. Type = RegularFile.

missing

The given file must not exist. Type = RegularFile.

custom
custom {
    activation { Project p ->
        // custom condition against Project p
    }
}
property
property {
    key
    value
}
key

The name of the property (required). Type = String.

value

The value of the property (optional). Type = String.

Usage rules:

  • This activation block can match environment variables, system properties, and/or project properties.

  • Environment variables are always uppercased and require env. as prefix in the key.

  • System properties require systemProp. as prefix in the key.

  • Project properties names are used as is in the key.

  • If the value is omitted then the activation only checks for the existence of the key. If the key is prefixed by a ! then the condition is inverted, i.e, the activation checks that the key does not exist.

  • If the value is given then the property’s value must match it. If the value is prefixed with a ! then the given value must not match.

Examples:

Environment variable SECRET_TOKEN must exist
property {
    key = 'env.SECRET_TOKEN'
}
System property server_ip must not exist
property {
    key = '!systemProp.server_ip'
}
Project property must match value
property {
    key   = 'region'
    value = 'Frankfurt'
}
Project property must not match value
property {
    key   = 'release'
    value = '!false'
}

7.24.3. Explicit Activation

Profiles can be explicitly activated on the command line when their id is supplied as a project property. This will bypass their activation condition if they happen to have one. This behavior can be triggered by setting a project property named profile whose value is a comma separated list of profile ids.

Example
profiles {
    profile('jdk9') {
        activation {
            jdk { version = '9' }
        }
        action { ... }
    }
    profile('jdk11') {
        activation {
            jdk { version = '11' }
        }
        action { ... }
    }
    profile('test') {
        action { ... }
    }
    profile('prod') {
        action { ... }
    }
}

The following command invocations have these results:

Builds with jdk9 and prod profiles
gm -Pprofile=jdk9,prod build
Builds with jdk11 profile only
gm -Pprofile=jdk11 build

In both cases the test profile remains inactive.

7.24.4. System Properties

profiles.enabled

Disables or enables the whole profiles block. Default is true.

7.24.5. Tasks

ActiveProfiles

Displays all profiles that have been activated with the current configuration.

Name

activeProfiles

Type

org.kordamp.gradle.plugin.profiles.tasks.ActiveProfilesTask

DisplayActivationInfo

Displays information used for profile activation.

Name

displayActivationInfo

Type

org.kordamp.gradle.plugin.profiles.tasks.DisplayActivationInfoTask

ListProfiles

Displays all configured profiles regardless of their activation state.

Name

listProfiles

Type

org.kordamp.gradle.plugin.profiles.tasks.ListProfilesTask

Example Output
$ gm :displayActivationInfo

> Task :displayActivationInfo
JDK:
    version: 1.8.0-191
    major: 1
    minor: 8
    incremental: 0
    build: 191
    qualifier: null
OS:
    name: osx
    arch: x86_64
    version: 10.14
    classifier: osx-x86_64

This information can be used in conjuction with the gradle-enforcer-plugin to match the RequireJavaVersion and RequireOs rules.

7.25. Project

Serves as central point of configuration for a project as it applies all dependent plugins. You may skip this plugin and apply plugins individually as needed.

This plugin adds the following plugins to the classpath without applying them:

7.25.1. Tasks

CopyDependencies

Copies dependencies for a given configuration.

Name

copyDependencies

Type

org.kordamp.gradle.plugin.project.tasks.CopyDependenciesTask

Options
configuration

The name of the configuration (REQUIRED).

layout

The layout type (OPTIONAL). Valid values are [flat, default].

includes

Comma separated artifact patterns, e.g, <groupId>:<artifactId>:<version>:<classifier>

excludes

Comma separated artifact patterns, e.g, <groupId>:<artifactId>:<version>:<classifier>

Properties
configuration

The name of the configuration (REQUIRED).

layout

The layout type (OPTIONAL). Valid values are [flat, default].

outputDirectory

The target directory where artifacts will be written to. Defaults to ${buildDir}/dependencies/${layout}.

includes

Artifact patterns, e.g, <groupId>:<artifactId>:<version>:<classifier>

excludes

Artifact patterns, e.g, <groupId>:<artifactId>:<version>:<classifier>

Artifact pattern examples:
  • org.apache.maven

  • org.apache.maven:badArtifact

  • org.apache.maven:artifact:badVersion

  • org.apache.maven:*:1.2 (exclude version 1.2 and above, equivalent to [1.2,) )

  • org.apache.maven:*:[1.2] (explicit exclude of version 1.2)

  • org.apache.maven:*:*:test

  • org.apache.*:maven-*:*

7.26. Properties

id

org.kordamp.gradle.properties

class

org.kordamp.gradle.plugin.properties.PropertiesPlugin (groovydoc, source)

This plugin should be applied to settings.gradle(.kts) only!

Enables additional property source files with YAML and TOML formats.

Property source files can be placed at any place where you would typically find the standard gradle.properties file, such as

  • $GRADLE_HOME/

  • $USER_HOME/.gradle/

  • $project.projectDir/

Following the convention set by the standard gradle.properties file, these are the only file names accepted for automatically processing additional property source files:

  • gradle.yml

  • gradle.toml

7.26.1. DSL

The following DSL applies to properties on projects. Property files will be automatically read and applied to settings.ext once the plugin is applied to settings.gradle. If you’d like to skip the YAML or TOML files then define a System property yaml.enabled or toml.enabled with false as value.

properties {
    yaml {
        enabled
        overwrite
    }
    toml {
        enabled
        overwrite
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables processing of the target format.

overwrite

boolean

no

true

Whether to overwrite existing properties or not.

You may use the systemProp prefix to declare a System property instead of a project property, just like it’s done for properties defined in gradle.properties.

7.27. Publishing

id

org.kordamp.gradle.publishing

class

org.kordamp.gradle.plugin.publishing.PublishingPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
org.kordamp.gradle.build-info,
org.kordamp.gradle.jar,
org.kordamp.gradle.minpom,
org.kordamp.gradle.source-jar
maven-publish,
signing

applied by

org.kordamp.gradle.project

Configures a MavenPublication for the project’s artifacts using the core maven-publish plugin. The name of the publication matches "main". Published artifacts include the main JAR, sources, javadoc/groovydoc JARs.

Data defined in the DSL’s config.info and config.licensing blocks will be used to fill out information required by the generated POM file.

7.27.1. DSL

config {
    publishing {
        enabled
        releasesRepository
        snapshotsRepository
        publications
        scopes
        flattenPlatforms
        useVersionExpressions
        signing {
            enabled
            keyId
            secretKey
            password
        }
        pom  {
            properties
            parent
            overwriteInceptionYear
            overwriteUrl
            overwriteLicenses
            overwriteScm
            overwriteOrganization
            overwriteDevelopers
            overwriteContributors
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.publishing plugin if false

releasesRepository

String

no

Name of a Maven compatible repository for publishing releases

snapshotsRepository

String

no

Name of a Maven compatible repository for publishing snapshots

publications

List<String>

no

[]

Publication names to be included

scopes

List<String>

no

[]

Maven scopes to be added to generated POM. If no value then defaults to ['compile', 'runtime']

flattenPlatforms

boolean

no

false

Expand dependencies imported from platforms and skip adding platforms to <dependencyManagement>

useVersionExpressions

boolean

no

true

Substitute dependency version numbers with version expressions added to <properties>

This block is optional.

signing

Name Type Required Default Value Description

enabled

boolean

no

false

Disables artifact signing if false

keyId

String

no

The public key ID (The last 8 symbols of the keyId. You can use gpg -K to get it)

secretKey

String

no

Ascii armored secret key used for signing

password

String

no

The passphrase used to protect the private key

If signing is set to true and no other properties are set then the signatory is expected to be set by conventional means explained at Signatory credentials.

If both secretKey and password are set then the signatory will use an in-memory ascii-armored key.

If keyId, secretKey, and password are set then the signatory will use an in-memory ascii-armored OpenPGP subkey.

pom

Name Type Required Default Value Description

packaging

String

no

jar

Defines the value for <packaging>

properties

Map<String, String>

no

[:]

Maps to <properties> block.

parent

String

no

Defines the coordinates of the parent POM

overwriteInceptionYear

boolean

no

false

Overwrite <inceptionYear> from parent POM

overwriteUrl

boolean

no

false

Overwrite <url> from parent POM

overwriteLicenses

boolean

no

false

Overwrite <licenses> from parent POM

overwriteScm

boolean

no

false

Overwrite <scm> from parent POM

overwriteOrganization

boolean

no

false

Overwrite <organization> from parent POM

overwriteDevelopers

boolean

no

false

Overwrite <developers> from parent POM

overwriteContributors

boolean

no

false

Overwrite <contributors> from parent POM

The format for parent may be any of the following ones:

  • Plain name of a project within the same multi-project, i.e. kordamp-core.

  • Project path within the same multi-project, i.e. :kordamp-core.

  • Full maven coordinates, i.e. org.kordamp:kordamp-core:1.2.3.

This block is optional.

7.27.2. Example

Publishing signed artifacts to Maven Central.

build.gradle
config {
    info {
        repositories {
            repository {
                name = 'mavenRelease'
                url  = 'https://oss.sonatype.org/service/local/staging/deploy/maven2/'
                credentials {
                    username = ...
                    password = ...
                }
            }
            repository {
                name = 'mavenSnapshot'
                url  = 'https://oss.sonatype.org/content/repositories/snapshots/'
                credentials {
                    username = ...
                    password = ...
                }
            }
        }
    }

    publishing {
        signing {
            enabled = true
        }
        releasesRepository  = 'mavenRelease'
        snapshotsRepository = 'mavenSnapshot'
    }
}

7.27.3. Tasks

PublicationSettings

Display publication configuration

Name

publicationSettings

Type

org.kordamp.gradle.plugin.publishing.PublicationSettingsTask

Options
absolute

Should paths be printed as absolutes or not. Defaults to 'false' (OPTIONAL).

publication

The publication to generate the report for.

publications

The publications to generate the report for.

You may specify either of the two, be advised that publications has precedence over publication. All publications will be displayed if neither of these options is specified.

7.27.4. Rules

Publications
Pattern

<PublicationName>PublicationSettings

Type

org.kordamp.gradle.plugin.publishing.PublicationSettingsTask

7.28. Reproducible

id

org.kordamp.gradle.reproducible

class

org.kordamp.gradle.plugin.source.ReproduciblePlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Configures a project for Reproducible Builds.
Follows the instructions explained at https://reproducible-builds.org/docs/jvm/ which include:

7.28.1. DSL

config {
    reproducible {
        enabled
        additionalProperties
        additionalArtifacts
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.reproducible plugin if false

additionalProperties

Map<String, Object>

no

no

Additional properties to be added to the .buildinfo file.

additionalArtifacts

FileCollection

no

no

Additional file outputs to be added to the .buildinfo file.

7.28.2. Tasks

createBuildInfo

Generates a .buildinfo file with reproducible build settings.
The file is added to the main publication.

Name

createBuildInfo

Type

org.kordamp.gradle.plugin.reproducible.tasks.CreateBuildInfoTask

Properties
outputFile

${rootProject.buildDir}/buildinfo/${project.name}-${project.version}.buildinfo

additionalProperties

Map of additional properties to be added to the .buildinfo file.

additionalArtifacts

Set of additional artifacts (such as .zip or .tar.gz) to be added to the .buildinfo file.

7.29. Settings

id

org.kordamp.gradle.settings

class

org.kordamp.gradle.plugin.settings.SettingsPlugin (groovydoc, source)

This plugin should be applied to settings.gradle(.kts) only!

Configures the root project by automatically including subprojects. The root project must abide to one of the following layouts:

two-level

Subprojects are defined using a two-level directory structure, typically grouped by responsibility, for example

.
├── build.gradle
├── settings.gradle
├── docs
│   └── guide
│       └── guide.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    └── project2
        └── project2.gradle
multi-level

Subprojects are defined using any directory structure, for example

.
├── build.gradle
├── settings.gradle
├── guide
│   └── guide.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    └── project2
        └── project2.gradle
standard

Suprojects are defined as direct children of the root project, for example

.
├── build.gradle
├── settings.gradle
├── guide
│   └── guide.gradle
├── project1
│   └── project1.gradle
└── project2
    └── project2.gradle

Build files should be renamed to match their containing directory unless enforceNamingConvention is set to false, in which case the default build file name (build.gradle, build.gradle.kts) applies.

7.29.1. DSL

projects {
    cache
    layout
    enforceNamingConvention
    directories
    excludes
    fileNameTransformation
    prefix
    suffix

    directories([String: String])     // optional

    includeProjects(String dir)
        .exclude(String projectName)  // optional
        .includeIf(boolean)           // optional
    includeProjects(String dir)
        .exclude(String projectName)  // optional
        .includeIf(Supplier<Boolean>) // optional

    includeProject(String projectFilePath)
         .includeIf(boolean)          // optional
    includeProject(String projectFilePath)
        .includeIf(Supplier<Boolean>) // optional

    plugins { }
}
Name Type Required Default Value Description

cache

boolean

no

false

If true then the project structure will be cached.

layout

Layout

no

TWO_LEVEL

Defines the project layout. Valid values are [TWO_LEVEL, MULTI_LEVEL, STANDARD, EXPLICIT].
Also accepts literal values [two-level, multi-level, standard, explicit].

enforceNamingConvention

boolean

no

true

If true then build file names must match their containing project directory name.

useLongPaths

boolean

no

false

If true then projects will use their long paths when layout != standard.

directories

List<String>

no*

[]

List of directories to include for two-level and multi-level layout.

excludes

Set<String>

no

[]

Set of directories to be excluded from automatic inclusion.

fileNameTransformation

FileNameTransformation

no

Transformation applied to build file name. Valid values are [ADD, REMOVE].
Also accepts literal values [add, remove].

prefix

String

no

Prefix added/removed from build file name.

suffix

String

no

Suffix added/removed from build file name.

The directories property is not required if the chosen layout is set to standard or explicit. It may be omitted if the chosen layout is two-level however is recommended to define it if the search space is too big (too many first level directories).

The use of this DSL implies the computation of the root project’s structure on every build. You can cache the project structure by settings cache to true. The cache will be automatically invalidated if the settings file is updated in any way, thus when adding or removing a project directory for autodiscovery you must, at least, modify the last modified timestamp of the settings file, typically by invoking the touch OS command on the file, failing that make a simple edit and save the file.

Methods

includeProjects(String dir)
Includes projects found under the given directory unless the given condition (includeIf()) evaluates to false.

exclude(String)
Excludes a project directory by name.

includeProject(String path)
Includes a project found under the given path unless the given condition (includeIf()) evaluates to false.

directories(Map<String, String>)
Defines a set of directories where the key is the parent directory name and the value is a prefix, e.g.

projects {
    layout = 'two-level'
    directories('subprojects': 'sub-')
}

This will match all projects inside subprojects whose name have a sub- prefix.

7.29.2. Example

Two-Level

A project with the following structure

.
├── build.gradle
├── settings.gradle
├── docs
│   └── guide
│       └── guide.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    └── project2
        └── project2.gradle

Can be configured as follows

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

projects {
    directories = ['docs', 'subprojects']
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    directories = listOf("docs", "subprojects")
}
Multi-Level

A project with the following structure

.
├── build.gradle
├── settings.gradle
├── guide
│   └── guide.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    └── project2
        └── project2.gradle

Can be configured as follows

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

projects {
    layout = 'multi-level'
    directories = [
        'guide',
        'subprojects/project1',
        'subprojects/project2'
    ]
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    setLayout("multi-level")
    directories.set(listOf(
        "guide",
        "subprojects/project1",
        "subprojects/project2"
    ))
}

Alternatively you may skip setting a value for directories and have the project structure be automatically discovered.

Standard

A project with the following structure

.
├── build.gradle
├── settings.gradle
├── guide
│   └── guide.gradle
├── project1
│   └── project1.gradle
└── project2
    └── project2.gradle
settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

projects {
    layout = 'standard'
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    setLayout("standard")
}
Explicit

A project with the following structure

.
├── build.gradle
├── settings.gradle
├── guide
│   └── guide.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    └── project2
        └── project2.gradle

Can be configured as follows

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

projects {
    layout = 'explicit'
    includeProject('guide')
    includeProjects('subprojects')
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    setLayout("explicit")
    includeProject("guide")
    includeProjects("subprojects")
}

Filename transformations are applied to candidate build files, for example

Addition

A project with the following structure

.
├── build.gradle
├── settings.gradle
├── core
│   └── project-core.gradle
└── ext
    └── project-ext.gradle

Can be configured as follows

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

projects {
    layout = 'standard'
    fileNameTransformation = 'add'
    prefix = 'project-'
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    setLayout("standard")
    fileNameTransformation.set("add")
    prefix.set("project-")
}
Removal

A project with the following structure

.
├── build.gradle
├── settings.gradle
├── project-core
│   └── core.gradle
└── project-ext
    └── ext.gradle

Can be configured as follows

settings.gradle
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'org.kordamp.gradle:settings-gradle-plugin:0.54.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

projects {
    layout = 'standard'
    fileNameTransformation = 'remove'
    prefix = 'project-'
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.54.0")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    setLayout("standard")
    fileNameTransformation.set("remove")
    prefix.set("project-")
}

7.30. SourceJar

id

org.kordamp.gradle.source-jar

class

org.kordamp.gradle.plugin.source.SourceJarPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

applied by

org.kordamp.gradle.project
org.kordamp.gradle.publishing

Packages the project’s source code into a single JAR file.

7.30.1. DSL

config {
    artifacts {
        source {
            enabled
            emty
            aggregate {
                enabled
                empty
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

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

empty

boolean

no

false

Generates an empty JAR if true.

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

empty

boolean

no

false

Generates an empty JAR if true.

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.30.2. Tasks

AggregateSourcesJar

Collects the results of the sourcesJar tasks.
This task is added to the root project.

Name

aggregateSourcesJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
destinationDir

${rootProject.buildDir}/build/libs

SourcesJar

An archive of the source code.

Name

sourcesJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

sources

destinationDir

${project.buildDir}/build/libs

from

project.sourceSets.main.allSource

7.31. SourceStats

id

org.kordamp.gradle.source-stats

class

org.kordamp.gradle.plugin.stats.SourceStatsPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

applied by

org.kordamp.gradle.project

Generates reports on source code statistics both at individual and aggregate levels.

7.31.1. Example

The following configuration may be used in a Griffon project for example

Groovy
config {
    stats {
        formats = ['xml', 'html', 'txt']
        paths   = [
            model:      [name: 'Models',      path: 'griffon-app/models'],
            view:       [name: 'Views',       path: 'griffon-app/views'],
            controller: [name: 'Controllers', path: 'griffon-app/controllers'],
            service:    [name: 'Services',    path: 'griffon-app/services'],
            config:     [name: 'Config',      path: 'griffon-app/conf'],
            lifecycle:  [name: 'Lifecycle',   path: 'griffon-app/lifecycle']
        ]
    }
}
Kotlin
config {
    stats {
        formats = listOf("xml", "html", "txt")
        paths   = mapOf(
            "model"      to mapOf("name" to "Models",      "path" to "griffon-app/models"),
            "view"       to mapOf("name" to "Views",       "path" to "griffon-app/views"),
            "controller" to mapOf("name" to "Controllers", "path" to "griffon-app/controllers"),
            "service"    to mapOf("name" to "Services",    "path" to "griffon-app/services"),
            "config"     to mapOf("name" to "Config",      "path" to "griffon-app/conf"),
            "lifecycle"  to mapOf("name" to "Lifecycle",   "path" to "griffon-app/lifecycle")
        )
    }
}

7.31.2. DSL

config {
    stats {
        enabled
        counters
        formats
        paths
        aggregate {
            enabled
            excludedProjects
        }
    }
}
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.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.31.3. Tasks

AggregateSourceStats

Aggregates sources statistics for all projects.
XML stats report must exist for each child project.
This task is added to the root project.

Name

aggregateSourceStats

Type

org.kordamp.gradle.plugin.stats.AggregateSourceStatsReportTask

Properties
destinationDir

${rootProject.reporting.baseDir.path}/stats

SourceStats

Generates a source code statistics report

Name

sourceStats

Type

org.kordamp.gradle.plugin.stats.SourceStatsTask

Properties
formats

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

reportDir

${project.reporting.baseDir.path}/stats

counters

a Map of additional org.kordamp.gradle.plugin.stats.Counter implementations, keyed by extension.

paths

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

7.32. SpotBugs

id

org.kordamp.gradle.spotbugs

class

org.kordamp.gradle.plugin.spotbugs.SpotbugsPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
com.github.spotbugs

Configures SpotBugs on Java projects and aggregate reports on the root project.

7.32.1. DSL

config {
    quality {
        spotbugs {
            enabled
            includeFilterFile
            excludeFilterFile
            excludeBugsFilterFile
            effort
            reportLevel
            report
            visitors
            omitVisitors
            extraArgs
            jvmArgs
            ignoreFailures
            jvmArgs
            showProgress
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.spotbugs plugin if false

includeFilterFile

File

no

Either config/spotbugs/${project.name}-includeFilter.xml or config/spotbugs/includeFilter.xml

excludeFilterFile

File

no

Either config/spotbugs/${project.name}-excludeFilter.xml or config/spotbugs/excludeFilter.xml

excludeBugsFilterFile

File

no

Either config/spotbugs/${project.name}-excludeBugsFilterFile.xml or config/spotbugs/excludeBugsFilterFile.xml

effort

String

no

max

reportLevel

String

no

high

report

String

no

html

Either html or xml

visitors

List<String>

no

[]

omitVisitors

List<String>

no

[]

extraArgs

List<String>

no

[]

jvmArgs

List<String>

no

[]

ignoreFailures

boolean

no

true

Fails the build if set to false.

showProgress

boolean

no

true

toolVersion

String

no

4.8.1

excludedSourceSets

Set<String>

no

[]

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.32.2. Tasks

AggregateSpotbugs

Aggregates all spotbugs reports for all projects.
Consumes settings from config.quality.spotbugs.
This task is added to the root project.

Name

aggregateSpotbugs

Type

com.github.spotbugs.SpotBugsTask

Properties
reports.html.destination

${project.buildDir}/reports/spotbugs/aggregate.html

reports.xml.destination

${project.buildDir}/reports/spotbugs/aggregate.xml

AllSpotbugs

Aggregates all spotbugs reports for a single project.
Consumes settings from config.quality.spotbugs.

Name

allSpotbugs

Type

com.github.spotbugs.SpotBugsTask

Properties
reports.html.destination

${project.buildDir}/reports/spotbugs/${project.name}.html

reports.xml.destination

${project.buildDir}/reports/spotbugs/${project.name}.xml

7.33. SonarQube

id

org.kordamp.gradle.sonar

class

org.kordamp.gradle.plugin.coveralls.SonarPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
org.sonarsource.scanner.gradle:sonarqube-gradle-plugin

Configures the SonarQube gradle plugin to analyze your project with SonarQube.
If org.kordamp.gradle.jacoco is enabled, the output of the aggregateJacocoReport task is used as input for the sonarqube task

Data defined in the DSL’s config.info block will be used to provide additional information to SonarQube.

7.33.1. DSL

config {
    quality {
        sonar {
            enabled
            hostUrl
            organization
            login
            password
            projectKey
            ignoreFailures
            configProperties
        }
    }
}
Table 1. Properties
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.sonar plugin if false

hostUrl

String

no

'https://sonarcloud.io'

The server URL to publish the sonar analysis to

projectKey

String

no

${project.group}:${project.name}

The project’s unique key.

organization

String

yes*

The name of the organization. Required if publishing to https://sonarcloud.io

login

String

yes

The login or authentication token of a SonarQube user with publish analysis permission on the project.

password

String

yes*

The password that goes with login. This should be left blank if an authentication token is being used.

ignoreFailures

boolean

no

true

excludedProjects

Set<Project>

no

[]

Projects in the set are excluded from aggregation

configProperties

Map<String, Object>

no

[:]

Additional sonar properties that are passed to sonar as such

This block should be configured on the root project.

Table 2. Mapping of Kordamp to SonarQube properties
Plugin Property SonarQube Property Comment

config.quality.sonar.hostUrl

sonar.host.url

config.quality.sonar.projectKey

sonar.projectKey

config.quality.sonar.excludes

sonar.exclusions

config.coverage.jacoco.aggregateReportXmlFile

sonar.coverage.jacoco.xmlReportPaths

if jacoco is enabled

config.info.description

sonar.projectDescription

config.info.links.website

sonar.links.homepage

config.info.ciManagement.url

sonar.links.ci

config.info.issueManagement.url

sonar.links.issue

config.info.scm.url

sonar.links.scm

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void excludeProject(Project)

Exclude a project from sonar analysis.

7.33.2. Tasks

Sonarqube

Runs the code analysis with SonarQube.
Consumes settings from config.quality.sonar.
This task is added to the root project.

Name

sonarqube

Type

org.sonarqube.gradle.SonarQubeTask

7.34. Testing

id

org.kordamp.gradle.testing

class

org.kordamp.gradle.plugin.testing.TestingPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

applied by

org.kordamp.gradle.project

Configures test reports for unit, integration (if the org.kordamp.gradle.integration-test) plugin is applied), and functional (if the org.kordamp.gradle.functional-test) plugin is applied). Both individual and aggregate reports can be configured.

Additionally, each testcase and project will output a summary of the testes that were executed, successful, failed, and skipped, as the following screenshots show:

test output1
Figure 8. Successful tests
test output2
Figure 9. A failed test
test output3
Figure 10. Test summary

7.34.1. DSL

config {
    testing {
        enabled
        logging
        timeThreshold
        aggregate
        jar
        integration {
            logging
            aggregate
            includeTestOutput
            baseDir
        }
        functional {
            logging
            aggregate
            baseDir
        }
        colors {
            success
            failure
            skipped
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.test plugin if false

logging

boolean

no

true

Enables verbose output

timeThreshold

double

no

2000d

Flags slow tests that run for more than the given threshold.

aggregate

boolean

no

true

Enables test report aggregation

jar

boolean

no

false

Generates a -tests JAR.

integration

Name Type Required Default Value Description

logging

boolean

no

true

Enables verbose output

aggregate

boolean

no

true

Enables test report aggregation

includeTestOutput

boolean

no

false

Includes the compiled output from the test sourceSet.

baseDir

String

no

src/integration-test

functional

Name Type Required Default Value Description

logging

boolean

no

true

Enables verbose output

aggregate

boolean

no

true

Enables test report aggregation

baseDir

String

no

src/functional-test

colors

Name Type Required Default Value Description

success

String

no

green

failure

String

no

red

skipped

String

no

yellow

Valid values are [black, red, green, yellow, blue, magenta, cyan, white].

Tests JAR

If config.testing.jar is set to true an additional JAR file becomes available, with classifier tests and containing the compiled classes of the test sourceSet. Two additional configurations also become available:

  • testElements containing just the test JAR.

  • testArtifacts containing the test JAR and all elements from the testImplementation and testRuntimeOnly configurations.

The second configuration may be consumed by sibling projects that require shared test classes, for example given the following structure

.
├── build.gradle
├── settings.gradle
└── subprojects
    ├── project1
    │   ├── project1.gradle
    │   └── src
    │       ├── main
    │       │   └── java
    │       │       └── org
    │       │           └── kordamp
    │       │               └── sample
    │       │                   └── HelloWorld1.java
    │       └── test
    │           └── java
    │               └── org
    │                   └── kordamp
    │                       └── sample
    │                           └── HelloWorld1Test.java
    └── project2
        ├── project2.gradle
        └── src
            ├── main
            │   └── java
            │       └── org
            │           └── kordamp
            │               └── sample
            │                   └── HelloWorld2.java
            └── test
                └── java
                    └── org
                        └── kordamp
                            └── sample
                                └── HelloWorld2Test.java

With the following builds files

project1.gradle
dependencies {
    implementation('junit:junit:4.13')
}
project2.gradle
dependencies {
    testImplementation(project(path: ':project1', configuration: 'testArtifacts'))
}
project2.gradle.kts
dependencies {
    testImplementation(project(":project1", "testArtifacts"))
}

Then the class HelloWorldTest1 becomes available to classes in project2/src/test/java.

The test JAR also becomes part of the main publication.

7.34.2. Tasks

AggregateTestReports

Aggregates all test reports that are not integration nor functional.
This task is added to the root project.

Name

aggregateTestReports

Type

org.gradle.api.tasks.testing.TestReport

Properties
destinationDir

${rootProject.buildDir}/reports/aggregate-tests

AggregateIntegrationTestReports

Aggregates all integration test reports.
This task is added to the root project.

Name

aggregateIntegrationTestReports

Type

org.gradle.api.tasks.testing.TestReport

Properties
destinationDir

${rootProject.buildDir}/reports/aggregate-integration-tests

AggregateFunctionalTestReports

Aggregates all functional test reports.
This task is added to the root project.

Name

aggregateFunctionalTestReports

Type

org.gradle.api.tasks.testing.TestReport

Properties
destinationDir

${rootProject.buildDir}/reports/aggregate-fiunctional-tests

AggregateAllTestReports

Aggregates all test reports.
This task is added to the root project.

Name

aggregateAllTestReports

Type

org.gradle.api.tasks.testing.TestReport

Properties
destinationDir

${rootProject.buildDir}/reports/aggregate-all-tests

AllTests

Executes all tests found in a project (unit, integration, functional, etc).

Name

allTests

Type

org.gradle.api.DefaultTask

8. Authoring

Kordamp offers a set of additional features for plugin and build authors.

8.1. Properties

In the Maven world, plugins define parameters for their inputs using a @Parameter annotation that exposes the annotated element (typically a field) in such a way that its value can be defined using project or System properties. This allows consumer to define and override values as needed. For example the EchoMojo from the echo-maven-plugin

EchoMojo.java
class EchoMojo extends AbstractMojo {
    /**
     * The message text that should be echoed
     */
    @Parameter(property = "echo.message")
    private String message;

    ...
}

The value of the message parameter can be defined inside a pom.xml like so

<project ...>
    <groupId>com.acme</groupId>
    <artifactId>sample</artifactId>
    <version>0.0.0-SNAPSHOT</version>

    <properties>
        <echo.message>Hello World</echo.message>
    </properties>
</project>

Or it could be passed in the command line like so

$ gm com.github.ekryd.echo-maven-plugin:echo-maven-plugin:1.2.0:echo -Decho.message="Hello from command"

The org.kordamp.gradle.property package provides classes that deliver similar functionality, following a pattern of using a org.gradle.api.provider.Property for write and a org.gradle.api.provider.Provider for read. For example, the SimpleStringState can be used to replicate the behavior of the EchoMojo but using a Gradle task

EchoTask.groovy
package com.acme

import groovy.transform.CompileStatic
import org.gradle.api.DefaultTask
import org.gradle.api.provider.Property
import org.gradle.api.provider.Provider
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.Internal
import org.gradle.api.tasks.Optional
import org.gradle.api.tasks.TaskAction
import org.gradle.api.tasks.options.Option
import org.kordamp.gradle.property.SimpleStringState
import org.kordamp.gradle.property.StringState

@CompileStatic
class EchoTask extends DefaultTask {
    private final StringState message

    EchoTask() {
        message = SimpleStringState.of(this, 'echo.message', 'default message')
    }

    @Option(option='echo-message', description = 'The message to write')
    void setMessage(String message) {
        getMessage().set(message)
    }

    @Internal
    Property<String> getMessage() {
        message.property
    }

    @Input
    @Optional
    Provider<String> getResolvedMessage() {
        message.provider
    }

    @TaskAction
    void echo() {
        println getResolvedMessage().get()
    }
}

Take note that the task action reads the value using the Provider field. you’re free to mutate (write) the value as much as needed using the Property field but make sue to always use the Provider for reading. This task can be applied to a build as you normally would

build.gradle
task echo(type: com.acme.EchoTask) {

}

Invoking the echo task with no parameters nor explicit value for the message property in the build yields the following

$ gm echo

> Task :echo
default message

Defining a project property, whether it’s inline with -P at the command line, in a gradle.properties file located at the project directory or your home directory, or using a gradle init script, would result in that value being picked up instead

$ gm echo -Pecho.message="from project"

> Task :echo
from project

Passing a System property, in any way a System property can be defined, results in that value being chosen this time around

$ gm echo -Pecho.message="from project" -Decho.message="from System"

> Task :echo
from System

If there’s an environment variable whose key name follows a naming convention (all caps, substitute . for _) then its value will be the selected one

$ export ECHO_MESSAGE="from environment"
$ gm echo -Pecho.message="from project" -Decho.message="from System"

> Task :echo
from environment

But if a specific value is set in the task’s message property then and only then it will be picked up

build.gradle
task echo(type: com.acme.EchoTask) {
    message = 'from build'
}
$ gm echo -Pecho.message="from project" -Decho.message="from System"

> Task :echo
from build

Explicit values set in the build file have priority over values provided via environment, System, or project properties. You can switch this behavior (globally) by setting a System property kordamp.property.priority to any of these values

  • PROPERTY

  • PROVIDER

The resolution order shown here is ENV_SYS_PROP, but it can be changed to any of these values

  • ENV_SYS_PROP

  • ENV_PROP_SYS

  • SYS_ENV_PROP

  • SYS_PROP_ENV

  • PROP_ENV_SYS

  • PROP_SYS_ENV

Also, when running in a multi-project build you may want to provide default values depending on context, such as the path of the owning task (typically of the format :project:taskname), or the owning project (:project) or global to the whole build. These previous elements will be prefixed to the property/variable name with the default setting being GLOBAL_PROJECT_OWNER which means all prefixes will be checked, from more specific (OWNER) to least (GLOBAL). These are the values you can choose from

  • GLOBAL_PROJECT_OWNER

  • GLOBAL_PROJECT

  • GLOBAL_OWNER

  • GLOBAL

  • PROJECT_OWNER

  • PROJECT

  • OWNER

Any : found in the owner’s or project’s path will be turned into a ., except for the first which will be removed altogether, thus if the echo task is defined on a project whose path is :project the following property names will be checked in turn

  • project1.echo.echo.message

  • project1.echo.message

  • echo.message

You may fix these values when authoring your own tasks or you may leave it to the consumer to define the order. Kordamp will check the following System properties

kordamp.property.order

Determines the order between ENV, SYS, and PROP. Defaults to ENV_SYS_PROP.

kordamp.property.access

Determines the access level for calculating a prefix. Defaults to GLOBAL_PROJECT_OWNER.

kordamp.property.priority

Determines the priority between explicit values in the build file (PROPERTY) or values resolved via environment, System, or project properties (PROVIDER). Defaults to PROPERTY.

There are base states for the following types:

8.2. File Cache

A File cache local to a Gradle distribution is also accessible for storing data between builds. The cache is provided by the org.kordamp.gradle.util.Cache class and exposes the following behavior:

boolean has(Gradle gradle, Key key)

Queries the existence of a key in the cache.

long lastModified(Gradle gradle, Key key)

Returns the last modification timestamp of the given key.

long touch(Gradle gradle, Key key)

Updates the last modification timestamp of the given key.

void delete(Gradle gradle, Key key)

Deletes an entry from the cache.

boolean get(Gradle gradle, Key key, Consumer<? super InputStream> consumer)

Reads from the cache using an {@code java.io.InputStream}.

boolean read(Gradle gradle, Key key, Consumer<? super BufferedReader> consumer)

Reads from the cache using a {@code java.io.BufferedReader}.

boolean put(Gradle gradle, Key key, Consumer<? super OutputStream> consumer)

Writes to the cache using an {@code java.io.OutputStream}.

boolean write(Gradle gradle, Key key, Consumer<? super BufferedWriter> consumer)

Writes to the cache using a {@code java.io.BufferedWriter}.

void clear(Gradle gradle)

Deletes the whole cache.

Key key(Object input)

Creates a Key instance based on the given input.

Example:

// obtain a key
Cache.Key key = Cache.key(settings.gradle.gradleHomeDir.absolutePath + '-plugins.txt')

// define a reader function
Consumer<InputStream> reader = { InputStream r -> r.text.split('\n').each { pluginId -> corePlugins.add(pluginId) } }

// read from the cache
if (!Cache.getInstance().get(settings.gradle, key, reader)) {
    // read failed, compute values
    computeDefaultPlugins()
    // write to the cache
    Cache.getInstance().write(settings.gradle, key) { w -> w.write(corePlugins.join('\n')) }
}