View source for Licensing in Qt's modules

This page provides an overview of how we document copyright and license within the Qt modules and how this information is used.

==Where is licensing documented?==
===In-file using, SPDX tags===
When possible, the copyright and license are documented using a license header. 

There must be at least one line for copyright and one line for the license. It is possible to have multiple copyright lines but there can only be one license line. 

The license must be documented using a SPDX tag and [https://spdx.dev/learn/handling-license-info/ License ID]. If the license is not part of the SPDX license list, it can be documented using ''LicenseRef-'' followed by a chosen ID.

The license IDs must be linked together with one of the following separators: ''WITH'', ''AND'', ''OR''.

Example of a license header:

<syntaxhighlight lang="cpp">
# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
</syntaxhighlight>

===In three types of external files===

====REUSE.toml====
''REUSE.toml'' files document copyright and licensing information when it cannot be included in-file due to file format constraints or when the in-file license corresponds to another file (e.g., for generation or documentation purpose).

The ''REUSE.toml'' files, along with the in-file licensing information are processed by the [https://reuse.software/ reuse tool] to check for [https://reuse.software/tutorial/ '''reuse compliance'''] and generate the [https://reuse.readthedocs.io/en/stable/man/reuse-spdx.html '''source SBOM'''].

Refer to the [https://reuse.software/spec-3.2/#reusetoml ''REUSE.toml'' full documentation]. Below is an example of  a ''REUSE.toml'' file:

<syntaxhighlight lang="bash">
version = 1

[[annotations]]
path = ["<path1>",
        "<folder1/**>",
        "<folder2/*>"]
precedence = "override"
comment = "test"
SPDX-FileCopyrightText = "Copyright (C) 2024 The Qt Company Ltd."
SPDX-License-Identifier = "LicenseRef-Qt-Commercial OR GPL-3.0-only"

[[annotations]]
path = "<path2>"
precedence = "closest"
comment = "test"
SPDX-FileCopyrightText = ["Copyright (C) 2024 The Qt Company Ltd.",
                          "Copyright (C) 2023 someone else"]
SPDX-License-Identifier = "LicenseRef-Qt-Commercial OR GPL-3.0-only"

[[annotations]]
path = "<path3>"
precedence = "aggregate"
comment = "test"
SPDX-FileCopyrightText = "Copyright (C) 2024 The Qt Company Ltd."
SPDX-License-Identifier = "LicenseRef-Qt-Commercial OR GPL-3.0-only"

</syntaxhighlight>

A ''REUSE.toml'' file always starts with ''version''. Each ''annotation'' represents a license and copyright assignment.

About the ''path'' field:
* It specifies where the annotation applies.
* It can be a list.
* I does not support exceptions.
* ''*'' matches everything in a folder.
* ''**'' matches everything in and down a folder.

Licensing information for a given file can be present in-file and in multiple ''REUSE.toml'' files. Precedence rules are set using ''precedence'' field:  
* ''closest'' - Uses in-file licensing if available, otherwise, the annotation from the ''REUSE.toml'' file closest to the file is used.
* ''aggregate'' - Collects all available licensing information for a given file ( from in-file and ''REUSE.toml'' files).
* ''override'' - Uses only the licensing information in the ''REUSE.toml'' file closest to the module's base, ignoring in-file and downstream ''REUSE.toml'' files.

''SPDX-FileCopyrightText'' and ''SPDX-License-Identifier'' are self-explanatory and can contain lists.

Other fields, such as <nowiki>''comment''</nowiki>, may be added for documentation purposes.

====licenseRule.json====
Each Qt module has a single ''licenseRule.json'' file. This file lists the licensing rule for this module. It enforces the [https://contribute.qt-project.org/quips/18 QUIP18] rule set and offers the possibility to add exceptions. The file format is presented in the patch introducing it,  [https://codereview.qt-project.org/c/qt/qtbase/+/536879 for example for qtbase].

This file is read by qtqa license test ''tst_license.pl'' to check the in-file licensing and the source SBOM.

====qt_attribution.json====
[https://contribute.qt-project.org/quips/7 ''qt_attribution.json''] files document information related to the third-party components within a module (see [https://contribute.qt-project.org/quips/4 QUIP4]).

Licensing information from these files is processed by the qattributionscanner tool to generate the third party licensing information in the Qt documentation.

==License files==

License files corresponding to an SPDX license tag or referenced within a used ''REUSE.toml'' annotation must be found in the ''LICENSES'' directory at the base of the module. The license file name must follow the format: ''<Id>.txt''. 

Any unused license file present in ''LICENSES'' directory breaks reuse compliance.

A license file corresponding to a license ID documented only in a ''qt_attribution.json'' file should be placed next to the ''qt_attribution.json'' file and be named ''LICENSE.Id.json''

License files must either be located in ''LICENSES'' directory or have a ''LICENSE.'' prefix to ignored by the reuse tool.

==Where is license used?==

===reuse tool===

The reuse tool reads in-file SPDX tags and copyright as well as ''REUSE.toml'' files for '''reuse compliance''' and '''source SBOM''' generation.

To be reuse compliant a module must provide licensing information for all files present in this module with few [https://reuse.software/spec-3.2/#covered-and-ignored-files exceptions], typically ''.gitignore'', files within ''LICENSES'' directory and ''LICENCE.'' prefixed files.

The source SBOM is a SPDX document providing copyright and licensing information for all files in the module, with the same [https://reuse.software/spec-3.2/#covered-and-ignored-files exceptions] as for reuse compliance.

===qtqa license test: ''tst_licenses.pl''===

====License check mode====
In license check mode, ''tst_licenses.pl'' reads copyright and SPDX tag in the file's license header and checks what has been found against our rule set in ''licenseRule.json''. In this test the checking was not made compulsory for every file.

To run a license check on a module, run:
<syntaxhighlight lang="bash">
QT_MODULE_TO_TEST=<path_to_module> perl <path_to_qtqa>/tests/prebuild/license/tst_licenses.pl
</syntaxhighlight>

====Source SBOM check mode====
In source SBOM check mode, ''tst_licenses.pl'' reads the source SBOM generated by the reuse tool. It checks the license ID against our rule set in ''licenseRule.json''.

To create a source SBOM run:
<syntaxhighlight lang="bash">
reuse spdx -o <module_source_SBOM>
</syntaxhighlight>
from the base of the module.

To check the generated source SBOM, run:
<syntaxhighlight lang="bash">
QT_MODULE_TO_TEST=<path_to_module> perl <path_to_qtqa>/tests/prebuild/license/tst_licenses.pl -sbom <module_source_SBOM> -sbomonly
</syntaxhighlight>

At the moment the check is skipping files down the ''3rdparty'' directories.

===qattributionscanner===

This reads the ''qt_attribution.json'' files to provide the licensing for Qt documentation pages.

''qattributionscanner'' is looking for the license files documented in the ''qt_attribution.json''. It searches for the ''<LicenseID>.txt'' files withing the ''LICENSES'' directory or for ''LICENSE.<LicenseID>.txt'' next to the ''qt_attribution.json'' file. The use of ''LicenseFile'' within ''qt_attribution.json'' is discouraged and will soon be deprecated.

==Useful links==

[https://contribute.qt-project.org/quips/18  QUIP18]: The licensing specification in Qt's modules.

[https://contribute.qt-project.org/quips/4/ QUIP04]: Third party components.

[https://wiki.qt.io/SBOM/ SBOM]:  Qt Software Bill of Materials (build SBOM).

[https://spdx.dev/learn/handling-license-info/ SPDX Id]: the official SPDX license Id.

[https://reuse.readthedocs.io/en/stable/man/reuse-spdx.html source SBOM]: the other type of Qt Software Bill of Materials.

[https://reuse.software/spec-3.2 reuse tool]: all you need to know about the reuse tool.

[https://reuse.software/spec-3.2/#reusetoml REUSE.toml]: the other way to document licensing.