--- name: "license-reconcile" section: "1p" platform: "linux" package: "license-reconcile" version: "0.16" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/license-reconcile" --- # license-reconcile(1p) reconcile debian/copyright against source ## NAME license-reconcile - reconcile debian/copyright against source ## SYNOPSIS **license-reconcile** **--help**\|**--man** **license-reconcile** \[**--copyright-file=***file*\] \[**--no-check-copyright**\] \[**--suggest-stanzas**\] \[**--no-format-spec**\] \[**--quiet**\] \[**--display-mapping**\] \[**--directory=***directory*\] \[**--filters=***module1 module2 ...*\] \[**--config-file=***file*\] \[**--changelog-file=***file*\] \[*files...*\] ## DESCRIPTION **license-reconcile** attempts to match license and copyright information in a directory with the information available in `"debian/copyright"`. It gets most of its data from `"licensecheck"` so should produce something worth looking at out of the box. However for a given package it can be configured to succeed in a known good state, so that if on subsequent upstream updates it fails, it points out what needs looking at. By default the tests run are as follows: - \- Does the copyright file have an approved format specification as its first line? - \- Can the copyright file be parsed? - \- Does every file in the source match at least one clause in the copyright file? - \- Can every file, license and copyright datum extracted from the source be contained in the corresponding matching paragraph from the copyright file? The data for this comparison comes from a number filter objects. See "Filters" for more information. - \- Is every file in the source assigned copyright and a license by some part of the "debian/copyright" file. ## GETTING STARTED ### out of the box From the top level of the source directory of Debian packaged software, just run `"license-reconcile"`. ### setting a config file Normally to make any progress it will be necessary to have a config file. The default file is `"debian/license-reconcile.yml"`. A different config file can be set with the **--config-file=***file*. The config file is interpreted using Config::Any but for the purposes of this documentation# we assume the format is YAML. ### overriding incorrect results Suppose you are really lucky. For just one file, `"a/b"`, the default filters which are wrappers around `"licensecheck"`, have got it wrong. They have for some reason decided that the file has a GPL-3 license, when inspection shows it is in the public domain. This is causing a false positive break against your carefully crafted `"debian/copyright"` file. You can fix this with the following config fragment: ``` Rules: rules: - Glob: a/b License: public-domain Copyright: 1556, Nostrodamus ``` See Debian::LicenseReconcile::Filter::Rules for more information on how to configure this filter. ### providing a catch all license and copyright You can make the filters provide a default license, but providing a suitable rule in the Default section of the config file: ``` Default: rules: - License: All software is property of the proletariat license Copyright: 1984, Ministry of Algorithms ``` The Default filter uses exactly the same code as the Rules filter, but by default runs last. So it has all the same functionality but the lowest precedence. ### controlling the sequence of filters. By default the filters run are: Rules, Std, Shebang, ChangeLog and Default. You can vary the filters using the **--filters=***module* option. Setting `"--filters Rules"` would mean that only the Debian::LicenseReconcile::Filter::Rules filter would be used. Once you specify one filter you must specify them all. ### filter aliasing The Default filter is an alias for Rules. This means it runs the same code but has a separate config. Default is defined as "Default~Rules". In general "X~Y" means use the code from Y but get the config from X. ### writing your own filter. You can write your own filters by inheriting from Debian::LicenseReconcile::Filter. You need to define the `"get_info"` method. ## OPTIONS ### --copyright-file=*file* Specify an alternative copyright file. Defaults to `"debian/copyright"`. ### --no-format-spec Don't check the first line of the copyright file against permitted format specifications. ### --no-check-copyright Don't check the copyright clauses. ### --quiet Don't give any explanations, simply a success or a fail via the exit status. ### --display-mapping Display mapping from the directory onto the copyright clauses. ### --directory=*directory* The directory whose copyright and licenses will be verified. This defaults to ".". ### --filters=*module1* --filters=*module2* .... A sequence of filters which will inspect the source package and return license and copyright information. Each module name must sit below the Debian::LicenseReconcile::Filter and inherit from it. The default value is "Rules Std Shebang ChangeLog Default". ### --config-file=*file* A file used to provide filter specific configuration data. The file is read by Config::Any and the relevant section is passed to each filter constructor via the `"config"` parameter. ### \<--changelog-file=\>*file* The Debian changelog file which defaults to `"debian/changelog"`. The Rules filter uses this to get the current version and the ChangeLog filter gets its data from it. ### --suggest-stanzas If set print out the license and copyright data in DEP-5 format. ## Filters By default the filters are processed in the order below. Once a file has been returned by a filter, subsequent filters will ignore it. - \- Rules - \- ChangeLog - \- Std - \- Shebang - \- Default Each filter constructor will be passed the following parameters: - \- directory - the directory from which to find license and copyright data. - \- files\_remaining - an array ref of files which have not been analyzed. - \- config - a data structure representing the portion of the config file relevant to this filter. - \- changelog - a Parse::DebianChangelog object. - \- licensecheck - a Debian::LicenseReconcile::LicenseCheck object. ## FILE ARGUMENTS Any arguments after the arguments are assumed to be files. If specified only these files will be reconciled. ## LIMITATIONS The DEP-5 specification is subtly different from the file glob specification. Since the File::FnMatch module is the only practical implementation there is little that can be done. The consequence is that attempting to specify that a file name should contain '\[' and later a '\]' in `"debian/copyright"` is unlikely to work correctly. In copyright parsing years cannot be expressed in an abbreviated two digit form. This is probably a good thing, but it it will surely cause an issue at some point. ## EXAMPLES Two Debian projects are currently using license-reconcile, to verify the `"debian/copyright"` file. - **license-reconcile\|https://anonscm.debian.org/cgit/pkg-perl/packages/license-reconcile.git/tree/debian/license-reconcile.yml** must obviously be clean by its own standards. At some point this check will be added to the build tests. - **ksh\|http://anonscm.debian.org/cgit/collab-maint/ksh.git/tree/debian/license-reconcile.yml** is using license-reconcile since version 93u+20120801-2. ## AUTHOR Nicholas Bamber, `""` ## LICENSE AND COPYRIGHT Copyright 2012, 2015, Nicholas Bamber. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.