.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "LICENSE-RECONCILE 1p" .TH LICENSE-RECONCILE 1p "2014-06-29" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" license\-reconcile \- reconcile debian/copyright against source .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBlicense-reconcile\fR \fB\-\-help\fR|\fB\-\-man\fR .PP \&\fBlicense-reconcile\fR [\fB\-\-copyright\-file=\fR\fIfile\fR] [\fB\-\-no\-check\-copyright\fR] [\fB\-\-no\-format\-spec\fR] [\fB\-\-quiet\fR] [\fB\-\-display\-mapping\fR] [\fB\-\-directory=\fR\fIdirectory\fR] [\fB\-\-filters=\fR\fImodule1 module2 ...\fR] [\fB\-\-config\-file=\fR\fIfile\fR] [\fB\-\-changelog\-file=\fR\fIfile\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBlicense-reconcile\fR attempts to match license and copyright information in a directory with the information available in \f(CW\*(C`debian/copyright\*(C'\fR. It gets most of its data from \f(CW\*(C`licensecheck\*(C'\fR 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: .IP "\- Does the copyright file have an approved format specification as its first line?" 4 .IX Item "- Does the copyright file have an approved format specification as its first line?" .PD 0 .IP "\- Can the copyright file be parsed?" 4 .IX Item "- Can the copyright file be parsed?" .IP "\- Does every file in the source match at least one clause in the copyright file?" 4 .IX Item "- Does every file in the source match at least one clause in the copyright file?" .ie n .IP "\- 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." 4 .el .IP "\- 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." 4 .IX Item "- 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." .ie n .IP "\- Is every file in the source assigned copyright and a license by some part of the ""debian/copyright"" file." 4 .el .IP "\- Is every file in the source assigned copyright and a license by some part of the \f(CWdebian/copyright\fR file." 4 .IX Item "- Is every file in the source assigned copyright and a license by some part of the debian/copyright file." .PD .SH "GETTING STARTED" .IX Header "GETTING STARTED" .SS "out of the box" .IX Subsection "out of the box" From the top level of the source directory of Debian packaged software, just run \f(CW\*(C`license\-reconcile\*(C'\fR. .SS "setting a config file" .IX Subsection "setting a config file" Normally to make any progress it will be necessary to have a config file. The default file is \f(CW\*(C`debian/license\-reconcile.yml\*(C'\fR. A different config file can be set with the \fB\-\-config\-file=\fR\fIfile\fR. The config file is interpreted using Config::Any but for the purposes of this documentation# we assume the format is \s-1YAML\s0. .SS "overriding incorrect results" .IX Subsection "overriding incorrect results" Suppose you are really lucky. For just one file, \f(CW\*(C`a/b\*(C'\fR, the default filters which are wrappers around \f(CW\*(C`licensecheck\*(C'\fR, have got it wrong. They have for some reason decided that the file has a \s-1GPL\-3\s0 license, when inspection shows it is in the public domain. This is causing a false positive break against your carefully crafted \f(CW\*(C`debian/copyright\*(C'\fR file. You can fix this with the following config fragment: .PP .Vb 6 \& Rules: \& rules: \& \- \& Glob: a/b \& License: public\-domain \& Copyright: 1556, Nostrodamus .Ve .PP See Debian::LicenseReconcile::Filter::Rules for more information on how to configure this filter. .SS "providing a catch all license and copyright" .IX Subsection "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: .PP .Vb 5 \& Default: \& rules: \& \- \& License: All software is property of the proletariat license \& Copyright: 1984, Ministry of Algorithms .Ve .PP 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. .SS "controlling the sequence of filters." .IX Subsection "controlling the sequence of filters." By default the filters run are: Rules, Std, Shebang, ChangeLog and Default. You can vary the filters using the \fB\-\-filters=\fR\fImodule\fR option. Setting \&\f(CW\*(C`\-\-filters Rules\*(C'\fR would mean that only the Debian::LicenseReconcile::Filter::Rules filter would be used. Once you specify one filter you must specify them all. .SS "filter aliasing" .IX Subsection "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 \*(L"Default~Rules\*(R". In general \&\*(L"X~Y\*(R" means use the code from Y but get the config from X. .SS "writing your own filter." .IX Subsection "writing your own filter." You can write your own filters by inheriting from Debian::LicenseReconcile::Filter. You need to define the \f(CW\*(C`get_info\*(C'\fR method. .SH "OPTIONS" .IX Header "OPTIONS" .SS "\fB\-\-copyright\-file=\fP\fIfile\fP" .IX Subsection "--copyright-file=file" Specify an alternative copyright file. Defaults to \f(CW\*(C`debian/copyright\*(C'\fR. .SS "\fB\-\-no\-format\-spec\fP" .IX Subsection "--no-format-spec" Don't check the first line of the copyright file against permitted format specifications. .SS "\fB\-\-no\-check\-copyright\fP" .IX Subsection "--no-check-copyright" Don't check the copyright clauses. .SS "\fB\-\-quiet\fP" .IX Subsection "--quiet" Don't give any explanations, simply a success or a fail via the exit status. .SS "\fB\-\-display\-mapping\fP" .IX Subsection "--display-mapping" Display mapping from the directory onto the copyright clauses. .SS "\fB\-\-directory=\fP\fIdirectory\fP" .IX Subsection "--directory=directory" The directory whose copyright and licenses will be verified. This defaults to \*(L".\*(R". .SS "\fB\-\-filters=\fP\fImodule1\fP \fB\-\-filters=\fP\fImodule2\fP ...." .IX Subsection "--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 \*(L"Rules Std Shebang ChangeLog Default\*(R". .SS "\fB\-\-config\-file=\fP\fIfile\fP" .IX Subsection "--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 \f(CW\*(C`config\*(C'\fR parameter. .SS "<\-\-changelog\-file=>\fIfile\fP" .IX Subsection "<--changelog-file=>file" The Debian changelog file which defaults to \f(CW\*(C`debian/changelog\*(C'\fR. The Rules filter uses this to get the current version and the ChangeLog filter gets its data from it. .SH "Filters" .IX Header "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. .IP "\- Rules" 4 .IX Item "- Rules" .PD 0 .IP "\- Std" 4 .IX Item "- Std" .IP "\- Shebang" 4 .IX Item "- Shebang" .IP "\- ChangeLog" 4 .IX Item "- ChangeLog" .IP "\- Default" 4 .IX Item "- Default" .PD .PP Each filter constructor will be passed the following parameters: .IP "\- directory \- the directory from which to find license and copyright data." 4 .IX Item "- directory - the directory from which to find license and copyright data." .PD 0 .IP "\- files_remaining \- an array ref of files which have not been analyzed." 4 .IX Item "- files_remaining - an array ref of files which have not been analyzed." .IP "\- config \- a data structure representing the portion of the config file relevant to this filter." 4 .IX Item "- config - a data structure representing the portion of the config file relevant to this filter." .IP "\- changelog \- a Parse::DebianChangelog object." 4 .IX Item "- changelog - a Parse::DebianChangelog object." .IP "\- licensecheck \- a Debian::LicenseReconcile::LicenseCheck object." 4 .IX Item "- licensecheck - a Debian::LicenseReconcile::LicenseCheck object." .PD .SH "LIMITATIONS" .IX Header "LIMITATIONS" The \s-1DEP\-5\s0 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 \f(CW\*(C`debian/copyright\*(C'\fR is unlikely to work correctly. .PP 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. .SH "AUTHOR" .IX Header "AUTHOR" Nicholas Bamber, \f(CW\*(C`\*(C'\fR .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2012 Nicholas Bamber. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See http://dev.perl.org/licenses/ for more information.