~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~   Licensed to the Apache Software Foundation (ASF) under one or more
~~   contributor license agreements.  See the NOTICE file distributed with
~~   this work for additional information regarding copyright ownership.
~~   The ASF licenses this file to You under the Apache License, Version 2.0
~~   (the "License"); you may not use this file except in compliance with
~~   the License.  You may obtain a copy of the License at
~~
~~       http://www.apache.org/licenses/LICENSE-2.0
~~
~~   Unless required by applicable law or agreed to in writing, software
~~   distributed under the License is distributed on an "AS IS" BASIS,
~~   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~   See the License for the specific language governing permissions and
~~   limitations under the License.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                   --------------------------
                   A Release Audit Tool
                   --------------------------

Apache Rat

 In a hurry? Jump to {{{Quick_Start:_Running_Rat}quick start}}

%{toc|fromDepth=2|toDepth=3}

* About Rat

** What Is Rat?

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

** Rat Is Used To...?

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

** Why Develop Rat?

 Reviewing releases in the {{{https://incubator.apache.org/}Apache Incubator}}
 by hand was error-prone and time-consuming.

 Rat arises from the Apache style, but is used more widely.
 If your release style isn't supported,
 {{{./mailing-lists.html}talk to us}}.

** How Do I Use Rat?

 Apache Rat ${project.version} ships with tooling for

   * {{{https://ant.apache.org/}Apache Ant}},

   * {{{https://maven.apache.org}Apache Maven}} and

   * the command line.

 Rat is extensible. If your build tool isn't supported, please contribute a
 {{{./issue-management.html}patch}} or
 {{{./mailing-lists.html}talk to us}}.

 Rat aspires to be self documenting. Please contribute a
 {{{./issue-management.html}patch}} or
 {{{./mailing-lists.html}talk to us}}
 whenever Rat falls short.
 
** How do I extend Rat
 
 There are several standard ways to extend Rat.
 
   * Add a {{{./license_def.html}license definition}} via an XML file.
   
   * Add a new {{{./matcher_def.html}Matcher definition}}. Requires Java expertise.
   
   * Add a new definition format.  Requires Java expertice as well as expertise with the format.

** Who Develops Rat?

  Apache Rat is part of the {{{https://creadur.apache.org}Apache Creadur}}
  language- and build-agnostic suite of tools for auditing and comprehending
  software distributions. Our community develops
  {{{https://opensource.org/} open source software}} the
  {{{https://www.apache.org/foundation/how-it-works.html} Apache way}}.

  Please feel free to contribute a
  {{{./issue-management.html}patch}},
  {{{https://wiki.c2.com/?TestDrivenDevelopment}demonstrate}} a
  {{{./issue-management.html}bug}}, or
  just
  {{{./mailing-lists.html}talk to us}}.
  All welcome :-)

* Quick Start: Running Rat

** Command Line

 Quick start by

+------------------------------------------+
java -jar apache-rat-${project.version}.jar --help
+------------------------------------------+

 Read more {{{./apache-rat/index.html}here}}.

** Apache Ant

 Use the task library for {{{https://ant.apache.org/} Apache Ant 1.7}} or later

 Read more {{{./apache-rat-tasks/index.html} here}}.

** Apache Maven

 Use the plugin for {{{https://maven.apache.org}Apache Maven ${mavenVersion}}} or later.

+------------------------------------------+
  <plugin>
    <groupId>org.apache.rat</groupId>
    <artifactId>apache-rat-plugin</artifactId>
    <version>${project.version}</version>
  </plugin>
+------------------------------------------+

 Read more {{{./apache-rat-plugin/index.html} here}}.

** Styling output

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

  * {{{https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl}plain-rat}} - The default stylesheet.

  * {{{https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl}unapproved-licenses}} - Lists only the files with unapproved licenses.

  * {{{https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl}missing-headers}} - List only files that are missing headers.

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

* Checking Out Rat

  Quick start

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

 Read more {{{./scm.html}here}}.

* Building Rat

 Build Rat with {{{https://maven.apache.org/} Apache Maven}}

 Quick start

 If you want to build RAT just launch 'mvn' or './mvnw' inside the root folder. It will automatically perform a

+------------------------------------------+
mvn clean install
+------------------------------------------+