About the Documentation

The documentation of the FreeFair Gradle Plugin collection main-SNAPSHOT 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 "main-SNAPSHOT"
}

Kotlin

plugins {
    id("io.freefair.lombok") version "main-SNAPSHOT"
}

Using legacy plugin application

Groovy

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "io.freefair.gradle:lombok-plugin:main-SNAPSHOT"
  }
}

apply plugin: "io.freefair.lombok"

Kotlin

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

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

2. System Requirements

2.1. Gradle

The plugins of version main-SNAPSHOT are targeted at Gradle 8.12.

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.12, 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

AspectJ™ is

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

Kotlin

lombok {
    version = "1.18.36"
}

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

The following task are provided:

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:

war
io.freefair.war-overlay
io.freefair.war-attach-classes
io.freefair.war-archive-classes

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:

io.freefair.javadoc-links
io.freefair.javadoc-utf-8

18.9. `io.freefair.javadoc-links`

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

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`

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

FreeFair Gradle Plugin Collection

About the Documentation

1. Installation

2. System Requirements

2.1. Gradle

2.2. Java

Module I: Settings

3. Settings Plugins

3.1. io.freefair.settings.plugin-versions

Module II: AspectJ

4. AspectJ Plugins

4.1. Compile-time weaving

4.2. Post-compile weaving

4.3. Configuration Options

4.3.1. AspectJ Runtime

4.3.2. Aspectpath

4.3.3. Inpath

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

5. AspectJ Tasks

5.1. AspectjCompile

Module III: Commons Compress

6. Compress Plugins

6.1. io.freefair.compress

6.2. io.freefair.compress.trees

6.3. io.freefair.compress.ar

6.4. io.freefair.compress.cpio

6.5. io.freefair.compress.7z

7. Compress Tasks

7.1. Ar

7.2. BZip2

7.3. Cpio

7.4. Deflate

7.5. GZip

7.6. LZMA

7.7. SevenZip

Module IV: Embedded Sass

8. JSass Plugins

8.1. io.freefair.sass-base

8.2. io.freefair.sass-webjars

8.3. io.freefair.sass-java

8.4. io.freefair.sass-war

9. Sass Tasks

Module V: Git

10. Git Plugins

10.1. io.freefair.git-version

11. Git Tasks

Module VI: GitHub

12. GitHub Plugins

12.1. io.freefair.github.base

12.2. io.freefair.github.pom

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

13. GitHub Tasks

Module VII: JaCoCo

14. JaCoCo Plugins

14.1. io.freefair.aggregate-jacoco-report

15. JaCoCo Tasks

15.1. JacocoDump

Module VIII: Lombok

16. Lombok Plugins

16.1. io.freefair.lombok-base

16.2. io.freefair.lombok

17. Lombok Tasks

Module IX: Maven

18. Maven Plugins

18.1. io.freefair.war

18.2. io.freefair.war-overlay

18.3. io.freefair.war-attach-classes

18.4. io.freefair.war-archive-classes

18.5. io.freefair.aggregate-javadoc

18.6. io.freefair.aggregate-javadoc-legacy

18.7. io.freefair.aggregate-javadoc-jar

18.8. io.freefair.javadocs

18.9. io.freefair.javadoc-links

18.10. io.freefair.javadoc-utf-8

18.11. io.freefair.maven-publish-java

18.12. io.freefair.maven-publish-war

18.13. io.freefair.maven-optional

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

19. Maven Tasks

19.1. ValidateMavenPom

3.1. `io.freefair.settings.plugin-versions`

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

5.1. `AspectjCompile`

6.1. `io.freefair.compress`

6.2. `io.freefair.compress.trees`

6.3. `io.freefair.compress.ar`

6.4. `io.freefair.compress.cpio`

6.5. `io.freefair.compress.7z`

7.1. `Ar`

7.2. `BZip2`

7.3. `Cpio`

7.4. `Deflate`

7.5. `GZip`

7.6. `LZMA`

7.7. `SevenZip`

8.1. `io.freefair.sass-base`

8.2. `io.freefair.sass-webjars`

8.3. `io.freefair.sass-java`

8.4. `io.freefair.sass-war`

10.1. `io.freefair.git-version`

12.1. `io.freefair.github.base`

12.2. `io.freefair.github.pom`

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

14.1. `io.freefair.aggregate-jacoco-report`

15.1. `JacocoDump`

16.1. `io.freefair.lombok-base`

16.2. `io.freefair.lombok`

18.1. `io.freefair.war`

18.2. `io.freefair.war-overlay`

18.3. `io.freefair.war-attach-classes`

18.4. `io.freefair.war-archive-classes`

18.5. `io.freefair.aggregate-javadoc`

18.6. `io.freefair.aggregate-javadoc-legacy`

18.7. `io.freefair.aggregate-javadoc-jar`

18.8. `io.freefair.javadocs`

18.9. `io.freefair.javadoc-links`

18.10. `io.freefair.javadoc-utf-8`

18.11. `io.freefair.maven-publish-java`

18.12. `io.freefair.maven-publish-war`

18.13. `io.freefair.maven-optional`

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

19.1. `ValidateMavenPom`

20.1. `io.freefair.maven-plugin`

21.1. `DescriptorGeneratorTask`

22.1. `io.freefair.mkdocs`

23.1. `MkDocsBuild`

23.2. `MkDocsGhDeploy`

23.3. `MkDocsNew`

23.4. `MkDocsServe`

24.1. `io.freefair.mjml.base`

24.2. `io.freefair.mjml.java`

27.1. `io.freefair.okhttp`

28.1. `OkHttpRequestTask`

28.2. `DownloadFile`

28.3. `UploadFile`