Apache RAT (Release Audit Tool) Gradle Plugin

This plugin allows to run the Apache RAT release audit tool, focused on licenses.

It bundles Apache RAT 0.18. The RAT version is an implementation detail and cannot be changed. RAT 0.18 needs Java 17; Gradle itself may run on Java 8, see Java for RAT.

Installation

In your build.gradle(.kts) file:

plugins {
    id("org.nosphere.apache.rat") version "0.11.0"
}

Upgrading from 0.9.0? See the migration guide.

Usage

The plugin registers a task named rat that you can configure in your build.gradle(.kts) file:

tasks.rat {

    // Use the default RAT license header matchers, defaults to `true`
    addDefaultMatchers.set(false)

    // Add custom substring license header matchers
    // First argument is the license family category: at most 5 characters,
    // and it must not clash with another license family
    substringMatcher("MYFOO", "My Foo License", "pattern-1", "pattern-2")

    // Declare approved license families, by name or by category
    // If used, any non-declared family won't be approved
    approvedLicense("MIT")

    // Input directory, defaults to '.'
    inputDir.set(file("some/path"))

    // List of Gradle exclude directives, defaults to ['**/.gradle/**']
    excludes.add("**/build/**")

    // RatTask 0.5.0+ implements PatternFilterable
    exclude { it.file in configurations.someConf.files }

    // XML, TXT and HTML reports directory, defaults to 'build/reports/rat'
    reportDir.set(file("some/other/path"))

    // Fail the build when the audit finds unapproved licenses, defaults to true
    // Invalid configuration always fails the build, whatever this is set to
    failOnError.set(false)

    // Print the unapproved files and the license families in use, defaults to false
    verbose.set(true)
}

rat {

    // Use the default RAT license header matchers, defaults to `true`
    addDefaultMatchers.set(false)

    // Add custom substring license header matchers
    // First argument is the license family category: at most 5 characters,
    // and it must not clash with another license family
    substringMatcher("MYFOO", "My Foo License", "pattern-1", "pattern-2")

    // Declare approved license families, by name or by category
    // If used, any non-declared family won't be approved
    approvedLicense("MIT")

    // Input directory, defaults to '.'
    inputDir.set(file("some/path"))

    // List of Gradle exclude directives, defaults to ['**/.gradle/**']
    excludes.add("**/build/**")

    // XML, TXT and HTML reports directory, defaults to 'build/reports/rat'
    reportDir.set(file("some/other/path"))

    // Fail the build when the audit finds unapproved licenses, defaults to true
    // Invalid configuration always fails the build, whatever this is set to
    failOnError.set(false)

    // Print the unapproved files and the license families in use, defaults to false
    verbose.set(true)
}

Excluding files

The task implements Gradle's PatternFilterable. Use exclude(...) to keep files out of the audit:

tasks.rat {
    exclude("**/*.txt")                        // Ant-style pattern
    exclude("build/**")                        // whole directory
    exclude { it.name.startsWith("generated") } // arbitrary rule
}

License families

RAT 0.18 knows these license families. Use either the name or the category in approvedLicenses:

A value that matches no family fails the build and lists the valid ones.

Reports

The task writes three files to reportDir:

Running

gradle rat

If the project has a check task, it is automatically made dependent on the rat task.

When a Rat audit fails, a clickable URL of the HTML report will be printed out:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':rat'.
> A failure occurred while executing org.nosphere.apache.rat.RatWork
   > Apache Rat audit failure - 35 unapproved licenses
     	See file:///path/to/build/reports/rat/index.html

Java for RAT

RAT 0.18 needs Java 17. You normally have nothing to configure: the plugin runs RAT in a separate worker process and picks its JVM by itself:

• Gradle running on Java 17 or later: the worker uses the same JVM as Gradle.

• Gradle running on Java 8 to 16: the plugin asks Gradle's toolchain support for a Java 17 and runs the worker on it. Any JDK 17 Gradle can detect works, see the toolchain documentation. Without one, the build fails with Gradle's own message. On recent Gradle versions it reads:

  Cannot find a Java installation on your machine ... matching: {languageVersion=17, ...}.
  Toolchain download repositories have not been configured.
  

  Install a JDK 17, or let Gradle download one by declaring a toolchain repository in settings.gradle(.kts). For example, you can use the Foojay Toolchains Plugin.

To pick the JVM yourself, set the javaLauncher task property to a Java 17 or later. The javaToolchains extension needs the java-base plugin, or the lighter jvm-toolchains plugin on Gradle 7.6 and later:

plugins {
    id("jvm-toolchains")
}
tasks.rat {
    javaLauncher.set(javaToolchains.launcherFor {
        languageVersion.set(JavaLanguageVersion.of(21))
    })
}

verbose.set(true) prints which JVM the worker runs on.

Logging

The task is quiet on a successful audit. To see RAT's own output, use Gradle's log levels:

Set verbose.set(true) to always print the list of unapproved files and the license families in use.

Compatibility matrix

• (1) Configuration Cache
• (2) Isolated Projects, on Gradle 7.1 and later
• (3) Build Cache