About the Documentation

The documentation of the FreeFair Gradle Plugin collection 8.10 consists of two parts:

  • This reference guide

  • The Javadoc API

The latest copy of the user guide is available at https://docs.freefair.io/gradle-plugins/current/reference
and the corresponding javadocs can be found at https://docs.freefair.io/gradle-plugins/current/api.

The source code for the plugins and this documentation can be found at https://github.com/freefair/gradle-plugins

1. Installation

All plugins are deployed to the Gradle Plugin Portal.

The plugins are grouped in multiple modules, each containing some plugins. These submodules are described by the different parts of this documentation.

Each plugin can be included using the Plugins DSL or by referencing its containing module in the buildscript-block:

Using the plugins DSL
Groovy
plugins {
    id "io.freefair.lombok" version "8.10"
}
Kotlin
plugins {
    id("io.freefair.lombok") version "8.10"
}
Using legacy plugin application
Groovy
buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "io.freefair.gradle:lombok-plugin:8.10"
  }
}

apply plugin: "io.freefair.lombok"
Kotlin
buildscript {
  repositories {
    maven {
      url = uri("https://plugins.gradle.org/m2/")
    }
  }
  dependencies {
    classpath("io.freefair.gradle:lombok-plugin:8.10")
  }
}

apply(plugin = "io.freefair.lombok")

2. System Requirements

2.1. Gradle

The plugins of version 8.10 are targeted at Gradle 8.10.

Starting with version 8, the Major.Minor version of the plugins matches those of Gradle itself.

2.2. Java

Most of the plugins should work all Java versions supported by Gradle 8.10, but some of the included external tools or libraries like Lombok or AJC might have additional constraints.

Module I: Settings

3. Settings Plugins

This chapter describes all the plugins contained in the settings-plugin module.

3.1. io.freefair.settings.plugin-versions

This plugin allows you to use all other plugins, without defining their version.

Module II: AspectJ

  • a seamless aspect-oriented extension to the Java™ programming language

  • Java platform compatible

  • easy to learn and use

AspectJ™ enables

  • clean modularization of crosscutting concerns, such as error checking and handling, synchronization, context-sensitive behavior, performance optimizations, monitoring and logging, debugging support, and multi-object protocols

— https://www.eclipse.org/aspectj/

4. AspectJ Plugins

This chapter describes all the plugins contained in the aspectj-plugin module.

The plugins support two different approaches when working with AspectJ: Compile-time weaving and post-compile weaving.

These are implemented by the io.freefair.aspectj and io.freefair.aspectj.post-compile-weaving plugins respectively.

4.1. Compile-time weaving

When using compile-time weaving, your sources are directly compiled by ajc. This works well for simple projects which only have .java and .aj sources and don’t need javac-specific features like annotation processing with Project Lombok.

The io.freefair.aspectj plugin is built analogous to the existing plugins for Groovy, Scala and Kotlin. It adds an additional aspectj directory to every source set which will be compiled by ajc. This creates the additional source folders src/main/aspectj, src/test/aspectj and so forth.

In order to avoid conflicts and confusion between ajc and javac, the default compile*Java tasks will be disabled, and src/<sourceSet>/java will be compiled by ajc as well. This aligns with the AspectJ Maven Plugin, which also uses src/<sourceSet>/java.

Technically, each Gradle SourceSet will get two new SourceDirectorySets: aspectj and allAspectj.

aspectj contains src/<sourceSet>/aspectj while allAspectj combines aspectj with the default java SourceDirectorySet.

The compile*Aspectj tasks the use allAspectj as its source, in order to compile both src/<sourceSet>/aspectj and src/<sourceSet>/java

If you need both ajc and javac, just reenable the compile*Java tasks and switch the compile*AspectJ tasks from allAspectj to aspectj.

4.2. Post-compile weaving

The io.freefair.aspectj.post-compile-weaving enhances the compileJava (compileGroovy, compileScala, compileKotlin) tasks of all source sets with an additional ajc action in order to perform post-compile weaving.

