Ant Elements and Attributes

The RAT Ant Task Library has many of the same options as the command line as well as a few that are specific to the Ant environment. The Ant UI implements the RAT options as attributes or child nodes.

Root Node

The report is the root node for the RAT report. All child nodes must be enclosed within it. All attributes listed below are attributes applied to the report node. The report node must have a fileSet to specify the files to process.

<project
    xmlns:rat="antlib:org.apache.rat.anttasks"
    xmlns="antlib:org.apache.tools.ant">
    ...
    <rat:report>
        <fileset dir="path/to/source"/>
    </rat:report>
    ...
</project>

The Child Nodes

The argument types specified in the list below are defined in a section following.

<config>

File names for system configuration.

Required: false
Argument Type: <File>
Argument Count: Unlimited.
Example: <rat:report> <config> <fileset file='data' /> </config> </rat:report>

<counterMax>

The acceptable maximum number for the specified counter. A value of '-1' specifies an unlimited number.

Required: false
Argument Type: <CounterPattern>
Argument Count: Unlimited.
Example: <rat:report> <counterMax><cntr>data</cntr> </counterMax> </rat:report>

<counterMin>

The minimum number for the specified counter.

Required: false
Argument Type: <CounterPattern>
Argument Count: Unlimited.
Example: <rat:report> <counterMin><cntr>data</cntr> </counterMin> </rat:report>

<exclude>

Deprecated for removal since 0.17: Use <inputExclude> instead. Excludes files matching <Expression>.

Required: false
Argument Type: <Expression>
Argument Count: Unlimited.
Example: <rat:report> <exclude><expr>data</expr> </exclude> </rat:report>

<include>

Deprecated for removal since 0.17: Use <inputInclude> instead. Includes files matching <Expression>. Will override excluded files.

Required: false
Argument Type: <Expression>
Argument Count: Unlimited.
Example: <rat:report> <include><expr>data</expr> </include> </rat:report>

<inputExclude>

Excludes files matching <Expression>.

Required: false
Argument Type: <Expression>
Argument Count: Unlimited.
Example: <rat:report> <inputExclude><expr>data</expr> </inputExclude> </rat:report>

<inputExcludeParsedScm>

Parse SCM based exclusion files to exclude specified files and directories. This action can apply to any standard collection that implements a file processor.

Required: false
Argument Type: <StandardCollection>
Argument Count: Unlimited.
Example: <rat:report> <inputExcludeParsedScm><std>data</std> </inputExcludeParsedScm> </rat:report>

<inputInclude>

Includes files matching <Expression>. Will override excluded files.

Required: false
Argument Type: <Expression>
Argument Count: Unlimited.
Example: <rat:report> <inputInclude><expr>data</expr> </inputInclude> </rat:report>

<licenseFamiliesApproved>

A comma separated list of approved license family IDs. These license families will be added to the list of approved license families.

Required: false
Argument Type: <FamilyID>
Argument Count: 1
Example: <rat:report> <licenseFamiliesApproved><lst>data</lst> </licenseFamiliesApproved> </rat:report>

<licenseFamiliesDenied>

A comma separated list of denied License family IDs. These license families will be removed from the list of approved licenses. Once license families are removed they can not be added back.

Required: false
Argument Type: <FamilyID>
Argument Count: 1
Example: <rat:report> <licenseFamiliesDenied><lst>data</lst> </licenseFamiliesDenied> </rat:report>

<licenses>

Deprecated for removal since 0.17: Use <config> instead. File names for system configuration.

Required: false
Argument Type: <File>
Argument Count: Unlimited.
Example: <rat:report> <licenses> <fileset file='data' /> </licenses> </rat:report>

<licensesApproved>

A comma separated list of approved License IDs. These licenses will be added to the list of approved licenses.

Required: false
Argument Type: <LicenseID>
Argument Count: 1
Example: <rat:report> <licensesApproved><lst>data</lst> </licensesApproved> </rat:report>

<licensesDenied>

A comma separated list of denied License IDs. These licenses will be removed from the list of approved licenses. Once licenses are removed they can not be added back.

Required: false
Argument Type: <LicenseID>
Argument Count: 1
Example: <rat:report> <licensesDenied><lst>data</lst> </licensesDenied> </rat:report>

The Attributes

The attributes apply to the report element.

