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.

2. Usage

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

Option #1

Groovy
buildscript {
    repositories {
        // Gradle Plugin Portal
        maven {  url 'https://plugins.gradle.org/m2/' }
        // required for additional dependencies, may use mavenCentral() instead
        jcenter()
    }
    dependencies {
        classpath 'org.kordamp.gradle:{plugin-id}:0.37.1'
    }
}
apply plugin: '{plugin-id}'
Kotlin
buildscript {
    repositories {
        // Gradle Plugin Portal
        maven(url = "https://plugins.gradle.org/m2/")
        // required for additional dependencies, may use mavenCentral() instead
        jcenter()
    }
    dependencies {
        classpath("org.kordamp.gradle:{plugin-id}:0.37.1")
    }
}
apply(plugin = "{plugin-id}")

Option #2

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

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 8 and Gradle 5 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.37.1'
    }
}
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.37.1")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

rootProject.name = "root"

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    directories = 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.37.1'      (1)
    id 'org.kordamp.gradle.bintray'      version '0.37.1'      (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'
            }
        }
    }

    bintray {                                                             (5)
        credentials {
            username = project.bintrayUsername
            password = project.bintrayApiKey
        }
        userOrg    = 'joecool'
        name       = rootProject.name
        githubRepo = 'joecool/sample'
    }
}

allprojects {
    repositories {
        jcenter()
    }
}
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
5 Publishing specific information
Kotlin
plugins {
    id("org.kordamp.gradle.java-project") version "0.37.1"     (1)
    id("org.kordamp.gradle.bintray")      version "0.37.1"     (1)
}

val bintrayUsername: String by project
val bintrayApiKey: String by project

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

    bintray {                                                             (5)
        credentials {
            username = project.bintrayUsername
            password = project.bintrayApiKey
        }
        userOrg    = "joecool"
        name       = rootProject.name
        githubRepo = "joecool/sample"
    }
}

allprojects {
    repositories {
        jcenter()
        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
5 Publishing specific information

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 bintray plugin with data defined in 5.

  • Configure the jacoco plugin on each project.

  • Configure aggregate JaCoCo reports on the root project.

  • Generate a source stats task per project.

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

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

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

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

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

And the build file for each subproject may look like

Groovy
apply plugin: 'java'

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

dependencies {
    // dependencies
}

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

Type Plugin

Generic

org.kordamp.gradle.project

Java

org.kordamp.gradle.java-project

Groovy

org.kordamp.gradle.groovy-project

Kotlin

org.kordamp.gradle.kotlin-project

Scala

org.kordamp.gradle.scala-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 { ... }
    dependencies { ... }
    bintray { ... }
    bom { ... }
    buildInfo { ... }
    clirr { ... }
    licensing { ... }
    plugin { ... }
    publishing { ... }
    stats { ... }
    testing { ... }
    artifacts {
        jar { ... }
        minpom { ... }
        source { ... }
    }
    docs {
        guide { ... }
        groovydoc { ... }
        javadoc { ... }
        kotlindoc { ... }
        scaladoc { ... }
        sourceHtml { ... }
        sourceXref { ... }
    }
    coverage {
        coveralls { ... }
        jacoco { ... }
    }
    quality {
        checkstyle { ... }
        codenarc { ... }
        cpd { ... }
        detekt { ... }
        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.37.1'
}

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

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

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

allprojects {
    repositories {
        jcenter()
    }
}
build.gradle (child)
config {
    bintray    { enabled = false }
    publishing { enabled = false }
}
build.gradle.kts (child)
config {
    bintray    { enabled = false }
    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 {
           id(String).when(boolean)
           id(String).when(Supplier<Boolean>)
        }
        dir(String) {
            id(String).when(boolean)
            id(String).when(Supplier<Boolean>)
        }
        dirs(List<String>) {
            exclude(String)
            id(String).when(boolean)
            id(String).when(Supplier<Boolean>)
        }
        path(String) {
            id(String).when(boolean)
            id(String).when(Supplier<Boolean>)
        }
        paths(List<String>) {
            id(String).when(boolean)
            id(String).when(Supplier<Boolean>)
        }
    }
}

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.

exclude

A project path to be excluded. Path must be an exact match to the given argument.

These are the usage rules:

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

  • The when() 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 {
        jcenter()
        gradlePluginPortal()
    }
    dependencies {
        classpath "org.kordamp.gradle:settings-gradle-plugin:0.37.1"
        classpath "org.kordamp.gradle:java-project-gradle-plugin:0.37.1"
        classpath "org.kordamp.gradle:guide-gradle-plugin:0.37.1"
        classpath "org.kordamp.gradle:integrationtest-gradle-plugin:0.37.1"
        classpath "org.kordamp.gradle:functionaltest-gradle-plugin:0.37.1"
    }
}

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') {
            exclude(':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 {
        jcenter()
        gradlePluginPortal()
    }

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

apply<SettingsPlugin>()

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

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

This configuration will perform the following:

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

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

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

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

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

5.2. Remarks

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

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

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

6. Projects DSL

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

The DSL is comprised of the following elements

projects {
    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 {
    // ...
}

projects
    all {
        path('*') {
            repositories {
                jcenter()
            }
        }

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

config {
    // ...
}

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

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

This configuration will perform the following

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

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

6.2. Remarks

  1. The usage of this DSL is optional.

7. Plugins

7.1. Base

id

org.kordamp.gradle.base

class

org.kordamp.gradle.plugin.base.BasePlugin (groovydoc, source)

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
        }

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

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

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

        issueManagement {
            system
            url
        }

        ciManagement {
            system
            url
        }

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

    dependencies {
        dependency(String)
    }
}

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

general

Name Type Required Default Value Description

name

String

no

project.name

Mapped to the <name> block in POM

description

String

yes

Mapped to the <description> block in POM

inceptionYear

String

no

current year

Mapped to the <inceptionYear> block in POM

vendor

String

no*

tags

List<String>

no

[]

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

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables this block.

website

String

yes

empty

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

issueTracker

String

no*

empty

Mapped to bintray.pkg.issueTracker

scm

String

no*

empty

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

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

scm

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables this block.

url

String

yes

empty

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

connection

String

no*

empty

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

developerconnection

String

no*

empty

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

This block has precedence over links.scm.

organization

Name Type Required Default Value Description

name

String

no

The name of the organization

url

String

no

The URL of the organization (website perhaps).

This block is optional.

specification

Name Type Required Default Value Description

enabled

boolean

no

true

JAR manifest entries will be updated if true

title

String

no

project.name

Mapped to Specification-Title manifest entry

version

String

no

project.version

Mapped to Specification-Version manifest entry

vendor

String

no

info.vendor

Mapped to Specification-Vendor manifest entry

This block is optional.

implementation

Name Type Required Default Value Description

enabled

boolean

no

true

JAR manifest entries will be updated if true

title

String

no

project.name

Mapped to Implementation-Title manifest entry

version

String

no

project.version

Mapped to Implementation-Version manifest entry

vendor

String

no

info.vendor

Mapped to Implementation-Vendor manifest entry

This block is optional.

credentials