With this setup, your source code is first compiled by javac, groovyc, scalac and/or kotlinc as usual. The resulting byte-code is then post-processed by ajc. This enables the usage of AspectJ in combination with annotation processors like Lombok or even other Languages like Groovy, Scala and Kotlin.

4.3. Configuration Options

4.3.1. AspectJ Runtime

Groovy
dependencies {
    implementation "org.aspectj:aspectjrt:1.9.21.1"
}
Kotlin
dependencies {
    implementation("org.aspectj:aspectjrt:1.9.21.1")
}

4.3.2. Aspectpath

Additional advices (the -aspectpath) can be declared as dependencies of the aspect configuration:

Groovy
dependencies {
    aspect project(":my-aspect")
    testAspect "com.example.foo:bar-aspect:1.0.0"
}
Kotlin
dependencies {
    aspect(project(":my-aspect"))
    testAspect("com.example.foo:bar-aspect:1.0.0")
}

4.3.3. Inpath

Additional jars/classes which should be woven and added to the output as well (the -inpath) can be declared as dependencies fo the inpath configuration:

Groovy
dependencies {
    inpath project(":my-lib")
    testInpath "com.example.foo:bar-lib:1.0.0"
}
Kotlin
dependencies {
    inpath(project(":my-lib"))
    testInpath("com.example.foo:bar-lib:1.0.0")
}

4.3.4. io.freefair.aspectj.post-compile-weaving

This plugin enhances the compileJava (compileGroovy, compileScala, compileKotlin) tasks of all source sets with an additional ajc action in order to perform post-compile-weaving.

The output of the compilation (javac, etc.) becomes the -inpath for ajc.

The -classpath, -source and -target arguments of ajc are set automatically to the corresponding values taken from the compile task. Additional ajc arguments can be configured using the ajc.options.compilerArgs property as shown below.

The following things are configurable:

Groovy
compileJava {
    ajc {
        enabled = true (1)
        classpath (2)
        options {
            aspectpath.setFrom configurations.aspect (3)
            compilerArgs = [] (4)
        }
    }
}
compileTestJava {
    ajc {
        enabled = true (1)
        classpath (2)
        options {
            aspectpath.setFrom configurations.testAspect (3)
            compilerArgs = [] (4)
        }
    }
}
Kotlin
tasks.compileJava {
    configure<AjcAction> {
        enabled = true (1)
        classpath (2)
        options {
            aspectpath.setFrom(configurations.aspect) (3)
            compilerArgs = listOf("") (4)
        }
    }
}
tasks.compileTestJava {
    configure<AjcAction> {
        enabled = true (1)
        classpath (2)
        options {
            aspectpath.setFrom(configurations.testAspect) (3)
            compilerArgs = listOf("") (4)
        }
    }
}
1 Specifies if ajc should run at all. Defaults to true
2 The classpath containing ajc itself (aspectjtools.jar). Inferred from the compile/runtime classpaths by default.
3 The classpath containing additional advices to weave. This directly maps to the -aspectpath argument of ajc.
4 Addittional arguments which will be passed to ajc.
The official documentation of ajc can be found here: https://www.eclipse.org/aspectj/doc/released/devguide/ajc-ref.html

5. AspectJ Tasks

5.1. AspectjCompile

This AbstractCompile task can be used to run ajc.

Groovy
task myAjcTask(type: io.freefair.gradle.plugins.aspectj.AspectjCompile) {
    aspectjClasspath.setFrom configurations.aspectj
    ajcOptions {
        inpath = files()
        aspectpath = files()
    }
}
Kotlin
tasks.register<AspectjCompile>("myAjcTask") {
    aspectjClasspath.setFrom(configurations.aspectj)
    ajcOptions {
        inpath = files()
        aspectpath = files()
    }
}

Module III: Commons Compress

The Apache Commons Compress library defines an API for working with ar, cpio, Unix dump, tar, zip, gzip, XZ, Pack200, bzip2, 7z, arj, lzma, snappy, DEFLATE, lz4, Brotli, Zstandard, DEFLATE64 and Z files.
— https://commons.apache.org/proper/commons-compress/

6. Compress Plugins

