What Is Rat?

Apache Rat is a release audit tool, focused on licenses.

Use Rat to improve accuracy and efficiency when checking releases for licenses.

Reviewing releases in the Apache Incubator by hand was error-prone and time-consuming. Rat arises from the Apache style, but is used more widely.

Apache Rat is part of the Apache Creadur language- and build-agnostic suite of tools for auditing and comprehending software distributions. Our community develops open source software the Apache way.

Please feel free to contribute a patch, demonstrate a bug, or just talk to us. All welcome :-)

How Do I Use Rat?

Apache Rat 0.17-SNAPSHOT ships with tooling for

• Apache Ant,
• Apache Maven and
• the command line.

Rat is extensible. If your build tool isn't supported, please contribute a patch or talk to us.

Rat aspires to be self documenting. Please contribute a patch or talk to us whenever Rat falls short.

How do I extend Rat

There are several standard ways to extend Rat.

• Add a license definition via an XML file.
• Add a new Matcher definition. Requires Java expertise.
• Add a new definition format. Requires Java expertise as well as expertise with the format.
• Write a new output report. Requires XSLT knowledge.
• Write a new user interface. Requires Java expertise, but there are tools to help.

Command Line

To run from the command line enter the following command:

java -jar apache-rat-0.17-SNAPSHOT.jar [options] [Directory or Archive]

Where "[options]" are one or more of the options listed in the table above (for CLI), and "[Directory or Archive]" is the directory or archive you want to process. There is more detailed information in the CLI documentation.

Apache Ant

Ant support is provided via a task library. This requires Apache Ant 1.7 or later. The Ant library documentation provides detailed information concerning how to load the library and how to use the custom elements and properties for the Rat tasks.

Apache Maven

Within the Maven ecosystem the Rat Maven plugin can be used. The plugin supports Apache Maven 3.9.9 or later.

ATTENTION! Maven4 is based on Java 17 and thus cannot be used with RAT, that relies on Java 8.

To use the plugin add the following information to your pom file.

  <plugin>
    <groupId>org.apache.rat</groupId>
    <artifactId>apache-rat-plugin</artifactId>
    <version>0.17-SNAPSHOT</version>
  </plugin>

Detailed information about the Maven plugin is available.

Styling output

Rat allows you to style the output as you see fit. Three stylesheets are included in the rat package.

• plain-rat - The default stylesheet.
• unapproved-licenses - Lists only the files with unapproved licenses.
• missing-headers - List only files that are missing headers.

These stylesheets can be specified using options in the command line, Maven or Ant clients.

In addition, new stylesheets may be developed and applied to create new reports.

Standard license and matcher definitions.

Rat ships with a number of licenses, license families, and matcher definitions. Additional definitions/implementations of these objects may be added to the system as noted in the license definition document. A list of default licenses is also available.

Checkout the code

Rat uses a Git repository. You can clone it using:

git clone https://gitbox.apache.org/repos/asf/creadur-rat.git

For more information about how to access our repository please read our source code management documentation.

Building Rat

Build Rat with Apache Maven preferably version 3.9.9 or later.

There are two methods for building the Rat suite:

cd creadur-rat
mvn clean install

or with the included Maven wrapper

cd creadur-rat
./mvnw