Name Type Required Default Value Description

 github

Credentials

no*

Username/Password for connecting to GitHub

 sonatype

Credentials

no*

Username/Password for connecting to Maven Central

named

Credentials

no*

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

The sonatype entry may be used by the org.kordamp.gradle.bintray plugin to configure auto-sync with Maven Central when pushing a publication. Named credentials my match the name of a repository, in which case they will be used during artifact publication on the matching repository.

This block is optional.

repositories

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

repository

Name Type Required Default Value Description

name

String

no*

The name of the repository

url

String

no*

The URL of the repository

credentials

Credentials

no*

Values mapped to credentials block

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

people

This block defines data associated with a particular person.

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

person

Name Type Required Default Value Description

id

String

no*

Mapped to the <id> block in POM

name

String

no*

Mapped to the <name> block in POM

email

String

no

Mapped to the <email> block in POM

url

String

no

Mapped to the <url> block in POM

organization

Organization

no

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

roles

List<String>

no

Mapped to the <roles> block in POM

timezone

String

no

Mapped to the <timezone> block in POM

properties

Map<String, Object>

no

[:]

Mapped to the <properties> block in POM

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

issueManagement

Name Type Required Default Value Description

system

String

no

The system value of the <issueManagement> block in POM

url

String

no

The url value of the <issueManagement> block in POM

ciManagement

Name Type Required Default Value Description

system

String

no

The system value of the <ciManagement> block in POM

url

String

no

The url value of the <ciManagement> block in POM

mailingLists

This block defines a list of MailingList entries.

mailingList

Name Type Required Default Value Description

name

String

no*

Mapped to the <name> block in POM

subscribe

String

no

Mapped to the <subscribe> block in POM

unsubscribe

String

no

Mapped to the <unsubscribe> block in POM

post

String

no

Mapped to the <post> block in POM

archive

String

no

Mapped to the <archive> block in POM

otherArchives

List<String>

no

Mapped to the <otherArchives> block in POM

At least name must be defined.

dependencies

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

name

short name of the dependency or platform.

groupId

the groupId part of the artifact’s coordinates.

artifactId

the artifactId part of the artifact’s coordinates.

version

the version part of the artifact’s coordinates.

platform

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

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

Dependencies defined in this way cannot have classifiers and must be resolvable from a Maven compatible repository.
Methods
dependency(String)

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

dependency(String, String)

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

dependency(String, String, Action)

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

dependency(String, String, Closure)

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

platform(String)

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

platform(String, String)

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

platform(String, String, Action)

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

platform(String, String, Closure)

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

dependency(String, Action)

Defines and configures a dependency by name.

dependency(String, Closure)

Defines and configures a dependency by name.

getDependency(String)

Returns the named dependency (if it exists). Throws an exception otherwise.

findDependencyByName(String)

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

findDependencyByGA(String, String)

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

gav(String)

Returns the given dependency in GAV notation if it exists. Throws an exception otherwise.

gav(String, String)

Returns the given module dependency in GAV notation if it exists. Throws an exception otherwise.

ga(String, String)

Returns the given module dependency in GA (groupId/artifactId) notation if it exists. Throws an exception otherwise.

Example
build.gradle
config {
    dependencies {
        // a dependency with modules
        dependency('groovy') {
            groupId    = 'org.codehaus.groovy'
            artifactId = 'groovy'
            version    = '3.0.3'
            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.0.M3') {
            modules = [
                'micronaut-core',
                'micronaut-inject',
                'micronaut-validation'
            ]
        }
    }
}

These dependencies can be used in combination with the cfg extension if the org.kordamp.gradle.java-project plugin is applied, for example

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

config {
    dependencies {
        // a dependency with modules
        dependency('groovy') {
            groupId    = 'org.codehaus.groovy'
            artifactId = 'groovy'
            version    = '3.0.3'
            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.0.M3') {
            modules = [
                'micronaut-core',
                'micronaut-inject',
                'micronaut-validation'
            ]
        }
    }
}

// consume dependencies
dependencies {
    // apply Micronaut platform to some configurations
    cfg.platform('micronaut', 'api', 'annotationProcessor', 'compileOnly')
    // configure a dependency in the standard way
    api 'io.micronaut:micronaut-core'
    // configure a platform module by groupId:artifactId
    annotationProcessor config.dependencies.ga('micronaut', 'micronaut-inject')
    // pull in a module from Groovy
    api config.dependencies.gav('groovy', 'groovy-json')
    // configure a single dependency
    testImplementation config.dependencies.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.0.M3</micronaut.version>
    <groovy.version>3.0.3</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.

7.1.2. Tasks

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'
    id 'org.kordamp.gradle.project' version '0.37.1'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :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. 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.

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.37.1'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :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: projects
    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.37.1'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :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.37.1'
    }
}
apply plugin: 'org.kordamp.gradle.settings'
build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.37.1'
}

config {
    licensing  { enabled = false }

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

Invoking these command

$ ./gradlew :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.37.1'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :plugins

Results in the following output

> Task :plugins
Total plugins: 30

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

plugin 23:
    id: org.kordamp.gradle.source-html
    implementationClass: org.kordamp.gradle.plugin.sourcehtml.SourceHtmlPlugin
    enabled: true

plugin 24:
    id: org.kordamp.gradle.source-xref
    implementationClass: org.kordamp.gradle.plugin.sourcexref.SourceXrefPlugin
    enabled: true

plugin 25:
    id: org.kordamp.gradle.bintray
    implementationClass: org.kordamp.gradle.plugin.bintray.BintrayPlugin
    enabled: true

plugin 26:
    id: org.kordamp.gradle.testing
    implementationClass: org.kordamp.gradle.plugin.testing.TestingPlugin
    enabled: true

plugin 27:
    id: com.github.ben-manes.versions
    implementationClass: com.github.benmanes.gradle.versions.VersionsPlugin

plugin 28:
    id: org.kordamp.gradle.project
    implementationClass: org.kordamp.gradle.plugin.project.ProjectPlugin
    enabled: true

plugin 29:
    id: net.nemerosa.versioning
    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.37.1'
}

ext.build_property = 'build'

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :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.37.1'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

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

Invoking these command

$ ./gradlew :repositories

Results in the following output

> Task :repositories
Total repositories: 3

repository 0:
    type: maven
    name: BintrayJCenter
    url: https://jcenter.bintray.com/

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

repository 2:
    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. Bintray

Configures artifact publications using Bintray. Relies on the publication configured by the org.kordamp.gradle.publishing plugin. The name of the publication matches "main".

7.2.1. DSL