This chapter describes all the plugins contained in the compress-plugin module.

6.1. io.freefair.compress

This plugin applies all of the plugins listed below for convenience.

6.2. io.freefair.compress.trees

This plugin adds the commonsCompress Extension to the project, which provides the following methods:

FileTree arTree(Object arFile);

FileTree arjTree(Object arjFile);
FileTree arjTree(Object arjFile, String charsetName);

FileTree cpioTree(Object cpioFile);
FileTree cpioTree(Object cpioFile, String encoding);
FileTree cpioTree(Object cpioFile, int blockSize);
FileTree cpioTree(Object cpioFile, int blockSize, String encoding);

FileTree sevenZipTree(Object sevenZipFile);
FileTree sevenZipTree(Object sevenZipFile, char[] password);

FileTree dumpTree(Object dumpFile);
FileTree dumpTree(Object dumpFile, String encoding);

FileTree tarXzTree(Object tarXzFile);
FileTree tarLzmaTree(Object tarLzmaFile);

These methods can be used to open ar, arj, cpio, 7z, dump, tar.xz or tar.lzma archives. They work the same way as the zipTree and tarTree methods which are described here

Example
Groovy
task example(type: Sync) {
    from commonsCompress.arTree(file("foo.ar"))
}
Kotlin
tasks.register<Sync>("example") {
    from(commonsCompress.arTree(file("foo.ar")))
}

6.3. io.freefair.compress.ar

This plugin makes the Ar task available without it’s qualified name.

6.4. io.freefair.compress.cpio

This plugin makes the Cpio task available without it’s qualified name.

6.5. io.freefair.compress.7z

This plugin makes the SevenZip task available without it’s qualified name.

7. Compress Tasks

7.1. Ar

This AbstractArchiveTask implementation can be used to create ar archives.

