licenserecon: Check licenses in debian/copyright against licensecheck or grep.

lrc parses a valid DEP-5 copyright file and notes the licenses of all files
in the source tree. Licensecheck or grep is then run, and the results compared.
Differences between licenses and license versions in debian/copyright
and the file's license are reported.

It should be run in the top level of a cleaned Debian source tree,
with a valid DEP-5 copyright file. The source tree should be clean,
otherwise results may be contaminated by spurious reports on the build's
generated files. It is advisable to run lintian first to ensure correct syntax
of debian/copyright.

The results are indicative only, and not a substitute for manual checking.
It is intended to report obvious errors. The design intends to minimise false
positives as much as is practical. However, false positives will occur if the
spelling of the license short-string is not identical between the file and
debian/copyright. This is quite likely with complex licensing such as
'and'/'or' constructs and specific exceptions.

False positives may suppressed by creating a file debian/lrc.config
List in the file, the file names and/or directories to be excluded.
Also, license aliases can be added.
The syntax for the file is described in /usr/share/lrc/lrc.config

Command line options to be used on every run (maybe --spdx etc with Salsa CI)
can be included in debian/lrc.config

Only files with a copyright header are checked.
False negatives may occur if licensecheck reports a file's license
as 'UNKNOWN', or if grep cannot find a valid SPDX identifier.
Files named copyright, copying, readme etc. are not checked as they often
specify the licenses of other files rather than their own.

EXIT CODES
    0: No differences found
    1: Failure to run (no valid debian/copyright)
    3: License differences found

SAMPLE OUTPUT
    Sample output invoking lrc.

    SUCCESS:
        Parsing Source Tree  ....
        Reading copyright    ....
        Running licensecheck ....

        No differences found

    DIFFERENCES:
        Parsing Source Tree  ....
        Reading copyright    ....
        Running licensecheck ....

        debian/copyright| licensecheck

        LGPL-2.1+       | GPL-2+       test/src/config/chan.c
        GPL-2+          | public-domain share/lua/int/dummy.lua
        GPL-2+          | LGPL-2.1+    modules/access/sr_common.h

OPTIONS
Options are case-insensitive. Invalid options are ignored.

-? -h or --help
Writes this readme file to stdout.

-l or --long
Output is generated for every file where licensecheck detects the license,
not just those with license discrepancies.
Can be used without a copyright file.

-f or --format
Formatted output.
Outputs the debian/copyright licence, file license, and filename
on three separate lines, followed by one blank line.
Headers and summary lines are suppressed. Version info is not output
unless specified via -v option.

-g or --grep Grep for SPDX.
Greps the source files for the SPDX Identifier string,
instead of using licensecheck. (Much faster)

-s or --short
Where blocks of files with identical license differences would be output,
only the first file is shown. Overrides -l (if specified)

-v or --version
Writes the version numbers of licenserecon and licenscheck to stdout, then exits

-x or --spdx
Expects SPDX style license short names. (Default is debian DEP 5 short names)

SALSA CI PIPELINE
lrc can be included in Salsa CI Pipelines by using
 debian/salsa-ci.yml@debian/licenserecon
as the CI/CD configuration file.

