A collection of opinionated Gradle plugins

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

Type	Plugin
Generic	`org.kordamp.gradle.project`
Java	`org.kordamp.gradle.java-project`
Groovy	`org.kordamp.gradle.groovy-project`

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

The usage of this DSL is optional. Gradle might change how it performs plugin management and resolution at any time.
Plugins defined and applied with this DSL are still visible to build files using the standard Gradle facilities such as plugins {} and apply plugin:.
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

The usage of this DSL is optional.

7. Plugins

7.1. Base

id	`org.kordamp.gradle.base`
class	`org.kordamp.gradle.plugin.base.BasePlugin` (groovydoc, source)
applied by	`org.kordamp.gradle.bom`, `org.kordamp.gradle.build-info`, `org.kordamp.gradle.chekcstyle`, `org.kordamp.gradle.codenarc`, `org.kordamp.gradle.coveralls`, `org.kordamp.gradle.errorprone`, `org.kordamp.gradle.functional-test`, `org.kordamp.gradle.groovydoc`, `org.kordamp.gradle.guide`, `org.kordamp.gradle.integration-test`, `org.kordamp.gradle.jacoco`, `org.kordamp.gradle.jar`, `org.kordamp.gradle.javadoc`, `org.kordamp.gradle.licensing`, `org.kordamp.gradle.minpom`, `org.kordamp.gradle.plugin`, `org.kordamp.gradle.pmd`, `org.kordamp.gradle.project`, `org.kordamp.gradle.publishing`, `org.kordamp.gradle.sonar`, `org.kordamp.gradle.source-jar`, `org.kordamp.gradle.source-stats`, `org.kordamp.gradle.spotbugs`, `org.kordamp.gradle.testing`

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	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	[]

name

String

project.name

Mapped to the <name> block in POM

description

String

yes

Mapped to the <description> block in POM

inceptionYear

String

current year

Mapped to the <inceptionYear> block in POM

vendor

String

no*

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.

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.

Name	Type	Required	Default Value	Description
name	String	no		The name of the organization
url	String	no		The URL of the organization (website perhaps).

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

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

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`.

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`.

Name	Type	Required	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

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`.

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

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

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

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`.

Name	Type	Required	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

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

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

true

Disables org.kordamp.gradle.bom plugin if false

autoIncludes

boolean

true

Disables default inclusion of all projects

dependencies

Map<String, Dependency>

[:]

Dependencies that should be added to the BOM

excludes

Set<String>

[]

Names of subprojects that should not be included

includes

Set<String>

[]

Names of subprojects that should be included

properties

Map<String, String>

[:]

Maps to <properties> block.

parent

String

Defines the coordinates of the parent POM

overwriteInceptionYear

boolean

false

Overwrite <inceptionYear> from parent POM

overwriteUrl

boolean

false

Overwrite <url> from parent POM

overwriteLicenses

boolean

false

Overwrite <licenses> from parent POM

overwriteScm

boolean

false

Overwrite <scm> from parent POM

overwriteOrganization

boolean

false

Overwrite <organization> from parent POM

overwriteDevelopers

boolean

false

Overwrite <developers> from parent POM

overwriteContributors

boolean

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'

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

true

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

useCommitTimestamp

boolean

true

Uses the latest commit time instead of the current time

skipBuildBy

boolean

false

Skips calculating this value

skipBuildDate

boolean

false

Skips calculating this value

skipBuildTime

boolean

false

Skips calculating this value

skipBuildRevision

boolean

false

Skips calculating this value

skipBuildJdk

boolean

false

Skips calculating this value

skipBuildOs

boolean

false

Skips calculating this value

skipBuildCreatedBy

boolean

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

true

Disables org.kordamp.gradle.checkstyle plugin if false

ignoreFailures

boolean

true

Fails the build if set to false.

includes

Set<String>

[]

excludes

Set<String>

[]

configFile

Set<String>

configProperties

Map<String, Object>

[:]

maxErrors

int

maxWarnings

int

Integer.MAX_VALUE

showViolations

boolean

yes

toolVersion

String

10.12.4

excludedSourceSets

Set<String>

[]

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

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

true

Disables org.kordamp.gradle.codenarc plugin if false

ignoreFailures

boolean

true

Fails the build if set to false.

configFile

Set<String>

maxPriority1Violations

int

maxPriority2Violations

int

maxPriority3Violations

int

toolVersion

String

3.3.0

excludedSourceSets

Set<String>

[]

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

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

true

Disables org.kordamp.gradle.coveralls plugin if false

standalone

boolean

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

true

Disables org.kordamp.gradle.errorprone plugin if false

args

List<String>

[]

Additional arguments to be passed to the ErrorProne javac plugin

disableAllChecks

boolean

false

allErrorsAsWarnings

boolean

false

allDisabledChecksAsWarnings

boolean

false

disableWarningsInGeneratedCode

boolean

true

ignoreUnknownCheckNames

boolean

false

ignoreSuppressionAnnotations

boolean

false

