| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| ~~ 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. |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| ----- |
| Built-In Types |
| ----- |
| |
| Built-In Types |
| |
| The Rat Antlib defines a few Ant types that can be used as nested |
| elements to the {{{./report.html} Report Task}} as license matchers or |
| license families. |
| |
| In order to stay compatible with Ant 1.7.1 these types are defined |
| via {{{http://ant.apache.org/manual/Tasks/typedef.html} |
| <<<typedef>>>}} rather than |
| {{{http://ant.apache.org/manual/Tasks/componentdef.html} |
| <<<componentdef>>>}} which means they can be defined outside of the |
| Report task as well - but they will be completely useless there. |
| |
| {License Matchers} |
| |
| The following types correspond to the built-in license matchers of Rat: |
| |
| *-------*---------+-------------+ |
| | Typename | Detected License | Corresponding class | |
| *-------*---------+-------------+ |
| | asl20 | Apache License 2.0 | <<<org.apache.rat.analysis.license.ApacheSoftwareLicense20>>> |
| *-------*---------+-------------+ |
| | dojo | {{{http://dojotoolkit.org/community/licensing.shtml}License of the Dojo Toolkit}} | <<<org.apache.rat.analysis.license.DojoLicenseHeader>>> |
| | <since Rat Antlib 0.8> | | |
| *-------*---------+-------------+ |
| | generated | Generated documents that don't need a license | <<<org.apache.rat.analysis.generation.GeneratedLicenseNotRequired>>> |
| *-------*---------+-------------+ |
| | gpl1 | {{{http://www.gnu.org/licenses/old-licenses/gpl-1.0.html}GNU General Public License, version 1}} | <<<org.apache.rat.analysis.license.GPL1License>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | gpl2 | {{{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html}GNU General Public License, version 2}} | <<<org.apache.rat.analysis.license.GPL2License>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | gpl3 | {{{http://www.gnu.org/licenses/gpl.html}GNU General Public License, version 3}} | <<<org.apache.rat.analysis.license.GPL3License>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | javadoc | Javadocs that don't need a license | <<<org.apache.rat.analysis.generation.JavaDocLicenseNotRequired>>> |
| *-------*---------+-------------+ |
| | mit | {{{http://www.opensource.org/licenses/MIT}The MIT License}} | <<<org.apache.rat.analysis.license.MITLicense>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | oasis | OASIS copyright claim plus derivative work clause | <<<org.apache.rat.analysis.license.OASISLicense>>> |
| | <since Rat Antlib 0.8> | | |
| *-------*---------+-------------+ |
| | w3c | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<<org.apache.rat.analysis.license.W3CLicense>>> |
| *-------*---------+-------------+ |
| | w3c-doc | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<<org.apache.rat.analysis.license.W3CDocLicense>>> |
| *-------*---------+-------------+ |
| |
| While these types may technically provide attributes or nested |
| elements you should use them as sole tags. |
| |
| * {<<<substringMatcher>>>} |
| |
| <since Rat Antlib 0.8> |
| |
| For the simple case where a license can be detected by searching for |
| a given string in a single line of the source code - in fact this is what |
| many built-in implementations do - you can use the |
| <<<substringMatcher>>> type. |
| |
| ** Attributes of the Type |
| |
| *-------------------------*-------------------------------+ |
| |Name |Description | |
| *-------------------------*-------------------------------+ |
| | licenseFamilyCategory | Short name of the detected license. Should be at most five characters long if you want to keep the layout of the plain text report. |
| | | This will be printed next to to the checked file inside the plain text report and creates <<<header-type>>> elements inside the XML report. |
| | | <<REQUIRED>> |
| *-------------------------*-------------------------------+ |
| | licenseFamilyName | Long name of the detected license. The value is checked against the list of approved licenses. |
| | | This will not appear inside the plain text report and creates <<<license-family>>> elements inside the XML report. |
| | | <<REQUIRED>> |
| *-------------------------*-------------------------------+ |
| | notes | Additional notes you want to provide. |
| | | This will not appear inside the plain text report and creates <<<header-sample>>> elements inside the XML report. |
| *-------------------------*-------------------------------+ |
| |
| ** Nested Elements Supported by the Type |
| |
| The substring(s) to look for are specified as nested <<<pattern>>> |
| elements with a substring attribute. You can specifiy multiple |
| <<<pattern>>> elements and the <<<substringMatcher>>> will claim the |
| license matches if at least one substring can be found. |
| |
| At least one pattern is required. |
| |
| ** Example |
| |
| Taking the example of {{{./examples/custom.html}the custom types page}} |
| in order to detect |
| |
| ------------------------------------------------------------------ |
| /** |
| * Yet Another Software License, 1.0 |
| * |
| * Lots of text, specifying the users rights, and whatever ... |
| */ |
| ------------------------------------------------------------------ |
| |
| you could use |
| |
| ------------------------------------------------------------------ |
| <rat:report> |
| <fileset dir="src"/> |
| <rat:substringMatcher licenseFamilyCategory="YASL1" |
| licenseFamilyName="Yet Another Software License, Version 1.0"> |
| <pattern substring="Yet Another Software License, 1.0"/> |
| </rat:substringMatcher> |
| </rat:report> |
| ------------------------------------------------------------------ |
| |
| * {<<<fullTextMatcher>>>} |
| |
| <since Rat Antlib 0.9> |
| |
| This matcher searches for the full text given, ignoring everything |
| that is not a character or a number (and for US-ASCII characters it |
| is case-insensitive). This allows licenses to be detected that can't |
| be identified by a single line, even if the formatting has been |
| changed. |
| |
| ** Attributes of the Type |
| |
| *-------------------------*-------------------------------+ |
| |Name |Description | |
| *-------------------------*-------------------------------+ |
| | licenseFamilyCategory | Short name of the detected license. Should be at most five characters long if you want to keep the layout of the plain text report. |
| | | This will be printed next to to the checked file inside the plain text report and creates <<<header-type>>> elements inside the XML report. |
| | | <<REQUIRED>> |
| *-------------------------*-------------------------------+ |
| | licenseFamilyName | Long name of the detected license. The value is checked against the list of approved licenses. |
| | | This will not appear inside the plain text report and creates <<<license-family>>> elements inside the XML report. |
| | | <<REQUIRED>> |
| *-------------------------*-------------------------------+ |
| | notes | Additional notes you want to provide. |
| | | This will not appear inside the plain text report and creates <<<header-sample>>> elements inside the XML report. |
| *-------------------------*-------------------------------+ |
| | fullText | The license text to look for. |
| | | Everything that is not a character or a digit will be ignored. |
| | | <<REQUIRED>> unless the text is specified as nested content. |
| *-------------------------*-------------------------------+ |
| |
| You can also nest the license text directly as content into the type. |
| |
| ** Example |
| |
| Taking the example of {{{./examples/custom.html}the custom types page}} |
| in order to detect |
| |
| ------------------------------------------------------------------ |
| /** |
| * Yet Another Software License, 1.0 |
| * |
| * Lots of text, specifying the users rights, and whatever ... |
| */ |
| ------------------------------------------------------------------ |
| |
| you could use |
| |
| ------------------------------------------------------------------ |
| <rat:report> |
| <fileset dir="src"/> |
| <rat:fullTextMatcher licenseFamilyCategory="YASL1" |
| licenseFamilyName="Yet Another Software License, Version 1.0" |
| fullText="Yet Another Software License, 1.0 Lots of text, specifying the users rights, and whatever"> |
| </rat:fullTextMatcher> |
| </rat:report> |
| ------------------------------------------------------------------ |
| |
| or |
| |
| ------------------------------------------------------------------ |
| <rat:report> |
| <fileset dir="src"/> |
| <rat:fullTextMatcher licenseFamilyCategory="YASL1" |
| licenseFamilyName="Yet Another Software License, Version 1.0"> |
| Yet Another Software License, 1.0 |
| |
| Lots of text, specifying the users rights, and whatever |
| </rat:fullTextMatcher> |
| </rat:report> |
| ------------------------------------------------------------------ |
| |
| {License Families} |
| |
| The following types correspond to the built-in license families of Rat: |
| |
| *-------*---------+-------------+ |
| | Typename | License Family | Corresponding class | |
| *-------*---------+-------------+ |
| *-------*---------+-------------+ |
| | academic-free-21 | Academic Free License 2.1 | <<<org.apache.rat.license.AcademicFree21LicenseFamily>>> |
| | <since Rat Antlib 0.8> | | |
| *-------*---------+-------------+ |
| | apache20-license | Apache License 2.0 | <<<org.apache.rat.license.Apache20LicenseFamily>>> |
| *-------*---------+-------------+ |
| | gpl1-family | GNU General Public License, version 1 | <<<org.apache.rat.license.GPL1LicenseFamily>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | gpl2-family | GNU General Public License, version 2 | <<<org.apache.rat.license.GPL2LicenseFamily>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | gpl3-family | GNU General Public License, version 3 | <<<org.apache.rat.license.GPL3LicenseFamily>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | mit-family | The MIT License | <<<org.apache.rat.license.MITLicenseFamily>>> |
| | <since Rat Antlib 0.9> | | |
| *-------*---------+-------------+ |
| | modified-bsd | Modified BSD License | <<<org.apache.rat.license.ModifiedBSDLicenseFamily>>> |
| | <since Rat Antlib 0.8> | | |
| *-------*---------+-------------+ |
| | oasis-license | OASIS copyright claim plus derivative work clause | <<<org.apache.rat.license.OASISLicenseFamily>>> |
| | <since Rat Antlib 0.8> | | |
| *-------*---------+-------------+ |
| | w3c-doc-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<<org.apache.rat.license.W3CDocumentLicenseFamily>>> |
| *-------*---------+-------------+ |
| | w3c-soft-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<<org.apache.rat.license.W3CSoftwareLicenseFamily>>> |
| *-------*---------+-------------+ |
| |
| While these types may technically provide attributes or nested |
| elements you should use them as sole tags. |
| |
| * {<<<approvedLicense>>>} |
| |
| <since Rat Antlib 0.8> |
| |
| This wrapper type makes it easy to specify a license name for new |
| approved licenses. The type has a single attribute <<<familyName>>> |
| that must match the license family name returned by the license |
| matcher to make a license approved. |
| |
| ** Example |
| |
| To make the YASL license of the {{substringMatcher}} Example approved |
| you'd use |
| |
| ------------------------------------------------------------------ |
| <rat:report> |
| <fileset dir="src"/> |
| <rat:substringMatcher licenseFamilyCategory="YASL1" |
| licenseFamilyName="Yet Another Software License, Version 1.0"> |
| <pattern substring="Yet Another Software License, 1.0"/> |
| </rat:substringMatcher> |
| <rat:approvedLicense |
| familyName="Yet Another Software License, Version 1.0"/> |
| </rat:report> |
| ------------------------------------------------------------------ |