addLicense attribute

Deprecated for removal since 0.17: Use editLicense attribute instead. Add the Apache-2.0 license header to any file with an unknown license that is not in the exclusion list.

Required: false
Example: <rat:report addLicense="true"> </rat:report>

configurationNoDefaults attribute

Ignore default configuration.

Required: false
Example: <rat:report configurationNoDefaults="true"> </rat:report>

copyright attribute

Deprecated for removal since 0.17: Use editCopyright attribute instead. The copyright message to use in the license headers.

Required: false
Example: <rat:report editLicense="true" copyright="data"> </rat:report>

dryRun attribute

If set do not update the files but generate the reports.

Required: false
Example: <rat:report dryRun="true"> </rat:report>

editCopyright attribute

Required: false
Example: <rat:report editLicense="true" editCopyright="data"> </rat:report>

editLicense attribute

Add the Apache-2.0 license header to any file with an unknown license that is not in the exclusion list. By default new files will be created with the license header, to force the modification of existing files use the --edit-overwrite option.

Required: false
Example: <rat:report editLicense="true"> </rat:report>

editOverwrite attribute

Forces any changes in files to be written directly to the source files so that new files are not created. Only valid with --edit-license.

Required: false
Example: <rat:report editLicense="true" editOverwrite="true"> </rat:report>

excludeFile attribute

Deprecated for removal since 0.17: Use inputExcludeFile attribute instead. Reads <Expression> entries from a file. Entries will be excluded from processing.

Required: false
Example: <rat:report excludeFile="data"> </rat:report>

force attribute

Deprecated for removal since 0.17: Use editOverwrite attribute instead. Forces any changes in files to be written directly to the source files so that new files are not created.

Required: false
Example: <rat:report editLicense="true" force="true"> </rat:report>

helpLicenses attribute

Print information about registered licenses.

Required: false
Example: <rat:report helpLicenses="true"> </rat:report>

includesFile attribute

Deprecated for removal since 0.17: Use inputIncludeFile attribute instead. Reads <Expression> entries from a file. Entries will be excluded from processing.

Required: false
Example: <rat:report includesFile="data"> </rat:report>

inputExcludeSize attribute

Excludes files with sizes less than the number of bytes specified.

Required: false
Example: <rat:report inputExcludeSize="data"> </rat:report>

listFamilies attribute

Deprecated for removal since 0.17: Use outputFamilies attribute instead. List the defined license families.

Required: false
Example: <rat:report listFamilies="data"> </rat:report>

listLicenses attribute

Deprecated for removal since 0.17: Use outputLicenses attribute instead. List the defined licenses.

Required: false
Example: <rat:report listLicenses="data"> </rat:report>

noDefaultLicenses attribute

Deprecated for removal since 0.17: Use configurationNoDefaults attribute instead. Ignore default configuration.

Required: false
Example: <rat:report noDefaultLicenses="true"> </rat:report>

out attribute

Deprecated for removal since 0.17: Use outputFile attribute instead. Define the output file where to write a report to.

Required: false
Example: <rat:report out="data"> </rat:report>

outputArchive attribute

Specifies the level of detail in ARCHIVE file reporting.

Required: false
Example: <rat:report outputArchive="data"> </rat:report>

outputFamilies attribute

List the defined license families.

Required: false
Example: <rat:report outputFamilies="data"> </rat:report>

outputFile attribute

Define the output file where to write a report to.

Required: false
Example: <rat:report outputFile="data"> </rat:report>

outputLicenses attribute

List the defined licenses.

Required: false
Example: <rat:report outputLicenses="data"> </rat:report>

outputStandard attribute

Specifies the level of detail in STANDARD file reporting.

Required: false
Example: <rat:report outputStandard="data"> </rat:report>

outputStyle attribute

XSLT stylesheet to use when creating the report. Either an external xsl file may be specified or one of the internal named sheets.

Required: false
Example: <rat:report outputStyle="data"> </rat:report>

scanHiddenDirectories attribute

Deprecated for removal since 0.17: Use <inputIncludeStd> with 'HIDDEN_DIR' argument instead. Scans hidden directories.

Required: false
Example: <rat:report scanHiddenDirectories="true"> </rat:report>

stylesheet attribute

Deprecated for removal since 0.17: Use outputStyle attribute instead. XSLT stylesheet to use when creating the report.

