Introduction

1. About the Documentation

The documentation of the FreeFair Gradle Plugin collection 8.0.1 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

2. 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
plugins {
    id "io.freefair.lombok" version "8.0.1"
}
Using legacy plugin application
buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "io.freefair.gradle:lombok-plugin:8.0.1"
  }
}

apply plugin: "io.freefair.lombok"

3. System Requirements

Unless otherwise noted, all plugins require at least Java 8 and are targeted at Gradle 8.0.2.

Settings

4. Settings Plugins

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

4.1. io.freefair.settings.plugin-versions

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

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/

5. AspectJ Plugins

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

5.1. io.freefair.aspectj.base

The other two plugins implicitly apply this one. In most cases it’s therefore unnecessary to explicitly apply it to your project.

This plugin enables the automatic configuration of the aspectjClasspath.

The automatic configuration follows the same principles as described here: https://docs.gradle.org/8.0.2/userguide/groovy_plugin.html#sec:automatic_configuration_of_groovyclasspath

5.2. io.freefair.aspectj

This plugin adds AspectJ support to the project, by adding a aspectj directory to every source set.

Source contained in the src/main/aspectj directory will be compiled with ajc by the compileAspectj task.

dependencies {
    implementation "org.aspectj:aspectjrt:1.9.8.RC3"
}
This is follows the same principles as the groovy and scala plugins.

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

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

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:

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

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

dependencies {
    implementation "org.aspectj:aspectjrt:1.9.8.RC3"
}

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

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

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:

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

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:

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

6. AspectJ Tasks

6.1. AspectjCompile

This AbstractCompile task can be used to run ajc.

task myAjcTask(type: io.freefair.gradle.plugins.aspectj.AspectjCompile) {
    aspectjClasspath.setFrom configurations.aspectj
    ajcOptions {
        inpath = files()
        aspectpath = files()
    }
}

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/

7. Compress Plugins

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

7.1. io.freefair.compress

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

7.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
task example(type: Sync) {
    from commonsCompress.arTree(file("foo.ar"))
}

7.3. io.freefair.compress.ar

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

7.4. io.freefair.compress.cpio

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

7.5. io.freefair.compress.7z

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

8. Compress Tasks

8.1. Ar

This AbstractArchiveTask implementation can be used to create ar archives.

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
}

8.2. BZip2

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

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

8.3. Cpio

This AbstractArchiveTask implementation can be used to create cpio archives.

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

8.4. Deflate

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

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

    compressionLevel = 9
    withZlibHeader = false
}

8.5. GZip

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

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
}

8.6. LZMA

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

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

8.7. SevenZip

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

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
}

Embedded Sass

9. JSass Plugins

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

9.1. io.freefair.sass-base

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

sass {
    omitSourceMapUrl = false
    outputStyle = sass.embedded_protocol.EmbeddedSass.OutputStyle.EXPANDED
    sourceMapContents = false
    sourceMapEmbed = false
    sourceMapEnabled = true
}

9.2. io.freefair.sass-webjars

This plugin adds webjars support to the sass compilation:

dependencies {
    compile 'org.webjars:bootstrap:5.1.3'
}
@import "scss/bootstrap";

9.3. io.freefair.sass-java

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

9.4. io.freefair.sass-war

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

10. Sass Tasks

Git

11. Git Plugins

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

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

12. Git Tasks

This module does not contain any tasks.

GitHub

13. GitHub Plugins

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

13.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
github {
    slug (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.

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

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

14. GitHub Tasks

This module does not contain tasks.

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/

15. JaCoCo Plugins

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

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

16. JaCoCo Tasks

16.1. JacocoDump

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

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

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

17. Lombok Plugins

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

17.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
lombok {
    version = "1.18.26"
}

17.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:

task myJavadocs(type: Javadoc) {
  source = 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.

18. Lombok Tasks

The following task are provided:

Maven

19. Maven Plugins

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

19.1. io.freefair.war

This plugin is a shortcut which applies the following plugins:

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

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

19.3. io.freefair.war-attach-classes

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

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

19.4. io.freefair.war-archive-classes

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

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

19.5. io.freefair.maven-jars

This plugin is a shortcut for applying the following plugins:

19.6. io.freefair.sources-jar

This plugin adds a sourcesJar task to the project, which produces a jar file containing all sources of the main source set.

19.7. io.freefair.javadoc-jar

This plugin adds a javadocJar task to the project, which produces a jar file containing the output of the javadoc task.

It will also add a aggregateJavadocJar task, if the io.freefair.aggregate-javadoc plugin is also applied.

19.8. 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:

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

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

19.10. io.freefair.aggregate-javadoc-jar

This plugin is a shortcut which applies the following plugins:

19.11. io.freefair.javadocs

This plugin is a shortcut which applies the following plugins:

19.12. io.freefair.javadoc-links

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

19.13. io.freefair.javadoc-utf-8

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

19.14. io.freefair.maven-publish-java

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

It also works together with the io.freefair.sources-jar, io.freefair.javadoc-jar and io.freefair.maven-jars plugins.

19.15. io.freefair.maven-publish-war

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

It also works together with the io.freefair.sources-jar, io.freefair.javadoc-jar and io.freefair.maven-jars plugins.

19.16. io.freefair.maven-optional

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

dependencies {
    optional "com.example:foo-bar:1.0.0"
}

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

This plugin adds a ValidateMavenPom task for each GenerateMavenPom task.

20. Maven Tasks

20.1. ValidateMavenPom

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

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

Maven-Plugin

21. Maven-Plugin Plugins

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

21.1. io.freefair.maven-plugin

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

22. Maven-Plugin Tasks

22.1. DescriptorGeneratorTask

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

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/

23. MkDocs Plugins

23.1. io.freefair.mkdocs

24. MkDocs Tasks

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

24.1. MkDocsBuild

This tasks executes mkdocs build.

24.2. MkDocsGhDeploy

This task executes mkdocs gh-deploy

24.3. MkDocsNew

This task executes mkdocs new

24.4. MkDocsServe

This tasks executes mkdocs serve

OkHttp

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

25. OkHttp Plugins

25.1. io.freefair.okhttp

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

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

26. OkHttp Tasks

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

26.2. DownloadFile

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

26.3. UploadFile

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

PlantUML

This plugin generates images from plantuml files.

27. Basic usage

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.

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

29. Custom Task

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