1. Introduction

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

1.1. Rationale

The Gradle Build Tool is a very flexible and extensible tool, 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 built 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 structure.

The following sections describe the conventions and each one 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.20.0'
    }
}
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.20.0")
    }
}
apply(plugin = "{plugin-id}")

Option #2

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

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

2.1. Requirements

Java 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 1 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().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.20.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

rootProject.name = 'root'

projects {
    directories = ['docs', 'subprojects']
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.20.0")
    }
}
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.project' version '0.20.0'            (1)
    id 'org.kordamp.gradle.bintray' version '0.20.0'            (1)
}

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

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

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

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

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

    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.project") version "0.20.0"          (1)
    id("org.kordamp.gradle.bintray") version "0.20.0"          (1)
}

val bintrayUsername: String by project
val bintrayApiKey: String by project
val releaseActive: Boolean? = rootProject.findProperty("release") as Boolean?

config {
    release = if (releaseActive != null) releaseActive!! else false       (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 Javadocs.

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

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

4. Project DSL

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

The DSL is comprised by the following elements

config {
    info { ... }
    apidoc { ... }
    bintray { ... }
    bom { ... }
    buildInfo { ... }
    buildScan { ... }
    clirr { ... }
    groovydoc { ... }
    jacoco { ... }
    javadoc { ... }
    kotlindoc { ... }
    licensing { ... }
    minpom { ... }
    plugin { ... }
    publishing { ... }
    scaladoc { ... }
    source { ... }
    sourceHtml { ... }
    sourceXref { ... }
    stats { ... }
    testing { ... }
}

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

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

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

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

5.1. Apidoc

id

org.kordamp.gradle.apidoc

class

org.kordamp.gradle.plugin.apidoc.ApidocPlugin (groovydoc, source)

applies

org.kordamp.gradle.base,
org.kordamp.gradle.javadoc,
org.kordamp.gradle.groovydoc

Responsible for aggregating API docs. Currently Javadocs (Java) and Groovydocs (Groovy) are supported.

5.1.1. DSL

config {
    apidoc {
        enabled
        replaceJavadoc
        excludedProjects
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.apidoc plugin if false

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block is optional.

5.1.2. Tasks

AggregateJavadocs

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

aggregateJavadocs

Type

org.gradle.api.tasks.javadoc.Javadoc

Properties
destinationDir

${rootProject.buildDir}/docs/javadoc

AggregateJavadocsJar

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

Name

aggregateJavadocsJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

javadoc

destinationDir

${rootProject.buildDir}/build/libs

AggregateGroovydocs

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

aggregateGroovydocs

Type

org.gradle.api.tasks.javadoc.Groovydoc

Properties
destinationDir

${rootProject.buildDir}/docs/groovydoc

AggregateGroovydocsJar

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

Name

aggregateGroovydocsJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

groovydoc

destinationDir

${rootProject.buildDir}/build/libs

AggregateApidocs

Aggregates all API docs for all projects.
This task is added to the root project.

Name

aggregateApidocs

Type

org.gradle.api.DefaultTask

DependsOn

aggregateJavadocs (if enabled)
aggregateGroovydocs (if enabled)

5.2. Base

id

org.kordamp.gradle.base

class

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

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

5.2.1. DSL

config {
    release
    info {
        name
        description
        inceptionYear
        vendor
        tags

        links {
            website
            issueTracker
            scm
        }

        scm {
            url
            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
            }
        }
    }
}

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

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

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.

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.

System Properties
org.kordamp.gradle.base.validate

Perform validation on DSL settings. Defaults to true.

5.2.2. Tasks

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.

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

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :extensions

Results in the following output

> Task :extensions
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: reporting
    type: org.gradle.api.reporting.ReportingExtension

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

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

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

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

extension 8:
    name: effectiveConfig
    type: org.kordamp.gradle.plugin.base.ProjectConfigurationExtension

extension 9:
    name: versioning
    type: net.nemerosa.versioning.VersioningExtension
GroovyCompilerSettings

Display compiler configuration

Name

groovyCompilerSettings

Type

org.kordamp.gradle.plugin.base.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.

JavaCompilerSettings

Display compiler configuration

Name

javaCompilerSettings

Type

org.kordamp.gradle.plugin.base.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.

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

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.20.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'
build.gradle
plugins {
    id 'org.kordamp.gradle.project' version '0.20.0'
}

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

config {
    licensing  { enabled = false }

    publishing { enabled = false }
}

Invoking these command

$ ./gradlew :plugins

Results in the following output

> Task :plugins
plugin 0:
    id: build-init
    implementationClass: org.gradle.buildinit.plugins.BuildInitPlugin

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

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

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: reporting-base
    implementationClass: org.gradle.api.plugins.ReportingBasePlugin

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

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

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: 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: org.kordamp.gradle.build-info
    implementationClass: org.kordamp.gradle.plugin.buildinfo.BuildInfoPlugin
    enabled: true

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

plugin 15:
    id: org.kordamp.gradle.javadoc
    implementationClass: org.kordamp.gradle.plugin.javadoc.JavadocPlugin
    enabled: true

plugin 16:
    id: org.kordamp.gradle.groovydoc
    implementationClass: org.kordamp.gradle.plugin.groovydoc.GroovydocPlugin
    enabled: false

plugin 17:
    id: org.kordamp.gradle.apidoc
    implementationClass: org.kordamp.gradle.plugin.apidoc.ApidocPlugin
    enabled: true

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

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

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

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

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.bintray
    implementationClass: org.kordamp.gradle.plugin.bintray.BintrayPlugin
    enabled: true

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

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

plugin 27:
    id: org.kordamp.gradle.project
    implementationClass: org.kordamp.gradle.plugin.project.ProjectPlugin

plugin 28:
    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.

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

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

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

Display test task configuration

Name

testSettings

Type

org.kordamp.gradle.plugin.base.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.

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

5.3.1. DSL

config {
    bintray {
        enabled
        credentials {
            username
            password
        }
        name
        repo
        userOrg
        githubRepo
        skipMavenSync
        publications
    }
}
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

No not sync with Maven Central

publications

List<String>

no

['main']

Configures the publications that should be published to Bintray.

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

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

5.4.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>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>project1</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>project2</artifactId>
        <version>${project.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

5.4.2. DSL

config {
    bom {
        autoIncludes
        enabled
        compile
        runtime
        test
        excludes
        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

compile

Set<String>

no

[]

Dependencies that should be added to the compile scope

runtime

Set<String>

no

[]

Dependencies that should be added to the runtime scope

test

Set<String>

no

[]

Dependencies that should be added to the test scope

excludes

Set<String>

no

[]

Names of subprojects tat should not be included

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
compile(String)

Add a dependency to the compile scope. Its value may be a project name or a dependency definition such as 'group:artifactId:version'.

runtime(String)

Add a dependency to the runtime scope. Its value may be a project name or a dependency definition such as 'group:artifactId:version'.

test(String)

Add a dependency to the test scope. Its value may be a project name or a dependency definition such as 'group:artifactId:version'.

exclude(String)

Skips the named project from being added to the BOM.

5.5. 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]

 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.

5.5.1. DSL

config {
    buildInfo {
        enabled
        clearTime
        skipBuildBy
        skipBuildDate
        skipBuildTime
        skipBuildRevision
        skipBuildJdk
        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

skipBuildCreatedBy

boolean

no

false

Skips calculating this value

5.6. BuildScan

id

org.kordamp.gradle.build-scan

class

org.kordamp.gradle.plugin.buildscan.BuildScanPlugin (groovydoc, source)

applies

org.kordamp.gradle.base
com.gradle.build-scan

Configures the com.gradle.build-scan plugin and enables conditional agreement on the terms of service.

You may define a System property build.scan.agree when invoking a build to set the value of the build scan agreement on the spot. You may also set this value at the project or global level. The precendence for evaluating the agreement is thus

  1. explicitly set on the buildScan.termsOfServiceUrl property.

  2. the build.scan.agree System property.

  3. the local project build scan agreement file.

  4. the global build scan agreement file.

You may create, remove, query the local and global build scan files with the tasks exposed by this plugin. Scans must be enabled by either specifying the --scan flag or buildScan.publishAlways().

5.6.1. DSL

config {
    buildScan {
        enabled
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

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

5.6.2. Tasks

ListBuildScanAgreementTask

Lists the agreements at both project and global levels.

Name

listBuildScanAgreementTask

Type

org.kordamp.gradle.plugin.buildscan.ListBuildScanAgreementTask

Example
$ gradle listBuildScanAgreements

> Task :listBuildScanAgreements
Project: no
Global:  yes
RemoveBuildScanAgreement

Removes the agreement value at either project or global level.

Name

removeBuildScanAgreement

Type

org.kordamp.gradle.plugin.buildscan.BuildScanAgreementTask

Options
location

The location of the agreement file. Valid values are project, global.

Example
$ gradle removeBuildScanAgreement --location=project
SetBuildScanAgreement

Sets the agreement value at either project or global level.

Name

setBuildScanAgreement

Type

org.kordamp.gradle.plugin.buildscan.BuildScanAgreementTask

Options
location

The location of the agreement file. Valid values are project, global.

agree

The value of the agreement. Must be either yes or no.

Example
$ gradle setBuildScanAgreement --location=global --agree=yes

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

5.7.1. DSL

config {
    clirr {
        enabled
        baseline
        filterFile
        filter
        failOnErrors
        failOnException
        semver
    }
}
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.

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

5.7.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(':')
}

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

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

5.8. 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 src/main/[java|groovy|kotlin|scala].

  • Create a Test task named functionalTest pointing to src/functional-test/[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.

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

5.9.1. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.groovydoc plugin if false

includes

Set<String>

no

[]

excludes

Set<String>

no

[]

replaceJavadoc

boolean

no

false

Disables javadocJar and applies the javadoc classifier

options

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

[]

noTimestamp

boolean

no

noVersionStamp

boolean

no

includePrivate

boolean

no

true

use

boolean

no

true

This block is optional.

5.9.2. Tasks

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

5.10. 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.kordamp.gradle.apidoc, (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'

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

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

  • aggregateJavadocs (if enabled)

  • aggregateGroovydocs (if enabled)

  • aggregateSourceHtml (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}

5.11. 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 src/main/[java|groovy|kotlin|scala].

  • Create a Test task named integrationTest pointing to src/integration-test/[java|groovy|kotlin|scala].

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

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

5.12.1. DSL

config {
    jacoco {
        enabled
        mergeExecFile
        mergeReportHtmlFile
        mergeReportXmlFile
        additionalSourceDirs
        additionalClassDirs
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

Disables org.kordamp.gradle.jacoco plugin if false

mergeExecFile

File

no

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

Location for the root merge execution data file

mergeReportHtmlFile

File

no

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

Location for root HTML reports

mergeReportXmlFile

File

no

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

Location for the root XML report

additionalSourceDirs

FileCollection

no

[]

Additional source directories

additionalClassDirs

FileCollection

no

[]

Additional class directories

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

This block is optional.

5.12.2. Tasks

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

JacocoRootMerge

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

jacocoRootMerge

Type

org.gradle.testing.jacoco.tasks.JacocoMerge

Properties
destinationFile

config.jacoco.mergeExecFile

JacocoRootReport

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

jacocoRootReport

Type

org.gradle.testing.jacoco.tasks.JacocoReport

Properties
reports.html.destination

config.jacoco.mergeReportHtmlFile

reports.xml.destination

config..jacoco.mergeReportXmlFile

reports.html.enabled

true

reports.xml.enabled

true

5.13. 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.effectiveConfig.buildInfo.buildCreatedBy

Built-By

rootProject.extensions.effectiveConfig.buildInfo.buildBy

Build-Jdk

rootProject.extensions.effectiveConfig.buildInfo.buildJdk

Build-Date

rootProject.extensions.effectiveConfig.buildInfo.buildDate

Build-Time

rootProject.extensions.effectiveConfig.buildInfo.buildTime

Build-Revision

rootProject.extensions.effectiveConfig.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

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

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

5.14.1. DSL

config {
    javadoc {
        enabled
        includes
        excludes
        title
        options { ... }
        <<_javadoc_autolinks,autoLinks>> {
            enabled
            configurations
            excludes
        }
    }
}
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.

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

5.14.2. Tasks

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

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

5.15.1. DSL

config {
    kotlindoc {
        enabled
        moduleName
        outputFormats
        outputDirectory
        includes
        samples
        jdkVersion
        cacheRoot
        languageVersion
        apiVersion
        includeNonPublic
        skipDeprecated
        reportUndocumented
        skipEmptyPackages
        noStdlibLink
        impliedPlatforms
        replaceJavadoc
        linkMappings {
            linkMapping {
                dir
                url
                path
            }
        }
        externalDocumentationLinks {
            externalDocumentationLink {
                url
                packageListUrl
            }
        }
        packageOptions {
            packageOption {
                prefix
                includeNonPublic
                reportUndocumented
                skipEmptyPackages
                suppress
            }
        }
    }
}
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

o 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.LinkMapping instances.
Each linkMapping 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

dir

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.

path

String

yes

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.

5.15.2. Tasks

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

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

5.16.1. DSL

config {
    licensing {
        enabled
        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

licenses

LicenseSet

yes

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

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.

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

5.16.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'

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

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

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

5.17.1. Example

For a project defined as follows

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

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

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

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

dependencies {
    compile("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 5.4
version=1.0.0
groupId=com.acme
artifactId=sample

5.17.2. DSL

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

enabled

boolean

no

true

Disables org.kordamp.gradle.minpom plugin if false

This block is optional.

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

5.18. Project

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

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

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

NOTE

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

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

5.19.2. Tasks

ListPluginDescriptors

Lists plugin descriptors from plugin declarations.

Name

listPluginDescriptors

Type

org.kordamp.gradle.plugin.plugin.ListPluginDescriptorsTask

5.20. Publishing

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.

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.

5.20.1. DSL

config {
    publishing {
        enabled
        signing
        releasesRepository
        snapshotsRepository
        pom  {
            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

This block is optional.

pom

Name Type Required Default Value Description

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.

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

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

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

5.21.1. DSL

config {
    scaladoc {
        enabled
        title
        includes
        excludes
        excludedProjects
        options {
            bottom
            top
            docTitle
            deprecation
            unchecked
            additionalParameters
        }
    }
}
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

[]

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

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.

5.21.2. Tasks

Scaladoc

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

Name

scaladoc

Type

org.gradle.api.tasks.scala.ScalaDoc

Properties
destinationDir

${project.buildDir}/docs/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

AggregateScaladocs

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

aggregateScaladocs

Type

org.gradle.api.tasks.scala.ScalaDoc

Properties
destinationDir

${rootProject.buildDir}/docs/scaladoc

AggregateScaladocsJar

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

Name

aggregateScaladocsJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

scaladoc

destinationDir

${rootProject.buildDir}/build/libs

5.22. Settings

id

org.kordamp.gradle.settings

class

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

Note

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.

5.22.1. DSL

projects {
    layout
    enforceNamingConvention
    directories
    excludes
}
Name Type Required Default Value Description

layout

boolean

no

two-level

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

 enforceNamingConvention

boolean

no

true

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

 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.

The directories property is not required if the chosen layout is set to standard. 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).

5.22.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.20.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

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

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

A project with the following structure

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

Can be configured as follows

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

projects {
    layout = 'multi-level'
    directories = [
        'guide',
        'subprojects/project1',
        'subprojects/project2'
    ]
}
settings.gradle.kts
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("org.kordamp.gradle:settings-gradle-plugin:0.20.0")
    }
}
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.20.0'
    }
}
apply plugin: 'org.kordamp.gradle.settings'

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

configure<org.kordamp.gradle.plugin.settings.ProjectsExtension> {
    layout = "standard"
}

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

5.23.1. DSL

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

enabled

boolean

no

true

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

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

This block is optional.

5.23.2. Tasks

SourceJar

An archive of the source code.

Name

sourceJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
classifier

sources

destinationDir

${project.buildDir}/build/libs

from

project.sourceSets.main.allSource

AggregateSourceJar

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

Name

aggregateSourceJar

Type

org.gradle.api.tasks.bundling.Jar

Properties
destinationDir

${rootProject.buildDir}/build/libs

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

5.24.1. DSL

config {
    sourceHtml {
        enabled
        excludedProjects
        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
        }
    }
}
Name Type Required Default Value Description

enabled

boolean

no

true

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

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

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.

5.24.2. Tasks

ConvertCodeToHtml

Converts source code files to Java2HTML documentation.

Name

convertCodeToHtml

Type

com.bmuschko.gradle.java2html.ConvertCodeTask

Properties

Consumes all settings found in the config.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.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

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

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

5.25.1. DSL

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

enabled

boolean

no

true

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

excludedProjects

Set<Project>

[]

Projects in the set are excluded from aggregation

 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

[]

5.25.2. Tasks

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.sourceXref.conversion block.

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/source-xref

Consumes all settings found in the config.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

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

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

5.26.2. DSL

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

5.26.3. Tasks

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.

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

5.27. Testing

id

org.kordamp.gradle.testing

class

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

applies

org.kordamp.gradle.base

Configures test reports.

5.27.1. DSL

config {
    testing {
        enabled
        logging
        aggregate
        integration {
            logging
            aggregate
        }
        functional {
            logging
            aggregate
        }
    }
}
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

functional

Name Type Required Default Value Description

 logging

boolean

no

true

Enables verbose output

 aggregate

boolean

no

true

Enables test report aggregation

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