licenserecon: Check licenses in debian/copyright file against licensecheck.

lrc parses a valid DEP-5 copyright file and notes the licenses of all files
in the source tree. Licensecheck is then run, and the results compared.
Differences between licenses and license versions in debian/copyright
and the output of licensecheck 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.
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 cannot determine a file's license. Files named copyright, copying,
readme etc. are not checked as they often specify the licenses of other files
rather than their own. Autogenerated Autotools' files are not checked,
as they do not need to be listed in debian/copyright,
and could otherwise appear as a difference.

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.

-f or --format
Formatted output.
Outputs the debian/copyright licence, licensecheck 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.

-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.

