.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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 "Dpkg::Copyright::Scanner 3pm"
.TH Dpkg::Copyright::Scanner 3pm "2021-01-25" "perl v5.32.0" "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"
.Vb 1
\& Dpkg::Copyright::Scanner \- Scan files to provide copyright data
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Dpkg::Copyright::Scanner qw/print_copyright scan_files/;
\&
\& # print copyright data on STDOUT
\& print_copyright;
\&
\& # return a data structure containing copyright information
\& my @copyright_data = scan_files();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This modules scans current package directory to extract copyright and
license information. Information are packed in a way to ease review and
maintenance. Files information is grouped with wildcards ('*') to reduce
the list of files.
.SS "About \s-1LICENSE\s0 and \s-1README\s0 files"
.IX Subsection "About LICENSE and README files"
Projects often store global copyright information, i.e. information
that apply to all files of a project (unless specified otherwise in
some files) in \s-1README\s0 or \s-1LICENSE\s0 or \s-1COPYING\s0 file.
.PP
The information contained in these files id merged and applied to the
directory entry that contain them.
.PP
I.e files like:
.PP
.Vb 2
\& foo_comp/README: (c) 2018 Joe, GPL\-2
\& foo_comp/LICENSE: (c) 2017 Max, GPL\-3
.Ve
.PP
yield the following copyright entries:
.PP
.Vb 4
\& foo_comp/*:
\& Copyright: 2018 Joe
\&   2019 Max
\& License: GPL\-2 or GPL\-3
\&
\& README:
\& Copyright: 2018 Joe
\& License: GPL\-2
.Ve
.SH "Selecting or ignoring files to scan"
.IX Header "Selecting or ignoring files to scan"
By default, scanner scans source files with known suffixes (like .c
\&.pl ...), \s-1README,\s0 scripts and skip backup files.
.PP
If needed, this behavior can tuned with
\&\f(CW\*(C`debian/copyright\-scan\-patterns.yml\*(C'\fR file. This \s-1YAML\s0 file contains a
list of suffixes or patterns to scan or to ignore that are added to
the default list. Any file that is not scanned or ignored will be
shown as \*(L"skipped\*(R".
.PP
This file must have the following structure (all fields are optional
and order does not matter):
.PP
.Vb 10
\& \-\-\-
\& check :
\&   suffixes :
\&     \- PL       # check .PL$
\&     \- asm
\&   pattern:
\&     \- /README$
\& ignore :
\&   suffixes :
\&     \- yml
\&   pattern :
\&     \- /t/
\&     \- /models/
\&     \- /debian/
\&     \- /Changes
.Ve
.PP
Do not specify the dot with the suffixes. This will be added by the scanner.
.PP
Note that a file that match both \*(L"check\*(R" and \*(L"ignore\*(R" pattern is ignored.
.SH "Filling the blanks"
.IX Header "Filling the blanks"
Sometimes, upstream coders are not perfect: some source files cannot
be parsed correctly or some legal information is missing.
.PP
All scanned files, even without copyright or license will be used. A
warning will be shown for each file with missing information.
.PP
Instead of patching upstream source files to fill the blank, you can
specify the missing information in a special file. This file is
\&\f(CW\*(C`debian/fill.copyright.blanks.yml\*(C'\fR. It should contain a \*(L"mapping\*(R"
\&\s-1YAML\s0 structure (i.e. a hash), where the key is a Perl pattern used to
match a path.
.PP
If the source of the package contains a lot of files without legal
information, you may need to specify there information for a whole
directory (See the \f(CW\*(C`/src\*(C'\fR dir in the example below).
.PP
For instance:
.PP
.Vb 10
\& \-\-\-
\& debian:
\&   copyright: 2015, Marcel
\&   license: Expat
\& src/:
\&   copyright: 2016. Joe
\&   license: Expat
\& share/pkgs/openSUSE/systemd/onedsetup:
\&   copyright: 2015, Marcel
\& share/vendor/ruby/gems/rbvmomi/lib/rbvmomi.*\e.rb:
\&   license: Expat
\& .*/NOTICE:
\&   skip: 1
\& share/websockify/:
\&   license: LGPL\-2
\& src/sunstone/:
\&   license: Apache\-2.0
\& src/garbled/:
\&   \*(Aqoverride\-copyright\*(Aq: 2016 Marcel MeXzigue
.Ve
.PP
Patterns are matched from the beginning a
path. I.e. \f(CW\*(C`share/websockify/\*(C'\fR pattern will match
\&\f(CW\*(C`share/websockify/foo.rb\*(C'\fR but will not match
\&\f(CW\*(C`web/share/websockify/foo.rb\*(C'\fR.
.PP
Patterns are tried in reversed sorted order. I.e. the data attached to
more specific path (e.g. \f(CW\*(C`3rdparty/foo/blah.c\*(C'\fR) are applied before
more generic patterns (e.g. \f(CW\*(C`3rdparty/foo/\*(C'\fR
.PP
The \f(CW\*(C`license\*(C'\fR key must contain a license short name as returned by
\&\f(CW\*(C`license_check\*(C'\fR.
.PP
When \f(CW\*(C`skip\*(C'\fR is true, the file is skipped like a file without any
information.
.PP
The \f(CW\*(C`override\-copyright\*(C'\fR and \f(CW\*(C`override\-license\*(C'\fR keys can be used to
ignore the copyright information coming from the source and provide
the correct information. Use this as last resort for instance when the
encoding of the owner is not ascii or utf\-8 or when the license data
is corrupted. Note that a warning will be shown each time an override
key is used.
.SH "METHODS"
.IX Header "METHODS"
.SS "print_copyright"
.IX Subsection "print_copyright"
Print copyright information on \s-1STDOUT\s0 like scan-copyrights.
.ie n .SS "scan_files ( %args )"
.el .SS "scan_files ( \f(CW%args\fP )"
.IX Subsection "scan_files ( %args )"
Return a data structure with copyright and license information.
.PP
The structure is a list of list:
.PP
.Vb 8
\& [
\&   [
\&     [ path1 ,path2, ...],
\&     copyright,
\&     license_short_name
\&   ],
\&   ...
\& ]
.Ve
.PP
Example:
.PP
.Vb 10
\& [
\&  [
\&    [ \*(Aq*\*(Aq ],
\&    \*(Aq1994\-2001, by Frank Pilhofer.\*(Aq,
\&    \*(AqGPL\-2+\*(Aq
\&  ],
\&  [
\&    [ \*(Aqpan/*\*(Aq ],
\&    \*(Aq2002\-2006, Charles Kerr <charles@rebelbase.com>\*(Aq,
\&    \*(AqGPL\-2\*(Aq
\&  ],
\&  [
\&    [
\&      \*(Aqpan/data/parts.cc\*(Aq,
\&      \*(Aqpan/data/parts.h\*(Aq
\&    ],
\&    \*(Aq2002\-2007, Charles Kerr <charles@rebelbase.com>\*(Aq,
\&    \*(AqGPL\-2\*(Aq
\&  ],
\& ]
.Ve
.PP
Parameters in \f(CW%args\fR:
.IP "quiet" 4
.IX Item "quiet"
set to 1 to suppress progress messages. Should be used only in tests.
.SH "Encoding"
.IX Header "Encoding"
The output of licensecheck is expected to be utf\-8. Which means
that the source files scanned by licensecheck should also be
encoded in utf\-8. This program will abort if invalid utf\-8 characters
are found.
.SH "BUGS"
.IX Header "BUGS"
Extracting license and copyright data from unstructured comments is not reliable.
User must check manually the files when no copyright info is found or when the
license is unknown.
.PP
Source files are assumed to be utf8 (or ascii). Using files with invalid characters
will break \f(CW\*(C`cme\*(C'\fR. In this case, you can:
.IP "\(bu" 4
Patch source files to use utf\-8 encoding.
.IP "\(bu" 4
Use the \*(L"fill copyright blank\*(R" mechanism described above with
\&\f(CW\*(C`copyright\-override\*(C'\fR to provide an owner name with the correct
encoding.
.IP "\(bu" 4
File a bug against licensecheck package to find a better solution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
licensecheck, \f(CW\*(C`licensecheck2dep5\*(C'\fR from \f(CW\*(C`cdbs\*(C'\fR package
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont <dod@debian.org>