Introduction
1. About the Documentation
The documentation of the FreeFair Gradle Plugin collection 6.4.3.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:
plugins {
id "io.freefair.lombok" version "6.4.3.1"
}
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "io.freefair.gradle:lombok-plugin:6.4.3.1"
}
}
apply plugin: "io.freefair.lombok"
3. System Requirements
Unless otherwise noted, all plugins require at least Java 8 and are targeted at Gradle 7.4.2.
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
4. AspectJ Plugins
This chapter describes all the plugins contained in the aspectj-plugin
module.
4.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/7.4.2/userguide/groovy_plugin.html#sec:automatic_configuration_of_groovyclasspath
4.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"
}
4.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
|
5. AspectJ Tasks
5.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.
6. Compress Plugins
This chapter describes all the plugins contained in the compress-plugin
module.
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
task example(type: Sync) {
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.
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
}
7.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"
}
7.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"
}
7.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
}
7.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
}
7.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"
}
7.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
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.
sass {
omitSourceMapUrl = false
outputStyle = sass.embedded_protocol.EmbeddedSass.OutputStyle.EXPANDED
sourceMapContents = false
sourceMapEmbed = false
sourceMapEnabled = true
}
8.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";
8.3. io.freefair.sass-java
This plugin configures a compileSass
task for the
resources
of each
source set.
Git
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:
github
extensiongithub {
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. |
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.
|
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.
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
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
}
JSass
The JSass plugin is deprecated and should not be used anymore. Use the Embedded Sass plugin instead. |
16. JSass Plugins
This chapter describes all the plugins contained in the jsass-plugin
module.
16.1. 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.
16.2. 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";
16.3. io.freefair.jsass-java
This plugin configures a compileSass
task for the
resources
of each
source set.
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.
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:
lombok {
version = "1.18.24"
}
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
andcompileOnly
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
|
In contrast to the |
Maven
19. Maven Plugins
This chapter describes all the plugins contained in the maven-plugin
module.
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.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 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.9. io.freefair.aggregate-javadoc-jar
This plugin is a shortcut which applies the following plugins:
19.11. 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.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.14. 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.15. 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.16. io.freefair.maven-central.validate-poms
This plugin adds a ValidateMavenPom
task for each
GenerateMavenPom
task.
Maven-Plugin
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.
24. MkDocs Tasks
All MkDocs tasks can be found in the
io.freefair.gradle.plugins.mkdocs.tasks
package
OkHttp
An HTTP & HTTP/2 client for Android and Java applications
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
task myDownload(type: io.freefair.gradle.plugins.okhttp.tasks.DownloadFile) { url = "https://example.com/foo.txt" outputFile = file("build/foo.txt") }
See also OkHttpRequestTask
|
26.3. UploadFile
task myUpload(type: io.freefair.gradle.plugins.okhttp.tasks.UploadFile) { url = "https://example.com/foo.txt" file = file("build/file.txt") contentType = "text/plain" }
See also OkHttpRequestTask
|