compilingTestOnlyCode

boolean

false

excludedPaths

String

errorProneVersion

String

2.23.0

errorProneJavacVersion

String

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:

org.kordamp.gradle.codenarc

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

true

Disables org.kordamp.gradle.groovydoc plugin if false

empty

boolean

false

Generates an empty JAR if true.

includes

Set<String>

[]

excludes

Set<String>

[]

replaceJavadoc

boolean

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

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

docTitle

String

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

header

String

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

footer

String

overviewText

TextResource

links

Set<Link>

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

noTimestamp

boolean

noVersionStamp

boolean

includePrivate

boolean

true

use

boolean

true

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

true

Enables or disables aggregation

empty

boolean

false

Generates an empty JAR if true.

fast

boolean

true

Does not execute child groovydoc tasks if true

replaceJavadoc

boolean

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

true

Disables org.kordamp.gradle.guide plugin if false

publish

Name Type Required Default Value Description

enabled

boolean

false

Disables publication of guide if false

branch

String

'gh-pages'

Git branch

message

String

"Publish guide for ${project.version}"

Commit message

7.12.2. Extension

guide {
    javadocApiDir
    groovydocApiDir
}

Name

Type

Required

Default Value

Description

javadocApiDir

String

'api'

Director where javadoc will be copied

groovydocApiDir

String

'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:

pluginId:task where pluginId is either a core Gradle plugin or an aliased plugin.
pluginId:version:task where pluginId is a core Gradle plugin or an aliased plugin.
groupId:artifactId:version:task.
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

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

green

Color to use when state is SUCCESS

failure

String

red

Color to use when state is FAILURE

skipped

String

yellow

Color to use when state is SKIPPED

partial

String

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

true

Enables or disables this report.

format

String

short

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

zeroPadding

boolean

false

Output 0 characters in task table.

maxProjectPathSize

int

Maximum size for displaying project path.

confTimeThreshold

double

0.5d

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

execTimeThreshold

double

120d

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

displayProjectThreshold

int

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

Figure 1. $ gm build

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

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.

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

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

Figure 5. $ gm build

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

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.

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

true

Disables org.kordamp.gradle.jacoco plugin if false

aggregateExecFile

File

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

Location for the aggregate merge execution data file

aggregateReportHtmlFile

File

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

Location for aggregate HTML reports

aggregateReportXmlFile

File

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

Location for the aggregate XML report

additionalSourceDirs

FileCollection

[]

Additional source directories

additionalClassDirs

FileCollection

[]

Additional class directories

toolVersion

String

0.8.11

excludes

Set<String>

[]

includeProjectDependencies

boolean

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

true

Disables org.kordamp.gradle.jar plugin if false

This block is optional.

manifest

Name Type Required Default Value Description

enabled

boolean

false

Enables or disables manifest customizations

addClasspath

boolean

false

Whether to create a Class-Path manifest entry

classpathPrefix

String

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

classpathLayoutType

String

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:

org.kordamp.gradle.checkstyle
org.kordamp.gradle.pmd
org.kordamp.gradle.errorprone
org.kordamp.gradle.spotbugs

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

true

Disables org.kordamp.gradle.javadoc plugin if false

empty

boolean

false

Generates an empty JAR if true.

copyDocFiles

boolean

true

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

includes

Set<String>

[]

excludes

Set<String>

[]

title

String

options

MinimalJavadocOptions

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.

autoLinks

Name Type Required Default Value Description

enabled

boolean

true

Disables generation of auto links if false

configurations

List<String>

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

Configurations to be checked for dependencies

excludes

Set<String>

[]

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

useJavadocIo

boolean

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

true

Enables or disables aggregation

empty

boolean

false

Generates an empty JAR if true.

fast

boolean

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`

CheckAutoLinks

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

true

Disables org.kordamp.gradle.licensing plugin if false

includes

Set<String>

[]

excludes

Set<String>

[]

mappings

Map<String, String>

[:]

excludedSourceSets

Set<String>

[]

licenses

LicenseSet

yes

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

inherits

boolean

true

Whether to inherit values from a parent POM.

mergeStrategy

MergeStrategy

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

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

Maps to the <url> block

distribution

String

'repo'

Maps to the <distribution> block

comments

String

Maps to the <comments> block

aliases

List<String>

[]

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

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

true

Disables org.kordamp.gradle.plugin plugin if false

plugin

Name

Type

Required

Default Value

Description

String

yes

Defines the plugin’s id

name

String

yes

Defines the plugin’s name

description

String

Defines the plugin’s description

displayName

String

Defines the plugin’s display name

implementationClass

String

yes

Defines the plugin’s implementation Class

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

true

Disables org.kordamp.gradle.pmd plugin if false

ignoreFailures

boolean

true

Fails the build if set to false.

ruleSetFiles

FileCollection

incrementalAnalysis

boolean

false

rulePriority

int

excludedSourceSets

Set<String>

[]

toolVersion

String

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

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 {
    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

id	`org.kordamp.gradle.project`
class	`org.kordamp.gradle.plugin.project.ProjectPlugin` (groovydoc, source)
applies	`org.kordamp.gradle.base`, `org.kordamp.gradle.profiles`, `org.kordamp.gradle.build-info`, `org.kordamp.gradle.jacoco`, `org.kordamp.gradle.coveralls`, `org.kordamp.gradle.jar`, `org.kordamp.gradle.javadoc`, `org.kordamp.gradle.licensing`, `org.kordamp.gradle.minpom`, `org.kordamp.gradle.publishing`, `org.kordamp.gradle.source-jar`, `org.kordamp.gradle.source-stats`, `org.kordamp.gradle.testing`, `com.github.ben-manes.versions`
applied by	`org.kordamp.gradle.java-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:

org.kordamp.gradle.bom
org.kordamp.gradle.integration-test
org.kordamp.gradle.functional-test

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

true

Enables or disables processing of the target format.

overwrite

boolean

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

true

Disables org.kordamp.gradle.publishing plugin if false

releasesRepository

String

Name of a Maven compatible repository for publishing releases

snapshotsRepository

String

Name of a Maven compatible repository for publishing snapshots

publications

List<String>

[]

Publication names to be included

scopes

List<String>

[]

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

flattenPlatforms

boolean

false

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

useVersionExpressions

boolean

true

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

This block is optional.

signing

Name Type Required Default Value Description

enabled

boolean

false

Disables artifact signing if false

keyId

String

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

secretKey

String

Ascii armored secret key used for signing

password

String

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

jar

Defines the value for <packaging>

properties

Map<String, String>

[:]

Maps to <properties> block.

parent

String

Defines the coordinates of the parent POM

overwriteInceptionYear

boolean

false

Overwrite <inceptionYear> from parent POM

overwriteUrl

boolean

false

Overwrite <url> from parent POM

overwriteLicenses

boolean

false

Overwrite <licenses> from parent POM

overwriteScm

boolean

false

Overwrite <scm> from parent POM

overwriteOrganization

boolean

false

Overwrite <organization> from parent POM

overwriteDevelopers

boolean

false

Overwrite <developers> from parent POM

overwriteContributors

boolean

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:

Disables time, date, and author information from org.kordamp.gradle.build-info.
Disable timestamps on Javadoc and Groovydoc files.
Configured all generated archives as reproducible.

7.28.1. DSL

config {
    reproducible {
        enabled
        additionalProperties
        additionalArtifacts
    }
}

Name Type Required Default Value Description

enabled

boolean

true

Disables org.kordamp.gradle.reproducible plugin if false

additionalProperties

Map<String, Object>

Additional properties to be added to the .buildinfo file.

additionalArtifacts

FileCollection

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

false

If true then the project structure will be cached.

layout

Layout

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

true

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

useLongPaths

boolean

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>

[]

Set of directories to be excluded from automatic inclusion.

fileNameTransformation

FileNameTransformation

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

prefix

String

Prefix added/removed from build file name.

suffix

String

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

true

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

empty

boolean

false

Generates an empty JAR if true.

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

true

Enables or disables aggregation

empty

boolean

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

true

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

counters

Map<String, String>

[:]

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

formats

List<String>

[]

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

paths

Map<String, Map<String, String>>

[:]

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

This block is optional.

aggregate

Name

Type

Required

Default Value

Description

enabled

boolean

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

true

Disables org.kordamp.gradle.spotbugs plugin if false

includeFilterFile

File

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

excludeFilterFile

File

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

excludeBugsFilterFile

File

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

effort

String

max

reportLevel

String

high

report

String

html

Either html or xml

visitors

List<String>

[]

omitVisitors

List<String>

[]

extraArgs

List<String>

[]

jvmArgs

List<String>

[]

ignoreFailures

boolean

true

Fails the build if set to false.

showProgress

boolean

true

toolVersion

String

4.8.1

excludedSourceSets

Set<String>

[]

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

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:

Figure 8. Successful tests

Figure 9. A failed test

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

true

Disables org.kordamp.gradle.test plugin if false

logging

boolean

true

Enables verbose output

timeThreshold

double

2000d

Flags slow tests that run for more than the given threshold.

aggregate

boolean

true

Enables test report aggregation

jar

boolean

false

Generates a -tests JAR.

integration

Name Type Required Default Value Description

logging

boolean

true

Enables verbose output

aggregate

boolean

true

Enables test report aggregation

includeTestOutput

boolean

false

Includes the compiled output from the test sourceSet.

baseDir

String

src/integration-test

functional

Name

Type

Required

Default Value

Description

logging

boolean

true

Enables verbose output

aggregate

boolean

true

Enables test report aggregation

baseDir

String

src/functional-test

colors

Name

Type

Required

Default Value

Description

success

String

green

failure

String

red

skipped

String

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')) }
}

9. Links

Javadoc

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).

Name	archives
Type	`org.kordamp.gradle.plugin.base.tasks.ArchivesTask`