Groovy
task packageArArchive(type: io.freefair.gradle.plugins.compress.tasks.Ar) {
    archiveFileName = "my-distribution.ar"
    destinationDirectory = file("$buildDir/dist")

    from "$buildDir/toArchive"

    longFileMode = org.apache.commons.compress.archivers.ar.ArArchiveOutputStream.LONGFILE_ERROR
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.Ar>("packageArArchive") {
    archiveFileName = "my-distribution.ar"
    destinationDirectory = file("$buildDir/dist")

    from("$buildDir/toArchive")

    longFileMode = org.apache.commons.compress.archivers.ar.ArArchiveOutputStream.LONGFILE_ERROR
}

7.2. BZip2

This task can be used to compress individual files using BZip2.

Groovy
task compressBZip2(type: io.freefair.gradle.plugins.compress.tasks.BZip2) {
    source "src/main/resources"
    destinationDir = file("$buildDir/compressed")
    fileExtension = "bz2"
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.BZip2>("compressBZip2") {
    source("src/main/resources")
    destinationDir = file("$buildDir/compressed")
    fileExtension = "bz2"
}

7.3. Cpio

This AbstractArchiveTask implementation can be used to create cpio archives.

Groovy
task packageCpioArchive(type: io.freefair.gradle.plugins.compress.tasks.Cpio) {
    archiveFileName = "my-distribution.cpio"
    destinationDirectory = file("$buildDir/dist")

    from "$buildDir/toArchive"

    format = org.apache.commons.compress.archivers.cpio.CpioConstants.FORMAT_NEW
    blockSize = 512
    encoding = "US-ASCII"
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.Cpio>("packageCpioArchive") {
    archiveFileName = "my-distribution.cpio"
    destinationDirectory = file("$buildDir/dist")

    from("$buildDir/toArchive")

    format = org.apache.commons.compress.archivers.cpio.CpioConstants.FORMAT_NEW
    blockSize = 512
    encoding = "US-ASCII"
}

7.4. Deflate

This task can be used to compress individual files using the zlib deflate algorithm.

Groovy
task compressDeflate(type: io.freefair.gradle.plugins.compress.tasks.Deflate) {
    source "src/main/resources"
    destinationDir = file("$buildDir/compressed")
    fileExtension = "deflate"

    compressionLevel = 9
    withZlibHeader = false
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.Deflate>("compressDeflate") {
    source("src/main/resources")
    destinationDir = file("$buildDir/compressed")
    fileExtension = "deflate"

    compressionLevel = 9
    withZlibHeader = false
}

7.5. GZip

This task can be used to compress individual files using BZip2.

Groovy
task compressGZip(type: io.freefair.gradle.plugins.compress.tasks.GZip) {
    source "src/main/resources"
    destinationDir = file("$buildDir/compressed")
    fileExtension = "gz"

    compressionLevel = 9
    comment = ""
    addFilename = false
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.GZip>("compressGZip") {
    source("src/main/resources")
    destinationDir = file("$buildDir/compressed")
    fileExtension = "gz"

    compressionLevel = 9
    comment = ""
    addFilename = false
}

7.6. LZMA

This task can be used to compress individual files using LZMA.

Groovy
task compressLZMA(type: io.freefair.gradle.plugins.compress.tasks.LZMA) {
    source "src/main/resources"
    destinationDir = file("$buildDir/compressed")
    fileExtension = "lzma"
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.LZMA>("compressLZMA") {
    source("src/main/resources")
    destinationDir = file("$buildDir/compressed")
    fileExtension = "lzma"
}

7.7. SevenZip

This AbstractArchiveTask implementation can be used to create 7z archives.

Groovy
task packageSevenZipArchive(type: io.freefair.gradle.plugins.compress.tasks.SevenZip) {
    archiveFileName = "my-distribution.7z"
    destinationDirectory = file("$buildDir/dist")

    from "$buildDir/toArchive"

    contentCompression = org.apache.commons.compress.archivers.sevenz.SevenZMethod.LZMA2
}
Kotlin
tasks.register<io.freefair.gradle.plugins.compress.tasks.SevenZip>("packageSevenZipArchive") {
    archiveFileName = "my-distribution.7z"
    destinationDirectory = file("$buildDir/dist")

    from("$buildDir/toArchive")

    contentCompression = org.apache.commons.compress.archivers.sevenz.SevenZMethod.LZMA2
}

Module IV: Embedded Sass

8. JSass Plugins

This chapter describes all the plugins contained in the embedded-sass-plugin module.

8.1. io.freefair.sass-base

This plugin adds the sass extension to the project and applies it to all SassCompile tasks.

Groovy
sass {
    omitSourceMapUrl = false
    outputStyle = com.sass_lang.embedded_protocol.OutputStyle.EXPANDED
    sourceMapContents = false
    sourceMapEmbed = false
    sourceMapEnabled = true
}
Kotlin
sass {
    omitSourceMapUrl = false
    outputStyle = com.sass_lang.embedded_protocol.OutputStyle.EXPANDED
    sourceMapContents = false
    sourceMapEmbed = false
    sourceMapEnabled = true
}

8.2. io.freefair.sass-webjars

This plugin adds webjars support to the sass compilation:

Groovy
dependencies {
    implementation 'org.webjars:bootstrap:5.1.3'
}
Kotlin
dependencies {
    implementation("org.webjars:bootstrap:5.1.3")
}
@import "scss/bootstrap";

8.3. io.freefair.sass-java

This plugin configures a compileSass task for the resources of each source set.

8.4. io.freefair.sass-war

This plugin creates a compileWebappSass for the src/main/webapp folder of your war project.

9. Sass Tasks

Module V: Git

10. Git Plugins

This chapter describes all the plugins contained in the git-plugin module.

10.1. io.freefair.git-version

This plugin sets the project version according to the current git tag or branch.

It should only be applied to the root project.

11. Git Tasks

This module does not contain any tasks.

Module VI: GitHub

12. GitHub Plugins

This chapter describes all the plugins contained in the github-plugin module.

12.1. io.freefair.github.base

Common base plugin which is applied by the other plugins in this module. It adds the github extension to the project:

Configuration options of the github extension
Groovy
github {
    slug = "freefair" (1)
    username = findProperty('githubUsername') (2)
    token = findProperty('githubToken') (3)
    tag = 'HEAD' (4)
    travis = true (5)
}
Kotlin
github {
    slug = "freefair" (1)
    username = findProperty("githubUsername") (2)
    token = findProperty("githubToken") (3)
    tag = "HEAD" (4)
    travis = true (5)
}
1 The owner/name identifier of the GitHub repository. This is auto-detected using the configured git remotes.
2 The username which should be used when accessing the GitHub API.
3 The token which should be used when accessing the GitHub API.
4 See io.freefair.github.pom
5 Whether the GitHub project uses TravisCI (true) or not (false). This is auto-detected by default.
This plugin should only be applied to the root project.

12.2. io.freefair.github.pom

This plugin pre-fills the pom’s of all `MavenPublication`s with information avaiable from the GitHub project.

The scm.tag element of the pom is auto-detected by default, but can be overriden using the github.tag extension property.

This plugins calls the GitHub API. Configure a username and token as described in io.freefair.github.base if you have problems with GitHub’s rate limit. (The token does not need any scopes for this).

12.3. io.freefair.github.package-registry-maven-publish

This plugin pre-configures publishing to the GitHub Package Registry using the maven-publish plugin.

It also applies the io.freefair.github.pom plugin.

When using this plugin, you have to configure a username and token as described in io.freefair.github.base. The token needs the read:packages and write:packages scopes as described here.

13. GitHub Tasks

This module does not contain tasks.

Module VII: JaCoCo

JaCoCo is a free code coverage library for Java, which has been created by the EclEmma team based on the lessons learned from using and integration existing libraries for many years.
— https://www.eclemma.org/jacoco/

14. JaCoCo Plugins

This chapter describes all the plugins contained in the jacoco-plugin module.

14.1. io.freefair.aggregate-jacoco-report

This plugin adds a aggregateJacocoReport task to the project its applied on. This Task will generate an aggregated Jacoco report for the main java source sets of all projects by evaluating the execution data of the test tasks of all projects.

The task is of type JacocoReport

15. JaCoCo Tasks

15.1. JacocoDump

The io.freefair.gradle.plugins.jacoco.tasks.JacocoDump task is the Gradle equivalent of the dump Ant-Task

JacocoDump Example
Groovy
task dump(type: io.freefair.gradle.plugins.jacoco.tasks.JacocoDump) {
    address = "localhost"
    port = 6300
    retryCount = 10
    dump = true
    reset = false
    destfile = file("build/dump.exec")
    append = true
}
Kotlin
tasks.register<io.freefair.gradle.plugins.jacoco.tasks.JacocoDump>("dump") {
    address = "localhost"
    port = 6300
    retryCount = 10
    dump = true
    reset = false
    destfile = file("build/dump.exec")
    append = true
}

Module VIII: Lombok

Project Lombok is a java library that automatically plugs into your editor and build tools, spicing up your java. Never write another getter or equals method again, with one annotation your class has a fully featured builder, Automate your logging variables, and much more.
— https://projectlombok.org

16. Lombok Plugins

This chapter describes all the plugins contained in the lombok-plugin module.

16.1. io.freefair.lombok-base

This plugin adds the lombok configuration and the lombok extension to the project. It also configures all Lombok related tasks to use the lombok configuration.

The used Lombok version can be customized using the lombok extension:

Setting a custom Lombok version
Groovy
lombok {
    version = "1.18.32"
}
Kotlin
lombok {
    version = "1.18.32"
}

16.2. io.freefair.lombok

This plugin simplifies the use of Lombok in Gradle by performing the following steps:

  • Lombok is added to the annotationProcessor and compileOnly configurations of each source set

  • For each source set a delombok task is created.

  • The javadoc task will be configured to read the delombok-ed sources instead of the actual sources.

  • lombok-mapstruct-binding is added to each source-set when 'org.mapstruct:mapstruct-processor' is found.

  • The compile tasks for each source set will consider the lombok.config(s) in their up-to-date checks

Only the default javadoc Javadoc task will be modified to work on the delombok-ed sources. If you create your own custom Javadoc tasks, it’s up to you to assign the correct source. The delombok task created by this plugin can be used as source for the javadoc task:

Groovy
task myJavadocs(type: Javadoc) {
  source = delombok
}
Kotlin
tasks.register<Javadoc>("myJavadocs") {
  source = tasks.named<Delombok>("delombok")
}

In contrast to the javadoc task, the sourcesJar task is not adjusted to use the delomboked sources. This is done on purpose, so the line numbers in the -sources.jar match the LineNumberTable in the generated class files.

17. Lombok Tasks

Module IX: Maven

18. Maven Plugins

This chapter describes all the plugins contained in the maven-plugin module.

18.1. io.freefair.war

This plugin is a shortcut which applies the following plugins:

18.2. io.freefair.war-overlay

This plugin ports the overlays feature of the Maven War Plugin to Gradle.

The overlays can be configured using the overlays property, which is added to every War task.

Groovy
war {
    overlays {
        foo {
            from "com.example:some-war:1.2.3@war" (1)
            enabled = true (2)
            into "sub-path/foo" (3)
            enableCompilation = true (4)
            provided = false (5)
        }
        bar {
            from project(":some-other-war") (1)
            skip = false (2)
            targetPath = "sub-path/bar" (3)
            include "*.html"
            includes = ["*.html", "**/*.xml"]
        }
    }
}
Kotlin
tasks.withType<org.gradle.api.tasks.bundling.War> {
    val extension: NamedDomainObjectContainer<WarOverlay> = extensions["overlays"] as NamedDomainObjectContainer<WarOverlay>
    extension.create("foo") {
        from("com.example:some-war:1.2.3@war") (1)
        enabled = true (2)
        into("sub-path/foo") (3)
        enableCompilation = true (4)
        provided(false) (5)
    }
    extension.create("bar") {
        from(project(":some-other-war")) (1)
        skip = false (2)
        targetPath = "sub-path/bar" (3)
        include("*.html")
        includes = ["*.html", "**/*.xml"]
    }
}
1 The source of the overlay. This can be another project, a File instance or a dependency notation.
2 Whether the overlay is enabled or should be skipped.
3 The target relative path in the webapp structure. By default, the content of the overlay is added in the root structure of the webapp.
4 Whether the classes and jars in the overlay should be added to the compile classpath of the project.
5 Whether the contents of the overlay should not be added to the war. Setting this to true can be used to compile against the classes in the war and have IDE auto-completion without actually adding the files of the overlay to the war.

The overlays property of the war task is a NamedDomainObjectContainer of WarOverlay instances.

18.3. io.freefair.war-attach-classes

This plugin ports the attachClasses feature of the Maven War Plugin to Gradle.

Groovy
war {
    attachClasses.set(true) (1)
    classesClassifier.set('classes') (2)
}
Kotlin
war {
    val attachClasses = extensions["attachClasses"] as Property<Boolean>
    val classesClassifier = extensions["classesClassifier"] as Property<String>
    attachClasses.set(true) (1)
    classesClassifier.set("classes") (2)
}
1 Whether classes (that is the content of the WEB-INF/classes directory) should be attached to the project as an additional artifact.
2 The classifier to use for the attached classes artifact.

18.4. io.freefair.war-archive-classes

This plugin ports the archiveClasses feature of the Maven War Plugin to Gradle.

Groovy
war {
    archiveClasses.set(true) (1)
}
Kotlin
war {
    val archiveClasses = extensions["archiveClasses"] as Property<Boolean>
    archiveClasses.set(true) (1)
}
1 Whether a JAR file will be created for the classes in the webapp. Using this optional configuration parameter will make the compiled classes to be archived into a JAR file and the classes directory will then be excluded from the webapp.

18.5. io.freefair.aggregate-javadoc

This plugin can be used to generate the aggregated javadocs of multiple projects. It is inspired by the aggregate mojo of the javadoc-maven-plugin.

This plugin is designed to be used in multi-module Gradle builds. It can either be applied directly to the root project or to a separate subproject.

The projects which sources should be included into the aggregated javadocs have to be added as dependencies to the javadoc configuration:

Groovy
dependencies {
    // Option 1: List projects explicitly
    javadoc project(":moduleA")
    javadoc project(":moduleB")

    //Option 2: Add all java projects automatically
    rootProject.subprojects { subproject ->
        subproject.plugins.withId("java") {
            javadoc subproject
        }
    }
}
Kotlin
dependencies {
    // Option 1: List projects explicitly
    javadoc(project(":moduleA"))
    javadoc(project(":moduleB"))

    //Option 2: Add all java projects automatically
    rootProject.subprojects.forEach { subproject ->
        subproject.plugins.withId("java") {
            javadoc(subproject)
        }
    }
}

18.6. io.freefair.aggregate-javadoc-legacy

This is the old io.freefair.aggregate-javadoc plugin which was deprecated and replaced with version 8.0.

This plugin adds a aggregateJavadoc task to the project which will generate the aggregated javadoc for the project itself and all of its subprojects (which have the java plugin applied).

18.7. io.freefair.aggregate-javadoc-jar

This plugin adds an aggregateJavadocJar task based on the io.freefair.aggregate-javadoc-legacy Plugin.

Consider using the new io.freefair.aggregate-javadoc Plugin which was rewritten for Version 8.0 which now also directly includes a jar task.

18.8. io.freefair.javadocs

This plugin is a shortcut which applies the following plugins:

This plugin configures the links of each Javadoc task based on the dependencies in the classpath of the task.

18.10. io.freefair.javadoc-utf-8

This plugin configures all Javadoc tasks to use UTF-8.

18.11. io.freefair.maven-publish-java

This plugin applies the maven-publish and java plugins and configures a mavenJava publication.

18.12. io.freefair.maven-publish-war

This plugin applies the maven-publish and war plugins and configures a mavenWeb publication.

18.13. io.freefair.maven-optional

This plugin adds a Maven-like optional configuration to the project.

Groovy
dependencies {
    optional "com.example:foo-bar:1.0.0"
}
Kotlin
dependencies {
    optional("com.example:foo-bar:1.0.0")
}

18.14. io.freefair.maven-central.validate-poms

This plugin adds a ValidateMavenPom task for each GenerateMavenPom task.

19. Maven Tasks

19.1. ValidateMavenPom

This task validates, that a given pom file contains all the information required by maven central.

Groovy
task validateMyPom(type: io.freefair.gradle.plugins.maven.central.ValidateMavenPom) {
    pomFile = file("path/to/my/pom.xml")
    ignoreFailures = false
}
Kotlin
tasks.register<io.freefair.gradle.plugins.maven.central.ValidateMavenPom>("validateMyPom") {
    pomFile = file("path/to/my/pom.xml")
    ignoreFailures = false
}

Module X: Maven-Plugin

20. Maven-Plugin Plugins

This chapter describes all the plugins contained in the maven-plugin-plugin module.

20.1. io.freefair.maven-plugin

This plugin can be used to build maven plugins. It’s based on the java and maven-publish plugins.

21. Maven-Plugin Tasks

21.1. DescriptorGeneratorTask

This Task is the gradle equivalent of the DescriptorGeneratorMojo of the Maven Plugin Maven Plugin.

Module XI: MkDocs

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
— https://www.mkdocs.org/

22. MkDocs Plugins

22.1. io.freefair.mkdocs

23. MkDocs Tasks

All MkDocs tasks can be found in the io.freefair.gradle.plugins.mkdocs.tasks package

23.1. MkDocsBuild

This tasks executes mkdocs build.

23.2. MkDocsGhDeploy

This task executes mkdocs gh-deploy

23.3. MkDocsNew

This task executes mkdocs new

23.4. MkDocsServe

This tasks executes mkdocs serve

Module XII: MJML

24. MJML Plugin

This chapter describes all the plugins contained in the mjml-plugin module.

24.1. io.freefair.mjml.base

This plugin adds the mjml extension to the project and create some basic tasks to install mjml via npm.

Groovy
mjml {
    validationMode = ValidationMode.strict
    minify = true
    beautify = false
    minifyOptions = "{\"minifyCSS\": true, \"removeEmptyAttributes\": false}"
    juiceOptions = "{\"preserveImportant\": true}"
    juicePreserveTags = "{\"myTag\": { \"start\": \"<#\", \"end\": \"</#\" }}"
}
Kotlin
mjml {
    validationMode = ValidationMode.strict
    minify = true
    beautify = false
    minifyOptions = "{\"minifyCSS\": true, \"removeEmptyAttributes\": false}"
    juiceOptions = "{\"preserveImportant\": true}"
    juicePreserveTags = "{\"myTag\": { \"start\": \"<#\", \"end\": \"</#\" }}"
}

24.2. io.freefair.mjml.java

This plugin adds the mjml compile task output to java’s resources.

25. MJML Task

Compiles your mjml files to html with the given configuration (see extension documentation).

Module XIII: OkHttp

An HTTP & HTTP/2 client for Android and Java applications
— https://square.github.io/okhttp/

26. OkHttp Plugins

27. Apply plugin

Groovy
plugins {
    id "io.freefair.okhttp"
}
Kotlin
plugins {
    id("io.freefair.okhttp")
}

27.1. io.freefair.okhttp

This plugin provides an OkHttpClient instance which can be used by other tasks and plugins.

Groovy
okHttp {
    loggingLevel = okhttp3.logging.HttpLoggingInterceptor.Level.BASIC
}
Kotlin
okHttp {
    loggingLevel = okhttp3.logging.HttpLoggingInterceptor.Level.BASIC
}

28. OkHttp Tasks

28.1. OkHttpRequestTask

This is the base class for all tasks executing an http request which provides the following common properties:

url

The URL for the Request

username

The username for HTTP Basic Auth

password

The password for HTTP Basic Auth

headers

Additional headers which will be added to the request.

28.2. DownloadFile

Groovy
tasks.register("myDownload", io.freefair.gradle.plugins.okhttp.tasks.DownloadFile) {
    url = "https://example.com/foo.txt"
    outputFile = file("build/foo.txt")
}
Kotlin
tasks.register<io.freefair.gradle.plugins.okhttp.tasks.DownloadFile>("myDownload") {
    url = "https://example.com/foo.txt"
    outputFile = file("build/foo.txt")
}

28.3. UploadFile

Groovy
tasks.register("myUpload", io.freefair.gradle.plugins.okhttp.tasks.UploadFile) {
    url = "https://example.com/foo.txt"
    file = file("build/file.txt")
    contentType = "text/plain"
}
Kotlin
tasks.register<io.freefair.gradle.plugins.okhttp.tasks.UploadFile>("myUpload") {
    url = "https://example.com/foo.txt"
    file = file("build/file.txt")
    contentType = "text/plain"
}

Module XIV: PlantUML

This plugin generates images from plantuml files.

29. Basic usage

Groovy
plugins {
    id "io.freefair.plantuml"
}
Kotlin
plugins {
    id("io.freefair.plantuml")
}

This adds a PlantUML task to gradle as well as a new source set. The images will be saved to the build directory.

30. Configuration options

Option Description Default

includePattern

Pattern for filenames to include in the image generation process. This is different to source so that changes in included files will trigger a recompile as well

*/.puml

fileFormat

File format to generate. All valid options for PlantUML can be chosen.

PNG

outputDirectory

Directory to save generated files in.

build/plantuml

30.1. Configure

Groovy
plantUml {
    fileFormat = "PNG"
    outputDirectory = layout.buildDirectory.dir("dist")
}
Kotlin
tasks.plantUml {
    fileFormat = "PNG"
    outputDirectory = layout.buildDirectory.dir("dist")
}

31. Custom Task

Groovy
tasks.register("plantUml2", PlantumlTask) {
    source("src/plantuml2")
    includePattern = "**/*.tuml"
    fileFormat = "SVG"
    outputDirectory = layout.buildDirectory.dir("dist2")
}
Kotlin
tasks.register<PlantumlTask>("plantUml2") {
    source("src/plantuml2")
    includePattern = "**/*.tuml"
    fileFormat = "SVG"
    outputDirectory = layout.buildDirectory.dir("dist2")
}