Introduction

1. About the Documentation

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

  • This reference guide

  • The Javadoc API

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

2. System Requirements

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

AspectJ Plugins

3. io.freefair.aspectj.base

This plugin adds the aspectj extension and the aspectj configuration to the project.

Setting the AspectJ version using the aspectj extension.
aspectj {
    version = "1.9.4"
}

The aspectj configuration contains the aspectjtools.jar with the specified version.

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

This plugin enhances the compileJava (compileGroovy, compileScala) 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. 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"
}

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

The following things are configurable:

compileJava {
    ajc {
        enabled = true (1)
        classpath = configurations.aspectj (2)
        aspectpath = configurations.aspect (3)
        compilerArgs = [] = (4)
    }
}
compileTestJava {
    ajc {
        enabled = true (1)
        classpath = configurations.aspectj (2)
        aspectpath = configurations.testAspect (3)
        compilerArgs = [] (4)
    }
}
1 Specifies if ajc should run at all. Defaults to true
2 The classpath containing ajc itself (aspectjtools.jar). Defaults to configurations.aspectj
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

Commons Compress Plugins

5. io.freefair.compress

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

6. io.freefair.compress.trees

This plugin adds the following methods to the project:

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

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

7. io.freefair.compress.ar

This plugin makes the io.freefair.gradle.plugins.compress.tasks.Ar task available without it’s qualified name.

task packageArArchive(type: Ar) {
    archiveFileName = "my-distribution.ar"
    destinationDirectory = file("$buildDir/dist")

    from "$buildDir/toArchive"

    longFileMode = org.apache.commons.compress.archivers.ar.ArArchiveOutputStream.LONGFILE_ERROR
}
This task extends from AbstractArchiveTask, so you can use all of it’s features.

8. io.freefair.compress.cpio

This plugin makes the io.freefair.gradle.plugins.compress.tasks.Cpio task available without it’s qualified name.

task packageCpioArchive(type: 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"
}
This task extends from AbstractArchiveTask, so you can use all of it’s features.

9. io.freefair.compress.7z

This plugin makes the io.freefair.gradle.plugins.compress.tasks.SevenZip task available without it’s qualified name.

task packageSevenZipArchive(type: SevenZip) {
    archiveFileName = "my-distribution.7z"
    destinationDirectory = file("$buildDir/dist")

    from "$buildDir/toArchive"

    contentCompression = org.apache.commons.compress.archivers.sevenz.SevenZMethod.LZMA2
}
This task extends from AbstractArchiveTask, so you can use all of it’s features.

GitHub Plugins

10. todo

Jacoco Plugins

11. todo

JSass Plugins

12. io.freefair.jsass-base

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

jsass {
    indent = "  "
    linefeed = System.lineSeparator()
    omitSourceMapUrl = false
    outputStyle = io.bit3.jsass.OutputStyle
    precision = 8
    sourceComments = false
    sourceMapContents = false
    sourceMapEmbed = false
    sourceMapEnabled = true
}

All the properties correspond to the jsass options.

13. io.freefair.jsass-webjars

This plugin adds webjars support to the sass compilation:

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

14. io.freefair.jsass-java

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

15. io.freefair.jsass-war

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

Lombok Plugins

16. 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.8"
}

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

  • A generateLombokConfig will be added to the project, which generates the lombok.config file based on the lombok extension.

17.1. lombok.config handling

Disable lombok.config generation
generateLombokConfig.enabled = false
Modifying the generated lombok.config file
lombok {
    config['lombok.log.fieldName'] = 'LOG'
}

18. Task overview

The following task are provided:

Maven Plugins

19. todo

Maven-Plugin Plugin

20. todo