Required: false
Example: <rat:report stylesheet="data"> </rat:report>

xml attribute

Deprecated for removal since 0.17: Use outputStyle attribute with the 'xml' argument instead. forces XML output rather than the textual report.

Required: false
Example: <rat:report xml="true"> </rat:report>

Argument Types

Arg

A string

CounterPattern

A pattern comprising one of the following prefixes followed by a colon and a count (e.g. UNAPPROVED:5). Prefixes are

APPROVED: A count of approved licenses. Default range [0, unlimited]
ARCHIVES: A count of archive files. Default range [0, unlimited]
BINARIES: A count of binary files. Default range [0, unlimited]
DOCUMENT_TYPES: A count of distinct document types. Default range [1, unlimited]
IGNORED: A count of ignored files. Default range [0, unlimited]
LICENSE_CATEGORIES: A count of distinct license categories. Default range [1, unlimited]
LICENSE_NAMES: A count of distinct license names. Default range [1, unlimited]
NOTICES: A count of notice files. Default range [0, unlimited]
STANDARDS: A count of standard files. Default range [1, unlimited]
UNAPPROVED: A count of unapproved licenses. Default range [0, 0]
UNKNOWN: A count of unknown file types. Default range [0, unlimited]

DirOrArchive

A directory or archive file to scan.

Expression

A file matching pattern usually of the form used in Ant build files and '.gitignore' files (see https://ant.apache.org/manual/dirtasks.html#patterns for examples). Regular expression patterns may be specified by surrounding the pattern with '%regex[' and ']'. For example '%regex[[A-Z].*]' would match files and directories that start with uppercase latin letters.

FamilyID

The ID for a license family.

File

A file name.

Integer

An integer value.

LicenseFilter

A defined filter for the licenses to include. Valid values: ALL, APPROVED, NONE.

LicenseID

The ID for a license.

LogLevel

The log level to use. Valid values DEBUG, INFO, WARN, ERROR, OFF.

ProcessingType

Specifies how to process file types. Valid values are: * NOTIFICATION: List file as present

PRESENCE: List any licenses found
ABSENCE: List licenses found and any unknown licences

StandardCollection

Defines standard expression patterns (see above). Valid values are:

ALL: All of the Standard Excludes combined.
ARCH: The files and directories created by an ARCH source code control based tool.
BAZAAR: The files and directories created by a Bazaar source code control based tool.
BITKEEPER: The files and directories created by a Bitkeeper source code control based tool.
CVS: The files and directories created by a CVS source code control based tool.
DARCS: The files and directories created by a DARCS source code control based tool.
ECLIPSE: The files and directories created by an Eclipse IDE based tool.
GIT: The files and directories created by GIT source code control to support GIT, also processes files listed in '.gitignore' and (unless RAT_NO_GIT_GLOBAL_IGNORE is specified) the global gitignore.
HIDDEN_DIR: The hidden directories. Directories with names that start with '.'
HIDDEN_FILE: The hidden files. Directories with names that start with '.'
IDEA: The files and directories created by an IDEA IDE based tool.
MAC: The .DS_Store files on Mac computers.
MAVEN: The files and directories created by Maven build system based project.
MERCURIAL: The files and directories created by a Mercurial source code control based tool.
MISC: The set of miscellaneous files generally left by editors and the like.
MKS: The files and directories created by an MKS source code control based tool.
RCS: The files and directories created by a RCS source code control based tool.
SCCS: The files and directories created by a SCCS source code control based tool.
SERENA_DIMENSIONS_10: The files and directories created by a Serena Dimensions V10 change control system based tool.
STANDARD_PATTERNS: A standard collection of generally accepted patterns to ignore.
STANDARD_SCMS: A standard collection of SCMs
SUBVERSION: The files and directories created by a Subversion source code control based tool.
SURROUND_SCM: The files and directories created by a Surround SCM source code control based tool.
VSS: The files and directories created by a Visual Source Safe source code control based tool.

A complete description of each of the standard collection types is available.

StyleSheet

Either an external xsl file or one of the internal named sheets. Internal sheets are:

plain-rat: The default style.
missing-headers: Produces a report of files that are missing headers.
unapproved-licenses: Produces a report of the files with unapproved licenses.
xml: Produces output in pretty-printed XML.