For Apache Netbeans the rules of the ASF need to be followed when dealing with licensing. So the base of the guide is formed by:

ASF Legal Previously Asked Questions

ASF Source Header and Copyright Notice Policy

Checking licensing state

To aid in the license check the Apache Netbeans build system has the rat target. That target invokes the `release audit tool` (https://creadur.apache.org/rat/) which basicly scans all files for license information. It can be invoked by calling:

ant rat

That call will check the default cluster. As with most calls to the build system you can choose a different cluster at call time:

ant -Dcluster.config=full rat

will run the RAT check on the full cluster. That call will create a bunch of files, that help evaluating the licensing state:

  • A text summary is outputted to: 
    • nbbuild/build/rat-report.txt (Summary of the analysis)
    • nbbuild/build/rat-appendix.txt (Summary of the Exceptions)
  • A pseudo unittest output is generated as nbbuild/build/rat/<CLUSTER>.xml

Checking formal license formatting/handling

Apache Netbeans has to places where licenses are referenced/specified: The licenseinfo.xml files

Handling exceptions

The ASF requires license info placed into each file header. There are exceptions to this rule and there are situations where license info can't be included in files. There are two mechanisms currently employed to exclude/enhance the rat scan:

Global RAT Exclusions

A global file nbbuild/rat-exclusions.txt allows excluding groups of files from rat scan. The primary use case are generated files that can't hold license information, because added license would be removed on next change of the base data or can't hold licenses.

Per file info - licenseinfo.xml

This is a summary - the authorative source is org.netbeans.nbbuild.extlibs.licenseinfo

A more finegrained mechanism was introduced to allow documentation of licenses and notice information. The file licenseinfo.xml should be placed in the root directory of the module and must be valid XML. The types:

  • licenseinfo:
    • root element
    • can hold arbitrary count of child-elements of type fileset
  • fileset:
    • Group of identically licensed files
    • can hold arbitrary count of child-elements of type file
    • can hold exactly one child-element of type comment
    • can hold exactly one child-element of type notice
    • can hold exactly one child-element of type sourceOnly
    • can hold exactly one child-element of type license
  • license:
    • can have an attribute ref, which is a reference to one of the licenses contained in the `nbbuild/licenses` directory.
    • if license additions are present or license clarifications are necessary, the text-content of the element can be used.
  • comment:
    • can have an attribute type to specify one of the predefined reasons for inclusion of the file. Currently supported values:
      • TEMPLATE_MINIMAL_IP: The file is used as a template and contains minimal IP.
      • CATEGORY_B: The contained code is used at runtime and must be included in source form.
      • COMMENT_UNSUPPORTED: Filetype does not support comments.
      • GUI_USABILITY: Code is visible at runtime and added license would negatively affect usability.
    • if none of the type values match, it can contain text content explaining the file (why is it there)
  • notice:
    • allows extensions to the generated NOTICE file
    • The text-content will be copied verbatim to the NOTICE file
  • sourceOnly:
    • no attributes
    • no child content
    • if present indicates, that the file is only used at build-time
  • file:
    • only supports text content
    • text content is a relative path to the referenced file

Sample (in production, there also need to be an XML declaration and the ASF license header):

<licenseinfo>
    <fileset>
        <file>antsrc/org/netbeans/nbbuild/xhtml-lat1.ent</file>
        <license ref="W3C2" />
        <sourceOnly />
    </fileset>
    <fileset>
        <file>javadoctools/resources/stability-deprecated.png</file>
        <license ref="Apache-2.0-ASF" />
        <comment type="COMMENT_UNSUPPORTED" />
    </fileset>
</licenseinfo>

The first block references an entity definition. The file is only used at build time and is not integrated into binaries. The file is licensed according to the W3C software license.

The second block references an image. The image was donated to the ASF and so is covered by the Apache License Version 2 and owned by the ASF. A reasoning for not including the license information in the file is here, that the file type does not comments (or comments, that can be parsed by the RAT tool).

Dependencies

The dependencies of netbeans are downloaded by the build system. The files are declared in the per module file external/binaries-list. For each file that is specified there a companion file `<basename>-license.txt` is required and if needed a `<basename>-notice.txt` file can be supplied.

`<basename>-license.txt`

This is a summary - the authorative source is org.netbeans.nbbuild.extlibs.VerifyLibsAndLicenses

The file consists of a set of headers and the license file, that is applied to the file <basename>.<ext>. There are certain headers that are required:

  • Name: Human readable name of the dependency
  • Version: Version of the artifact
  • Description: Description of the artifact - if the name is self-explanatory repeat it
  • License: The name of the license. It is a filename that must refer to a file inside the nbbuild/licenses folder
  • Origin: Description of the source of the Artifact

Optional headers:

  • Files: If the license file applies to multiple artifacts, these can be listed here and don't need separate copies. The files are separated by space or comma.
  • Source: URL where the source code for the artifact can be found
  • URL: URL where the artifact can be downloaded
  • Comment: Additional explanation for the artifact. For example useful for non-redistributable artifacts to explain their presence and describe how the artifacts are used
  • Type: declare special typed of dependencies, currently supported values are:
    • compile-time: The artifact is not redistributed and only used at build time
    • generated: The artifact is created at build time

Checking licenses

The content of a license file must be checked by humans and is a task that the committer has to do when merging into the repository. To check the structural aspects, there are two ant tasks, that can be run from the root of the repository:

# Check the licenses for dependencies, that are part of the current build configuration
ant verify-libs-and-licenses
# Check _all_ libraries (this included modules not referenced in a cluster (this also contrib))
ant verify-all-libs-and-licenses

The result of these calls is written to nbbuild/build/verifylibsandlicenses.xml which should be checked if a test failure is reported.


  • No labels