config {
    bintray {
        enabled
        credentials {
            username
            password
        }
        name
        repo
        userOrg
        githubRepo
        skipMavenSync
        publications
        publish
        publicDownloadNumbers
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.bintray plugin if false

credentials

Credentials

yes

Values map to bintray.user and bintray.key

repo

String

no

maven

Mapped to bintray.pkg.repo

userOrg

String

yes

Mapped to bintray.pkg.userOrg

name

String

no

project.name

Mapped to bintray.pkg.name

githubRepo

String

no

$userOrg/$name

Mapped to bintray.pkg.githubRepo

skipMavenSync

boolean

no

false

Do not sync with Maven Central

publications

List<String>

no

['main']

Configures the publications that should be published to Bintray

publish

boolean

no

false

Whether version should be auto published after an upload

publicDownloadNumbers

boolean

no

true

Whether download numbers should be public or not

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

The value for githubRepo may be inferred by using "$userOrg/$name".

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

Sync with Maven Central will happen automatically if Sonatype credentials are defined in the config DSL and if skipMavenSync is set to false (default).

7.3. 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.3.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.3.2. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.bom plugin if false

autoIncludes

boolean

no

true

Disables default inclusion of all projects

dependencies

Map<String, Dependency>

no

[:]

Dependencies that should be added to the BOM

excludes

Set<String>

no

[]

Names of subprojects that should not be included

includes

Set<String>

no

[]

Names of subprojects that should be included

properties

Map<String, String>

no

[:]

Maps to <properties> block.

parent

String

no

Defines the coordinates of the parent POM

overwriteInceptionYear

boolean

no

false

Overwrite <inceptionYear> from parent POM

overwriteUrl

boolean

no

false

Overwrite <url> from parent POM

overwriteLicenses

boolean

no

false

Overwrite <licenses> from parent POM

overwriteScm

boolean

no

false

Overwrite <scm> from parent POM

overwriteOrganization

boolean

no

false

Overwrite <organization> from parent POM

overwriteDevelopers

boolean

no

false

Overwrite <developers> from parent POM

overwriteContributors

boolean

no

false

Overwrite <contributors> from parent POM

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

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

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

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

This block is optional.

Methods
exclude(String)

Skips the named project from being added to the BOM.

include(String)

Adds the named project to the BOM.

dependency(String)

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

dependency(String, String)

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

dependency(String, String, Action)

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

dependency(String, String, Closure)

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

platform(String)

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

platform(String, String)

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

platform(String, String, Action)

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

platform(String, String, Closure)

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

dependency(String, Action)

Defines and configures a dependency by name.

dependency(String, Closure)

Defines and configures a dependency by name.

getDependency(String)

Returns the named dependency (if it exists). Throws an exception otherwise.

findDependencyByName(String)

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

findDependencyByGA(String, String)

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

void dependency(Dependency)

Adds an existing dependency, usually declared in config.dependencies.

7.4. BuildInfo

id

org.kordamp.gradle.build-info

class

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

applies

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

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.SSSZ"

 buildBy

String

The value of the user.name System property

 buildRevision

String

The value of the latest commit hash

 buildJdk

String

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

 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.4.1. DSL

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

enabled

boolean

no

true

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

clearTime

boolean

no

false

Sets the value of buildTime to zero.

skipBuildBy

boolean

no

false

Skips calculating this value

skipBuildDate

boolean

no

false

Skips calculating this value

skipBuildTime

boolean

no

false

Skips calculating this value

skipBuildRevision

boolean

no

false

Skips calculating this value

skipBuildJdk

boolean

no

false

Skips calculating this value

skipBuildOs

boolean

no

false

Skips calculating this value

skipBuildCreatedBy

boolean

no

false

Skips calculating this value

7.5. 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.5.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.checkstyle plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

configFile

Set<String>

no

configProperties

Map<String, Object>

no

[:]

maxErrors

int

no

0

maxWarnings

int

no

Integer.MAX_VALUE

showViolations

boolean

no

yes

toolVersion

String

no

8.27

excludedSourceSets

Set<String>

no

[]

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

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

  • Explicit value if set in the build file.

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

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

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

  • config/checkstyle/checkstyle.xml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.5.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.6. Clirr

id

org.kordamp.gradle.clirr

class

org.kordamp.gradle.plugin.clirr.ClirrPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Configures Clirr on all subprojects.
Configures aggregate reports on the root project.

This plugin is a fork of the kordamp-gradle-plugins authored by Uladzimir Mihura with Copyright (c) 2008 - 2013 10gen, Inc. http://10gen.com.

7.6.1. DSL

config {
    clirr {
        enabled
        baseline
        filterFile
        filter
        failOnErrors
        failOnException
        semver
        aggregate {
            enabled
            excludedProjects
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.clirr plugin if false

 baseline

String

no

Maven coordinates of the previous version, i.e. groupId:artifactId:version

 filterFile

File

no

A YAML file containing exclusions

 filter

Predicate

no

Excludes a compatibility issue if there’s a matching criteria

 failOnErrors

boolean

no

true

Abort the build if a compatibility issue with severity "error" is found

 failOnException

boolean

no

false

Abort the build if Clirr triggers an Exception during its checks

 semver

boolean

no

true

Evaluates the project’s version using semver rules

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

The filter predicate takes a single argument, which exposes the following properties

  • severity; java.lang.String; info, warning, error.

  • identifier; java.lang.String; severity id number.

  • classname; java.lang.String; fully qualified classname.

  • message; java.lang.String; formatted severity message.

You may skip defining a value for baseline and let the clirr task figure out the the previous version according to the following rules

  1. remove trailing tag if it exists

  2. if the semver property is set to true (default)

    1. if the minor version is 0 then revision is checked

      1. if revision is 0 clirr is disabled.

      2. if revision is > 0 decrement revision by 1.

    2. if the minor version is > 0 then revision is checked

      1. if revision is 0 decrement minor by 1.

      2. if revision is > 0 decrement revision by 1.

  3. if the semver property is set to false

  4. if revision is 0 then clirr is disabled.

  5. if revision is > 0 then revision is decremented by 1.

These rules produce the following outcomes given these inputs

semver = true
2.0.0 => disabled
2.0.4 => 2.0.3
2.1.0 => 2.0.0
2.1.3 => 2.1.2
semver = false
2.0.0 => disabled
2.0.4 => 2.0.3
2.1.0 => disabled
2.1.3 => 2.1.2

7.6.2. Example

The following example, taken from the Griffon build, calculates the clirr report of every submodule

build.gradle
clirr {
    failOnErrors = false
    baseline = ['org.codehaus.griffon', subproj.name, '2.0.0'].join(':')
}

7.6.3. Error Codes

Binary reports rely on a list of codes that determine the severity of a compatibility issue. The full list of codes and an explanation for each one can be found at http://clirr.sourceforge.net/clirr-core/exegesis.html

7.6.4. Tasks

Clirr

Determines the binary compatibility of the current codebase against a previous release.

Name

clirr

Type

org.kordamp.gradle.plugin.clirr.tasks.ClirrTask

Properties
xmlReport

${rootProject.reporting.baseDir.path}/clirr/compatibility-report.xml

htmlReport

${rootProject.reporting.baseDir.path}/clirr/compatibility-report.html

AggregateClirr

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

Name

aggregateClirr

Type

org.kordamp.gradle.plugin.clirr.tasks.AggregateClirrReportTask

Properties
reportFile

${rootProject.reporting.baseDir.path}/clirr/aggregate-compatibility-report.html

7.7. 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.7.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.codenarc plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

configFile

Set<String>

no

maxPriority1Violations

int

no

maxPriority2Violations

int

no

maxPriority3Violations

int

no

toolVersion

String

no

1.5

excludedSourceSets

Set<String>

no

[]

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

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

  • Explicit value if set in the build file.

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

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

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

  • config/codenarc/codenarc.groovy

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

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

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

  • config/codenarc/codenarc.xml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.7.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.8. Coveralls

id

org.kordamp.gradle.coveralls

class

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

applies

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

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.8.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.coveralls plugin if false

7.9. Cpd

id

org.kordamp.gradle.cpd

class

org.kordamp.gradle.plugin.cpd.CpdPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Configures CPD on Java projects and aggregate reports on the root project. Each sourceSet gets a org.kordamp.gradle.plugin.cpd.Cpd.

7.9.1. DSL

config {
    quality {
        cpd {
            enabled
            ignoreFailures
            minimumTokenCount
            encoding
            language
            ignoreLiterals
            ignoreIdentifiers
            ignoreAnnotations
            toolVersion
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.cpd plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

minimumTokenCount

int

no

50

encoding

String

no

UTF-8

language

String

no

java

ignoreLiterals

boolean

no

false

Ignore number values and string contents when comparing text.

ignoreIdentifiers

boolean

no

false

Ignore constant and variable names when comparing text.

ignoreAnnotations

boolean

no

false

Ignore language annotations when comparing text.

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.9.2. Tasks

AggregateCpd

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

Name

aggregateCpd

Type

org.kordamp.gradle.plugin.cpd.Cpd

Properties
reports.html.destination

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

reports.xml.destination

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

AllCpd

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

Name

allCpd

Type

org.kordamp.gradle.plugin.cpd.Cpd

Properties
reports.html.destination

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

reports.xml.destination

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

7.10. Detekt

id

org.kordamp.gradle.detekt

class

org.kordamp.gradle.plugin.detekt.DetektPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
io.gitlab.arturbosch.detekt.detekt

Configures Detekt on Kotlin projects and aggregate reports on the root project.

7.10.1. DSL

config {
    quality {
        detekt {
            enabled
            ignoreFailures
            configFile
            baselineFile
            parallel
            failFast
            buildUponDefaultConfig
            disableDefaultRuleSets
            toolVersion
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.detekt plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

configFile

Set<String>

no

baselineFile

Set<String>

no

parallel

boolean

no

yes

failFast

boolean

no

no

buildUponDefaultConfig

boolean

no

no

disableDefaultRuleSets

boolean

no

no

toolVersion

String

no

1.2.2

excludedSourceSets

Set<String>

no

[]

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

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

  • Explicit value if set in the build file.

  • config/detekt/${project.name}-${sourceSetName}.yml

  • config/detekt/${project.name}.yml

  • config/detekt/detekt-${sourceSetName}.yml

  • config/detekt/detekt.yml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.10.2. Tasks

AggregateDetekt

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

Name

aggregateDetekt

Type

io.gitlab.arturbosch.detekt.Detekt

Properties
reports.html.destination

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

reports.xml.destination

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

AllDetekt

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

Name

allDetekt

Type

io.gitlab.arturbosch.detekt.Detekt

Properties
reports.html.destination

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

reports.xml.destination

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

7.11. 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.11.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.errorprone plugin if false

disableAllChecks

boolean

no

false

allErrorsAsWarnings

boolean

no

false

allDisabledChecksAsWarnings

boolean

no

false

disableWarningsInGeneratedCode

boolean

no

true

ignoreUnknownCheckNames

boolean

no

false

ignoreSuppressionAnnotations

boolean

no

false

compilingTestOnlyCode

boolean

no

false

excludedPaths

String

no

errorProneVersion

String

no

2.3.4

errorProneJavacVersion

String

no

9+181-r4173-1

7.12. 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|kotlin|scala].

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

  • 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.13. GroovyProject

id

org.kordamp.gradle.groovy-project

class

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

applies

org.kordamp.gradle.java-project

Configures a project with Groovy conventions.

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

7.13.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.13.2. Rules

CompileGroovy
Pattern

compile<SourceSetName>GroovySettings

Type

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

7.14. Groovydoc

id

org.kordamp.gradle.groovydoc

class

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

applies

org.kordamp.gradle.base,
groovy

Generates and packages Groovydoc documentation.

7.14.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.groovydoc plugin if false

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

options

Name Type Required Default Value Description

windowTitle

String

no

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

docTitle

String

no

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

header

String

no

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

footer

String

no

overviewText

TextResource

no

links

Set<Link>

no

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

noTimestamp

boolean

no

noVersionStamp

boolean

no

includePrivate

boolean

no

true

use

boolean

no

true

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

fast

boolean

no

true

Does not execute child groovydoc tasks if true

replaceJavadoc

boolean

no

false

Disables aggregateJavadoc and applies the javadoc classifier

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.14.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.15. 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.15.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.guide plugin if false

publish

Name Type Required Default Value Description

enabled

boolean

no

false

Disables publication of guide if false

branch

String

no

'gh-pages'

Git branch

message

String

no

"Publish guide for ${project.version}"

Commit message

7.15.2. Extension

guide {
    javadocApiDir
    groovydocApiDir
    kotlindocApiDir
    sourceHtmlDir
    sourceXrefDir
}
Name Type Required Default Value Description

javadocApiDir

String

no

'api'

Director where javadoc will be copied

groovydocApiDir

String

no

'gapi'

Director where groovydoc will be copied

kotlindocApiDir

String

no

'kapi'

Director where kotlindoc will be copied

sourceHtmlDir

String

no

'api-html'

Director where source-html will be copied

sourceXrefDir

String

no

'api-xref'

Director where source-xref will be copied

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

  • aggregateKotlindocHtml (if enabled)

  • aggregateSourceHtml (if enabled)

  • aggregateSourceXref (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.16. 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|kotlin|scala].

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

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

7.17. JaCoCo

id

org.kordamp.gradle.jacoco

class

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

applies

org.kordamp.gradle.base,
jacoco

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

7.17.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.jacoco plugin if false

aggregateExecFile

File

no

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

Location for the aggregate merge execution data file

aggregateReportHtmlFile

File

no

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

Location for aggregate HTML reports

aggregateReportXmlFile

File

no

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

Location for the aggregate XML report

additionalSourceDirs

FileCollection

no

[]

Additional source directories

additionalClassDirs

FileCollection

no

[]

Additional class directories

toolVersion

String

no

0.8.5

excludes

Set<String>

no

[]

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

This block is optional.

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

7.17.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.18. 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

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

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.18.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 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")
    }
}

7.18.2. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.jar plugin if false

This block is optional.

manifest

Name Type Required Default Value Description

enabled

boolean

no

false

Enables or disables manifest customizations

addClasspath

boolean

no

false

Whether to create a Class-Path manifest entry

classpathPrefix

String

no

''

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

classpathLayoutType

String

no

simple

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

7.19. JavaProject

id

org.kordamp.gradle.java-project

class

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

applies

org.kordamp.gradle.project

Configures a project with Java conventions.

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

7.19.1. Extensions

cfg

Configures dependencies based on settings available from config.dependencies.

Name

cfg

Type

org.kordamp.gradle.plugin.project.DependencyHandler

Applied to

org.gradle.api.artifacts.dsl.DependencyHandler

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 if none are specified: api, implementation, annotationProcessor, testImplementation, testAnnotationProcessor, compileOnly, testCompileOnly, runtimeOnly, testRuntimeOnly.
Methods
  • void platform(Object notation)

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

  • void platform(Object notation, String…​ configurations)

  • void platform(Object notation, List<String> configurations)

  • void platform(Object notation, List<String> configurations, Action<? super Dependency> action)

  • void enforcedPlatform(Object notation)

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

  • void enforcedPlatform(Object notation, String…​ configurations)

  • void enforcedPlatform(Object notation, List<String> configurations)

  • void enforcedPlatform(Object notation, List<String> configurations, Action<? super Dependency> action)

  • void dependency(String name, String configuration, String…​ configurations)

  • void dependency(String name, String configuration, Closure)

  • void module(String name, String configuration, String…​ configurations)

  • void module(String name, String configuration, Closure)

Example

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

build.gradle
config {
    dependencies {
        dependency('micronaut') {
            platform   = true
            groupId    = 'io.micronaut'
            artifactId = 'micronaut-bom'
            version    = micronautVersion
            modules    = ['micronaut-inject-java',
                          'micronaut-inject-groovy',
                          'micronaut-inject',
                          'micronaut-validation',
                          'micronaut-runtime-groovy']
        }
    }
}

dependencies {
    cfg {
        enforcedPlatform('micronaut')

        module('micronaut','micronaut-inject-java', 'annotationProcessor')
        module('micronaut','micronaut-validation', 'annotationProcessor', 'api')

        module('micronaut','micronaut-inject-groovy', 'compileOnly')
    }

    // you can still use standard configuration methods
    api('io.micronaut:micronaut-inject')

    // you can mix them both
    api(config.dependencies.ga('micronaut', 'micronaut-runtime-groovy'))
}

7.19.2. 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 cfg extension.

Name

platforms

Type

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

Example Output

For a project with the following dependencies

build.gradle
dependencies {
    cfg.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

$ ./gradlew :platforms

Results in the following output

> Task :platforms
Total platforms: 1

Platform 0:
    platform: io.micronaut:micronaut-bom:2.0.0.M3
    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'
    id 'org.kordamp.gradle.project' version '0.37.1'
}

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking this command

$ ./gradlew :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.19.3. 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.20. Javadoc

id

org.kordamp.gradle.javadoc

class

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

applies

org.kordamp.gradle.base

Generates and packages Javadoc documentation.

7.20.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.javadoc plugin if false

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

title

String

no

options

MinimalJavadocOptions

no

Supports all options from StandardJavadocDocletOptions.

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

This block is optional.

Name Type Required Default Value Description

enabled

boolean

no

true

Disables generation of auto links if false

configurations

List<String>

no

['compile', 'compileOnly', 'annotationProcessor', 'runtime']

Configurations to be checked for dependencies

excludes

Set<String>

no

[]

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

useJavadocIo

boolean

no

true

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

Methods
void exclude(String)

Adds a link exclusion rule (Regex pattern).

void offlineLink(String, String)

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

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

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

fast

boolean

no

true

Does not execute child javadoc tasks if true

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.20.2. Tasks

AggregateJavadoc

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

Name

aggregateJavadoc

Type

org.gradle.api.tasks.javadoc.Javadoc

Properties
destinationDir

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

AggregateJavadocJar

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

Name

aggregateJavadocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

javadoc

destinationDir

${rootProject.buildDir}/build/libs

Checks if generated Javadoc auto links are reachable.

Name

checkAutoLinks

Type

org.kordamp.gradle.plugin.javadoc.CheckAutoLinksTask

Javadoc

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

Name

javadoc

Type

org.gradle.api.tasks.javadoc.Javadoc

Properties
destinationDir

${project.buildDir}/docs/javadoc

JavadocJar

An archive of the Javadoc API docs.

Name

javadocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

javadoc

destinationDir

${project.buildDir}/build/libs

from

javadoc.destinationDir

7.21. KotlinProject

id

org.kordamp.gradle.kotlin-project

class

org.kordamp.gradle.plugin.project.kotlin.KotlinProjectPlugin (groovydoc, source)

applies

org.kordamp.gradle.java-project

Configures a project with Kotlin conventions.

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

7.21.1. Tasks

KotlinCompilerSettings

Display Kotlin compiler settings.

Name

kotlinCompilerSettings

Type

org.kordamp.gradle.plugin.project.kotlin.tasks.KotlinCompilerSettingsTask

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.21.2. Rules

CompileKotlin
Pattern

compile<SourceSetName>KotlinSettings

Type

org.kordamp.gradle.plugin.project.kotlin.tasks.KotlinCompilerSettingsTask

7.22. Kotlindoc

id

org.kordamp.gradle.kotlindoc

class

org.kordamp.gradle.plugin.kotlindoc.KotlindocPlugin (kotlindoc, source)

applies

org.kordamp.gradle.base

Generates and packages Kotlin documentation via Dokka.

This plugin relies on the org.jetbrains.dokka plugin but does not apply it.

7.22.1. DSL

config {
    docs {
        kotlindoc {
            enabled
            moduleName
            outputFormats
            outputDirectory
            includes
            samples
            jdkVersion
            cacheRoot
            languageVersion
            apiVersion
            includeNonPublic
            skipDeprecated
            reportUndocumented
            skipEmptyPackages
            noStdlibLink
            impliedPlatforms
            replaceJavadoc
            sourceLinks {
                sourceLink {
                    url
                    path
                    suffix
                }
            }
            externalDocumentationLinks {
                externalDocumentationLink {
                    url
                    packageListUrl
                }
            }
            packageOptions {
                packageOption {
                    prefix
                    includeNonPublic
                    reportUndocumented
                    skipEmptyPackages
                    suppress
                }
            }
            aggregate {
                enabled
                fast
                replaceJavadoc
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.kotlindoc plugin if false

moduleName

String

no

outputFormats

List<String>

no

['html']

Valid values are 'html', 'javadoc', 'html-as-java', 'markdown', 'gfm', 'jekyll'.

outputDirectory

File

no

${project.buildDir}/docs/kotlindoc

Value of outputFormat is appended.

includes

List<Object>

no

[]

List of files with module and package documentation

samples

List<Object>

no

[]

The list of files or directories containing sample code (referenced with @sample tags)

jdkVersion

int

no

6

Used for linking to JDK

cacheRoot

String

no

languageVersion

String

no

apiVersion

String

no

includeNonPublic

boolean

no

false

Use to include or exclude non public members.

skipDeprecated

boolean

no

false

Do not output deprecated members. Applies globally, can be overridden by packageOptions.

reportUndocumented

boolean

no

true

Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions.

skipEmptyPackages

boolean

no

true

Do not create index pages for empty packages.

noStdlibLink

boolean

no

false

No default documentation link to kotlin-stdlib

impliedPlatforms

List<String>

no

['JVM']

Valid values are 'Common', 'JVM', 'JS', 'Native'.

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier.

This block defines data associated with org.jetbrains.dokka.gradle.SourceLink instances.
Each sourceLink instance specifies the location of the project source code on the Web.
If provided, Dokka generates "source" links for each declaration.

Name Type Required Default Value Description

path

String

yes

Source directory, i.e, src/main/kotlin.

url

String

yes

URL showing where the source code can be accessed through the web browser.

suffix

String

no

Suffix which is used to append the line number to the URL. Use #L for GitHub.

This block is optional.

This block defines data associated with org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink instances.
Allows linking to documentation of the project’s dependencies (generated with Javadoc or Dokka).

Name Type Required Default Value Description

url

String

yes

Root URL of the generated documentation to link with. Trailing slash is required!

packageListUrl

String

no

If package-list file located in non-standard location.

This block is optional.

packageOptions

This block defines data associated with org.jetbrains.dokka.gradle.PackageOptions instances.
Allows to customize documentation generation options on a per-package basis.

packageOption

Name Type Required Default Value Description

prefix

String

no

''

includeNonPublic

boolean

no

false

Use to include or exclude non public members.

skipDeprecated

boolean

no

false

Do not output deprecated members.

reportUndocumented

boolean

no

true

Emit warnings about not documented members.

suppress

boolean

no

false

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

fast

boolean

no

true

Does not execute child kotlindoc tasks if true

replaceJavadoc

boolean

no

false

Disables aggregateJavadoc and applies the javadoc classifier

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.22.2. Tasks

AggregateKotlindoc

Generates aggregate Kotlindoc API documentation.
Consumes settings from config.kotlindoc.
This task is added to the root project.

Name

The actual name of this task depends on the configured formats. Possible names are:

  • aggregateKotlindocHtml

  • aggregateKotlindocJavadoc

  • aggregateKotlindocHtmljava

  • aggregateKotlindocMarkdown

  • aggregateKotlindocGfm

  • aggregateKotlindocJekyll

Type

org.jetbrains.dokka.gradle.DokkaTask

Properties
outputDirectory

${project.buildDir}/docs/kotlindoc/aggregate-${format}

AggregateKotlindocJar

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

Name

The actual name of this task depends on the configured formats. Possible names are:

  • aggregateKotlindocHtmlJar

  • aggregateKotlindocJavadocJar

  • aggregateKotlindocHtmljavaJar

  • aggregateKotlindocMarkdownJar

  • aggregateKotlindocGfmJar

  • aggregateKotlindocJekyllJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
destinationDir

${project.buildDir}/build/libs

from

aggregateKotlindoc.outputDirectory

Kotlindoc

Generates Kotlindoc API documentation.
Consumes settings from config.kotlindoc.

Name

The actual name of this task depends on the configured formats. Possible names are:

  • kotlindocHtml

  • kotlindocJavadoc

  • kotlindocHtmljava

  • kotlindocMarkdown

  • kotlindocGfm

  • kotlindocJekyll

Type

org.jetbrains.dokka.gradle.DokkaTask

Properties
outputDirectory

${project.buildDir}/docs/kotlindoc/${format}

KotlindocJar

An archive of the Kotlindoc API docs.

Name

The actual name of this task depends on the configured formats. Possible names are:

  • kotlindocHtmlJar

  • kotlindocJavadocJar

  • kotlindocHtmljavaJar

  • kotlindocMarkdownJar

  • kotlindocGfmJar

  • kotlindocJekyllJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

kotlindoc | javadoc

destinationDir

${project.buildDir}/build/libs

from

kotlindoc.outputDirectory

7.23. Licensing

id

org.kordamp.gradle.licensing

class

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

applies

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

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

7.23.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.licensing plugin if false

mergeStrategy

String

no

merge

Either merge or overwrite

excludedSourceSets

Set<String>

no

[]

licenses

LicenseSet

yes

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

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

license

Name Type Required Default Value Description

id

String

no*

primary

boolean

no*

false

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

name

String

yes

Maps to the <name> block

url

String

no

Maps to the <url> block

distribution

String

no

'repo'

Maps to the <distribution> block

comments

String

no

Maps to the <comments> block

aliases

List<String>

no

[]

List of license aliases

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

Prefer setting a value for the id property. The value of id may be any of org.kordamp.gradle.plugin.base.model.LicenseId, including the literal values for spdx and bintray properties.
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.23.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.23.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'

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

7.24. Minpom

id

org.kordamp.gradle.minpom

class

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

applies

org.kordamp.gradle.base

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

7.24.1. Example

For a project defined as follows

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

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.37.1"
}

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 6.4.1
version=1.0.0
groupId=com.acme
artifactId=sample

7.24.2. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.minpom plugin if false

This block is optional.

7.24.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.25. Plugin

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.25.1. DSL

config {
    plugin {
        enabled
        id
        implementationClass
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.plugin plugin if false

id

String

yes

Defines the plugin’s id

implementationClass

String

yes

Defines the plugin’s implementation Class

7.25.2. Tasks

ListPluginDescriptors

Lists plugin descriptors from plugin declarations.

Name

listPluginDescriptors

Type

org.kordamp.gradle.plugin.plugin.ListPluginDescriptorsTask

7.26. 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.26.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.pmd plugin if false

ignoreFailures

boolean

no

true

Fails the build if set to false.

ruleSetFiles

FileCollection

no

incrementalAnalysis

boolean

no

false

rulePriority

int

no

5

excludedSourceSets

Set<String>

no

[]

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

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

  • Explicit value if set in the build file.

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

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

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

  • config/pmd/pmd.xml

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.26.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.27. Profiles

id

org.kordamp.gradle.profiles

class

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

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.27.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.27.2. Activations

There are 5 types of activations available in the profiles DSL

os
os {
    name(String)
    arch(String)
    version(String)
    release(String)
    classifier(String)
    classifierWithLikes(List<String>)
}

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

name

The expected OS name.

arch

The expected OS architecture.

version

The expected OS version.

release

The expected OS release (Linux).

classifier

The expected OS classifier.

classifierWithLikes

Additional classifiers.

jdk
jdk {
    version(String)
}
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).

file
file {
    exists(String)
    exists(File)
    exists(RegularFile)
    missing(String)
    missing(File)
    missing(RegularFile)
}
exists

The given file must exist.

missing

The given file must not exist.

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

The name of the property (required).

value

The Value of the property (optional).

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.27.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
./gradlew -Pprofile=jdk9,prod build
Builds with jdk11 profile only
./gradlew -Pprofile=jdk11 build

In both cases the test profile remains inactive.

7.27.4. System Properties

profiles.enabled

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

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

Example Output
$ ./gradlew :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.29. 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.29.1. DSL

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

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

enabled

boolean

no

true

Enables or disables processing of the target format.

 overwrite

boolean

no

true

Whether to overwrite existing properties or not.

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

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

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/kotlindoc/scaladoc JARs. Artifacts will be automatically signed if the uploadArchives task is present.

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.30.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.publishing plugin if false

signing

boolean

no

false

Enables signing of all artifacts associated with main

releasesRepository

String

no

Name of a Maven compatible repository for publishing releases

snapshotsRepository

String

no

Name of a Maven compatible repository for publishing snapshots

publications

List<String>

no

[]

Publication names to be included

scopes

List<String>

no

[]

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

flattenPlatforms

boolean

no

false

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

useVersionExpressions

boolean

no

true

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

This block is optional.

pom

Name Type Required Default Value Description

packaging

String

no

jar

Defines the value for <packaging>

properties

Map<String, String>

no

[:]

Maps to <properties> block.

parent

String

no

Defines the coordinates of the parent POM

overwriteInceptionYear

boolean

no

false

Overwrite <inceptionYear> from parent POM

overwriteUrl

boolean

no

false

Overwrite <url> from parent POM

overwriteLicenses

boolean

no

false

Overwrite <licenses> from parent POM

overwriteScm

boolean

no

false

Overwrite <scm> from parent POM

overwriteOrganization

boolean

no

false

Overwrite <organization> from parent POM

overwriteDevelopers

boolean

no

false

Overwrite <developers> from parent POM

overwriteContributors

boolean

no

false

Overwrite <contributors> from parent POM

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

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

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

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

This block is optional.

7.30.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 = true
        releasesRepository  = 'mavenRelease'
        snapshotsRepository = 'mavenSnapshot'
    }
}

7.30.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.30.4. Rules

Publications
Pattern

<PublicationName>PublicationSettings

Type

org.kordamp.gradle.plugin.publishing.PublicationSettingsTask

7.31. ScalaProject

id

org.kordamp.gradle.scala-project

class

org.kordamp.gradle.plugin.project.scala.ScalaProjectPlugin (groovydoc, source)

applies

org.kordamp.gradle.java-project

Configures a project with Scala conventions.

7.31.1. Tasks

ScalaCompilerSettings

Display Scala compiler settings.

Name

scalaCompilerSettings

Type

org.kordamp.gradle.plugin.project.scala.tasks.ScalaCompilerSettingsTask

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.31.2. Rules

CompileScala
Pattern

compile<SourceSetName>ScalaSettings

Type

org.kordamp.gradle.plugin.project.scala.tasks.ScalaCompilerSettingsTask

7.32. Scaladoc

id

org.kordamp.gradle.scaladoc

class

org.kordamp.gradle.plugin.scaladoc.ScaladocPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Generates and packages Scaladoc documentation.

7.32.1. DSL

config {
    docs {
        scaladoc {
            enabled
            title
            includes
            excludes
            replaceJavadoc
            options {
                bottom
                top
                docTitle
                deprecation
                unchecked
                additionalParameters
            }
            aggregate {
                enabled
                fast
                replaceJavadoc
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.scaladoc plugin if false

title

String

no

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

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

options

Name Type Required Default Value Description

bottom

String

no

top

String

no

docTitle

String

no

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

deprecation

boolean

no

unchecked

boolean

no

additionalParameters

List<String>

no

[]

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

fast

boolean

no

true

Does not execute child scaladoc tasks if true

replaceJavadoc

boolean

no

false

Disables aggregateJavadoc and applies the javadoc classifier

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.32.2. Tasks

AggregateScaladoc

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

Name

aggregateScaladoc

Type

org.gradle.api.tasks.scala.ScalaDoc

Properties
destinationDir

${rootProject.buildDir}/docs/scaladoc

AggregateScaladocJar

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

Name

aggregateScaladocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

scaladoc

destinationDir

${rootProject.buildDir}/build/libs

Scaladoc

Generates Scaladoc API documentation.
Consumes settings from config.scaladoc.

Name

scaladoc

Type

org.gradle.api.tasks.scala.ScalaDoc

Properties
destinationDir

${project.buildDir}/docs/aggregate-scaladoc

ScaladocJar

An archive of the Scaladoc API docs.

Name

scaladocJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

scaladoc

destinationDir

${project.buildDir}/build/libs

from

scaladoc.destinationDir

7.33. 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.33.1. DSL

projects {
    layout
    enforceNamingConvention
    directories
    excludes
    fileNameTransformation
    prefix
    suffix

    includeFromDir(String)
        .exclude(String)          // optional
        .when(boolean)            // optional
    includeFromDir(String)
        .exclude(String)          // optional
        .when(Supplier<Boolean>)  // optional

    includeFromPath(String)
         .when(boolean)           // optional
    includeFromPath(String)
        .when(Supplier<Boolean>)  // optional

    plugins { }
}
Name Type Required Default Value Description

layout

String

no

two-level

Defines the project layout. Valid values are [two-level, multi-level, standard, explicit].

 enforceNamingConvention

boolean

no

true

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

 useLongPaths

boolean

no

false

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

 directories

List<String>

no*

[]

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

 excludes

List<String>

no

[]

List of directories to be excluded from automatic inclusion.

 fileNameTransformation

String

no

Transformation applied to build file name. Valid values are [add, remove].

prefix

String

no

Prefix added/removed from build file name.

suffix

String

no

Suffix added/removed from build file name.

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

Methods

The following methods should be used when the chosen layout is explicit, otherwise no additional projects will be discovered and included in the build

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

exclude(String)
Excludes a project directory by name.

includeFromPath(String path)
Includes projects found under the given path unless the given condition (when()) evaluates to false.

7.33.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.37.1'
    }
}
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.37.1")
    }
}
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.37.1'
    }
}
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.37.1")
    }
}
apply(plugin = "org.kordamp.gradle.settings")

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    layout = "multi-level"
    directories = listOf(
        "guide",
        "subprojects/project1",
        "subprojects/project2"
    )
}
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.37.1'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

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

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    layout = "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.37.1'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

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

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    layout = "explicit"
    includeFromPath("guide")
    includeFromDir("subprojects")
}

7.34. SourceJar

id

org.kordamp.gradle.source-jar

class

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

applies

org.kordamp.gradle.base

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

7.34.1. DSL

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

enabled

boolean

no

true

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

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.34.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.35. SourceHtml

id

org.kordamp.gradle.source-html

class

org.kordamp.gradle.plugin.sourcehtml.SourceHtmlPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Converts source code into HTML with syntax highlighting.

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

7.35.1. DSL

config {
    docs {
        sourceHtml {
            enabled
            conversion {
                srcDirs
                destDir
                includes
                outputFormat
                tabs
                style
                lineAnchorPrefix
                horizontalAlignment
                showLineNumbers
                showFileName
                showDefaultTitle
                showTableBorder
                includeDocumentHeader
                includeDocumentFooter
                addLineAnchors
                useShortFileName
                overwrite
            }
            overview {
                destDir
                pattern
                windowTitle
                docTitle
                docDescription
                icon
                stylesheet
            }
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

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

conversion

Name Type Required Default Value Description

srcDirs

FileCollection

no

destDir

File

no

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

includes

String

no

'**/*.java,**/*.groovy'

outputFormat

String

no

'html'

tabs

int

no

4

style

String

no

'kawa'

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

lineAnchorPrefix

String

no

''

horizontalAlignment

String

no

'left'

showLineNumbers

boolean

no

true

showFileName

boolean

no

true

showDefaultTitle

boolean

no

true

showTableBorder

boolean

no

false

includeDocumentHeader

boolean

no

true

includeDocumentFooter

boolean

no

true

addLineAnchors

boolean

no

true

useShortFileName

boolean

no

true

overwrite

boolean

no

true

overview

Name Type Required Default Value Description

destDir

File

no

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

pattern

String

no

'**/*.html'

windowTitle

String

no

"$project.name $project.version"

docTitle

String

no

"$project.name $project.version"

docDescription

String

no

icon

File

no

stylesheet

File

no

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.35.2. Tasks

AggregateConvertCodeToHtml

Converts source code files to Java2HTML documentation.
This task is added to the root project.

Name

aggregateConvertCodeToHtml

Type

com.bmuschko.gradle.java2html.ConvertCodeTask

Properties

Consumes all settings found in the config.docs.sourceHtml.conversion block.

AggregateGenerateSourceHtmlOverview

Generates HTML overview files for Java2HTML documentation.
This task is added to the root project.

Name

aggregateGenerateSourceHtmlOverview

Type

com.bmuschko.gradle.java2html.GenerateOverviewTask

Properties

Consumes all settings found in the config.docs.sourceHtml.overview block.

AggregateSourceHtml

Collects the results of the aggregateConvertCodeToHtml and aggregateGenerateSourceHtmlOverview tasks.
This task is added to the root project.

Name

aggregateSourceHtml

Type

org.gradle.api.tasks.Copy

Properties
destinationDir

${rootProject.buildDir}/docs/aggregate-source-html

AggregateSourceHtmlJar

Generates an archive of the aggregateSourceHtml tasks.
This task is added to the root project.

Name

aggregateSourceHtmlJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
destinationDir

${rootProject.buildDir}/build/libs

ConvertCodeToHtml

Converts source code files to Java2HTML documentation.

Name

convertCodeToHtml

Type

com.bmuschko.gradle.java2html.ConvertCodeTask

Properties

Consumes all settings found in the config.docs.sourceHtml.conversion block.

GenerateSourceHtmlOverview

Generates HTML overview files for Java2HTML documentation.

Name

generateSourceHtmlOverview

Type

com.bmuschko.gradle.java2html.GenerateOverviewTask

Properties

Consumes all settings found in the config.docs.sourceHtml.overview block.

SourceHtml

Collects the results of the convertCodeToHtml and generateSourceHtmlOverview tasks.

Name

sourceHtml

Type

org.gradle.api.tasks.Copy

Properties
destinationDir

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

7.36. SourceStats

id

org.kordamp.gradle.source-stats

class

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

applies

org.kordamp.gradle.base

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

7.36.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.36.2. DSL

config {
    stats {
        enabled
        counters
        formats
        paths
        aggregate {
            enabled
            excludedProjects
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

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

counters

Map<String, String>

no

[:]

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

formats

List<String>

no

[]

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

paths

Map<String, Map<String, String>>

no

[:]

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

This block is optional.

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.36.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.37. SourceXref

id

org.kordamp.gradle.source-xref

class

org.kordamp.gradle.plugin.sourcexref.SourceXrefPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Converts source code into HTML with syntax highlighting using the Maven JXR project.

7.37.1. DSL

config {
    docs {
        sourceXref {
            enabled
            templateDir
            inputEncoding
            outputEncoding
            windowTitle
            docTitle
            bottom
            stylesheet
            javaVersion
            excludes
            includes
            aggregate {
                enabled
                excludedProjects
            }
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

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

 templateDir

String

no

 inputEncoding

String

no

UTF-8

 outputEncoding

String

no

UTF-8

 windowTitle

String

no

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

 docTitle

String

no

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

 bottom

String

no

 stylesheet

String

no

 javaVersion

String

no

JavaVersion.current()

 excludes

Set<String>

no

[]

 includes

Set<String>

no

[]

Methods
void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.37.2. Tasks

AggregateSourceXref

Generates a JXR report of all Java source code found in all projects.
This task is added to the root project.

Name

aggregateSourceXref

Type

org.kordamp.gradle.plugin.sourcexref.JxrTask

Properties
outputDir

${project.buildDir}/docs/aggregate-source-xref

Consumes all settings found in the config.docs.sourceXref.conversion block.

AggregateSourceXrefJar

Generates an archive of the aggregateSourceXref tasks.
This task is added to the root project.

Name

aggregateSourceXrefJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
destinationDir

${rootProject.buildDir}/build/libs

SourceXref

Generates a JXR report of all Java source code found in this project.

Name

sourceXref

Type

org.kordamp.gradle.plugin.sourcexref.JxrTask

Properties
outputDir

${project.buildDir}/docs/source-xref

Consumes all settings found in the config.docs.sourceXref.conversion block.

7.38. 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.38.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.spotbugs plugin if false

includeFilterFile

File

no

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

excludeFilterFile

File

no

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

excludeBugsFilterFile

File

no

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

effort

String

no

max

reportLevel

String

no

high

report

String

no

html

Either html or xml

visitors

List<String>

no

[]

omitVisitors

List<String>

no

[]

extraArgs

List<String>

no

[]

jvmArgs

List<String>

no

[]

ignoreFailures

boolean

no

true

Fails the build if set to false.

showProgress

boolean

no

true

toolVersion

String

no

3.1.12

excludedSourceSets

Set<String>

no

[]

Methods
void excludeSourceSet(String)

Adds a sourceSet exclusion.

void exclude(String)

Adds a source exclusion rule (Ant pattern).

void include(String)

Adds a source inclusion rule (Ant pattern).

aggregate

Name Type Required Default Value Description

enabled

boolean

no

true

Enables or disables aggregation

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block should be configured on the root project.

7.38.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.39. 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.
For kotlin projects, if org.kordamp.gradle.detekt is enabled, the output of the aggregateDetekt task is also 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.39.1. DSL

config {
    quality {
        sonar {
            enabled
            hostUrl
            username
            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

username

String

yes

The login or authentication token of a SonarQube user with Execute Analysis permission on the project.

projectKey

String

no

$username + '_' + ${project.rootProject.name}

The project’s unique key.

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

'build/reports/detekt/aggregate.xml'

sonar.kotlin.detekt.reportPaths

if detekt 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.39.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.40. Testing

id

org.kordamp.gradle.testing

class

org.kordamp.gradle.plugin.testing.TestingPlugin (groovydoc, source)

applies

org.kordamp.gradle.base

Configures test reports.

7.40.1. DSL

config {
    testing {
        enabled
        logging
        aggregate
        integration {
            logging
            aggregate
            baseDir
        }
        functional {
            logging
            aggregate
            baseDir
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.test plugin if false

 logging

boolean

no

true

Enables verbose output

 aggregate

boolean

no

true

Enables test report aggregation

integration

Name Type Required Default Value Description

 logging

boolean

no

true

Enables verbose output

 aggregate

boolean

no

true

Enables test report aggregation

baseDir

String

no

src/integration-test

functional

Name Type Required Default Value Description

 logging

boolean

no

true

Enables verbose output

 aggregate

boolean

no

true

Enables test report aggregation

baseDir

String

no

src/functional-test

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