.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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 "Lintian::Collect::Source 3"
.TH Lintian::Collect::Source 3 "2019-05-26" "Lintian v2.15.0~bpo9+1" "Debian Package Checker"
.\" 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"
Lintian::Collect::Source \- Lintian interface to source package data collection
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    my ($name, $type, $dir) = (\*(Aqfoobar\*(Aq, \*(Aqsource\*(Aq, \*(Aq/path/to/lab\-entry\*(Aq);
\&    my $collect = Lintian::Collect\->new ($name, $type, $dir);
\&    if ($collect\->native) {
\&        print "Package is native\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lintian::Collect::Source provides an interface to package data for source
packages.  It implements data collection methods specific to source
packages.
.PP
This module is in its infancy.  Most of Lintian still reads all data from
files in the laboratory whenever that data is needed and generates that
data via collect scripts.  The goal is to eventually access all data about
source packages via this module so that the module can cache data where
appropriate and possibly retire collect scripts in favor of caching that
data in memory.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP "new (\s-1PACKAGE\s0)" 4
.IX Item "new (PACKAGE)"
Creates a new Lintian::Collect::Source object.  Currently, \s-1PACKAGE\s0 is
ignored.  Normally, this method should not be called directly, only via
the Lintian::Collect constructor.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
In addition to the instance methods listed below, all instance methods
documented in the Lintian::Collect and Lintian::Collect::Package
modules are also available.
.IP "changelog" 4
.IX Item "changelog"
Returns the changelog of the source package as a Parse::DebianChangelog
object, or \f(CW\*(C`undef\*(C'\fR if the changelog cannot be resolved safely.
.Sp
Needs-Info requirements for using \fIchangelog\fR: Same as index_resolved_path
.IP "diffstat" 4
.IX Item "diffstat"
Returns the path to diffstat output run on the Debian packaging diff
(a.k.a. the \*(L"diff.gz\*(R") for 1.0 non-native packages.  For source
packages without a \*(L"diff.gz\*(R" component, this returns the path to an
empty file (this may be a device like /dev/null).
.Sp
Needs-Info requirements for using \fIdiffstat\fR: diffstat
.IP "native" 4
.IX Item "native"
Returns true if the source package is native and false otherwise.
This is generally determined from the source format, though in the 1.0
case the nativeness is determined by looking for the diff.gz (using
the name of the source package and its version).
.Sp
If the source format is 1.0 and the version number is absent, this
will return false (as native packages are a lot rarer than non-native
ones).
.Sp
Note if the source format is missing, it is assumed to be a 1.0
package.
.Sp
Needs-Info requirements for using \fInative\fR: Same as field
.IP "files" 4
.IX Item "files"
Returns a reference to a hash containing information about files listed
in the .changes file.  Each hash may have the following keys:
.RS 4
.IP "name" 4
.IX Item "name"
Name of the file.
.IP "size" 4
.IX Item "size"
The size of the file in bytes.
.IP "checksums" 4
.IX Item "checksums"
A hash with the keys being checksum algorithms and the values themselves being
hashes containing
.RS 4
.IP "sum" 4
.IX Item "sum"
The result of applying the given algorithm to the file.
.IP "filesize" 4
.IX Item "filesize"
The size of the file as given in the .changes section relating to the given
checksum.
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
Needs-Info requirements for using \fIfiles\fR: \*(L"field ([FIELD[, \s-1DEFAULT\s0]])\*(R" in Lintian::Collect
.RE
.IP "repacked" 4
.IX Item "repacked"
Returns true if the source package has been \*(L"repacked\*(R" and false otherwise.
This is determined from the version name containing \*(L"dfsg\*(R" or similar.
.Sp
Needs-Info requirements for using \fIrepacked\fR: Same as field
.IP "binaries" 4
.IX Item "binaries"
Returns a list of the binary and udeb packages listed in the
\&\fIdebian/control\fR.  Package names appear the same order in the
returned list as they do in the control file.
.Sp
\&\fINote\fR: Package names that are not valid are silently ignored.
.Sp
Needs-Info requirements for using \fIbinaries\fR: Same as binary_package_type
.IP "binary_package_type (\s-1BINARY\s0)" 4
.IX Item "binary_package_type (BINARY)"
Returns package type based on value of the Package-Type (or if absent,
X\-Package-Type) field.  If the field is omitted, the default value
\&\*(L"deb\*(R" is used.
.Sp
If the \s-1BINARY\s0 is not a binary listed in the source packages
\&\fIdebian/control\fR file, this method return \f(CW\*(C`undef\*(C'\fR.
.Sp
Needs-Info requirements for using \fIbinary_package_type\fR: Same as binary_field
.IP "source_field([FIELD[, \s-1DEFAULT\s0]])" 4
.IX Item "source_field([FIELD[, DEFAULT]])"
Returns the content of the field \s-1FIELD\s0 from source package paragraph
of the \fIdebian/control\fR file, or \s-1DEFAULT \s0(defaulting to \f(CW\*(C`undef\*(C'\fR) if
the field is not present.  Only the literal value of the field is
returned.
.Sp
If \s-1FIELD\s0 is not given, return a hashref mapping field names to their
values (in this case \s-1DEFAULT\s0 is ignored).  This hashref should not be
modified.
.Sp
\&\s-1NB:\s0 If a field from the \*(L"dsc\*(R" file itself is desired, please use
field instead.
.Sp
Needs-Info requirements for using \fIsource_field\fR: Same as index_resolved_path
.IP "orig_index (\s-1FILE\s0)" 4
.IX Item "orig_index (FILE)"
Like \*(L"index\*(R" except orig_index is based on the \*(L"orig tarballs\*(R" of
the source packages.
.Sp
For native packages \*(L"index\*(R" and \*(L"orig_index\*(R" are generally
identical.
.Sp
\&\s-1NB:\s0 If sorted_index includes a debian packaging, it is was
contained in upstream part of the source package (or the package is
native).
.Sp
Needs-Info requirements for using \fIorig_index\fR: src-orig-index
.IP "sorted_orig_index" 4
.IX Item "sorted_orig_index"
Like sorted_index except
sorted_orig_index is based on the \*(L"orig tarballs\*(R" of the source
packages.
.Sp
For native packages sorted_index and
\&\*(L"sorted_orig_index\*(R" are generally identical.
.Sp
\&\s-1NB:\s0 If sorted_orig_index includes a debian packaging, it is was
contained in upstream part of the source package (or the package is
native).
.Sp
Needs-Info requirements for using \fIsorted_orig_index\fR: Same as orig_index
.IP "orig_index_resolved_path(\s-1PATH\s0)" 4
.IX Item "orig_index_resolved_path(PATH)"
Resolve \s-1PATH \s0(relative to the root of the package) and return the
entry denoting the resolved path.
.Sp
The resolution is done using
resolve_path.
.Sp
\&\s-1NB:\s0 If orig_index_resolved_path includes a debian packaging, it is was
contained in upstream part of the source package (or the package is
native).
.Sp
Needs-Info requirements for using \fIorig_index_resolved_path\fR: Same as orig_index
.IP "binary_field (PACKAGE[, FIELD[, \s-1DEFAULT\s0]])" 4
.IX Item "binary_field (PACKAGE[, FIELD[, DEFAULT]])"
Returns the content of the field \s-1FIELD\s0 for the binary package \s-1PACKAGE\s0
in the \fIdebian/control\fR file, or \s-1DEFAULT \s0(defaulting to \f(CW\*(C`undef\*(C'\fR) if
the field is not present.  Inheritance of field values from the source
section of the control file is not implemented.  Only the literal
value of the field is returned.
.Sp
If \s-1FIELD\s0 is not given, return a hashref mapping field names to their
values (in this case, \s-1DEFAULT\s0 is ignored).  This hashref should not be
modified.
.Sp
If \s-1PACKAGE\s0 is not a binary built from this source, this returns
\&\s-1DEFAULT.\s0
.Sp
Needs-Info requirements for using \fIbinary_field\fR: Same as index_resolved_path
.IP "java_info" 4
.IX Item "java_info"
Returns a hashref containing information about \s-1JAR\s0 files found in
source packages, in the form \fIfile name\fR \-> \fIinfo\fR, where \fIinfo\fR is
a hash containing the following keys:
.RS 4
.IP "manifest" 4
.IX Item "manifest"
A hash containing the contents of the \s-1JAR\s0 file manifest. For instance,
to find the classpath of \fI\f(CI$file\fI\fR, you could use:
.Sp
.Vb 4
\& if (exists $info\->java_info\->{$file}{\*(Aqmanifest\*(Aq}) {
\&     my $cp = $info\->java_info\->{$file}{\*(Aqmanifest\*(Aq}{\*(AqClass\-Path\*(Aq};
\&     # ...
\& }
.Ve
.Sp
\&\s-1NB:\s0 Not all jar files have a manifest.  For those without, this will
value will not be available.  Use exists (rather than defined) to
check for it.
.IP "files" 4
.IX Item "files"
A table of the files in the \s-1JAR. \s0 Each key is a file name and its value
is its \*(L"Major class version\*(R" for Java or \*(L"\-\*(R" if it is not a class file.
.IP "error" 4
.IX Item "error"
If it exists, this is an error that occurred during reading of the zip
file.  If it exists, it is unlikely that the other fields will be
present.
.RE
.RS 4
.Sp
Needs-Info requirements for using \fIjava_info\fR: java-info
.RE
.IP "binary_relation (\s-1PACKAGE, FIELD\s0)" 4
.IX Item "binary_relation (PACKAGE, FIELD)"
Returns a Lintian::Relation object for the specified \s-1FIELD\s0 in the
binary package \s-1PACKAGE\s0 in the \fIdebian/control\fR file.  \s-1FIELD\s0 should be
one of the possible relationship fields of a Debian package or one of
the following special values:
.RS 4
.IP "all" 4
.IX Item "all"
The concatenation of Pre-Depends, Depends, Recommends, and Suggests.
.IP "strong" 4
.IX Item "strong"
The concatenation of Pre-Depends and Depends.
.IP "weak" 4
.IX Item "weak"
The concatenation of Recommends and Suggests.
.RE
.RS 4
.Sp
If \s-1FIELD\s0 isn't present in the package, the returned Lintian::Relation
object will be empty (always satisfied and implies nothing).
.Sp
Any substvars in \fIdebian/control\fR will be represented in the returned
relation as packages named after the substvar.
.Sp
Needs-Info requirements for using \fIbinary_relation\fR: Same as binary_field
.RE
.IP "relation (\s-1FIELD\s0)" 4
.IX Item "relation (FIELD)"
Returns a Lintian::Relation object for the given build relationship
field \s-1FIELD. \s0 In addition to the normal build relationship fields, the
following special field names are supported:
.RS 4
.IP "build-depends-all" 4
.IX Item "build-depends-all"
The concatenation of Build-Depends, Build-Depends-Arch and
Build-Depends-Indep.
.IP "build-conflicts-all" 4
.IX Item "build-conflicts-all"
The concatenation of Build-Conflicts, Build-Conflicts-Arch and
Build-Conflicts-Indep.
.RE
.RS 4
.Sp
If \s-1FIELD\s0 isn't present in the package, the returned Lintian::Relation
object will be empty (always satisfied and implies nothing).
.Sp
Needs-Info requirements for using \fIrelation\fR: Same as field
.RE
.IP "relation_noarch (\s-1FIELD\s0)" 4
.IX Item "relation_noarch (FIELD)"
The same as \*(L"relation (\s-1FIELD\s0)\*(R", but ignores architecture
restrictions and build profile restrictions in the \s-1FIELD\s0 field.
.Sp
Needs-Info requirements for using \fIrelation_noarch\fR: Same as relation
.IP "debfiles ([\s-1FILE\s0])" 4
.IX Item "debfiles ([FILE])"
\&\fBThis method is deprecated\fR.  Consider using
index_resolved_path(\s-1PATH\s0)
instead, which returns Lintian::Path objects.
.Sp
Returns the path to \s-1FILE\s0 in the debian dir of the extracted source
package.  \s-1FILE\s0 must be relative to the root of the debian dir and
should be without leading slash (and without \*(L"./\*(R").  If \s-1FILE\s0 is
not in the debian dir, it returns the path to a non-existent file
entry.
.Sp
It is not permitted for \s-1FILE\s0 to be \f(CW\*(C`undef\*(C'\fR.  If the \*(L"root\*(R" dir is
desired either invoke this method without any arguments at all or use
the empty string.
.Sp
The caveats of unpacked
also apply to this method.
.Sp
Needs-Info requirements for using \fIdebfiles\fR: debfiles
.IP "index (\s-1FILE\s0)" 4
.IX Item "index (FILE)"
For the general documentation of this method, please refer to the
documentation of it in
Lintian::Collect::Package.
.Sp
The index of a source package is not very well defined for non-native
source packages.  This method gives the index of the \*(L"unpacked\*(R"
package (with 3.0 (quilt), this implies patches have been applied).
.Sp
If you want the index of what is listed in the upstream orig tarballs,
then there is \*(L"orig_index\*(R".
.Sp
For native packages, the two indices are generally the same as they
only have one tarball and their debian packaging is included in that
tarball.
.Sp
\&\s-1IMPLEMENTATION DETAIL/CAVEAT:\s0 Lintian currently (2.5.11) generates
this by running \*(L"\fIfind\fR\|(1)\*(R" after unpacking the source package.
This has three consequences.
.Sp
First it means that (original) owner/group data is lost; Lintian
inserts \*(L"root/root\*(R" here.  This is usually not a problem as
owner/group information for source packages do not really follow any
standards.
.Sp
Secondly, permissions are modified by A) umask and B) laboratory
set{g,u}id bits (the laboratory on lintian.d.o has setgid).  This is
*not* corrected/altered.  Note Lintian (usually) breaks if any of the
\&\*(L"user\*(R" bits are set in the umask, so that part of the permission bit
\&\fIshould\fR be reliable.
.Sp
Again, this shouldn't be a problem as permissions in source packages
are usually not important.  Though if accuracy is needed here,
\&\*(L"orig_index\*(R" may used instead (assuming it has the file in
question).
.Sp
Third, hardlinking information is lost and no attempt has been made
to restore it.
.Sp
Needs-Info requirements for using \fIindex\fR: unpacked
.IP "is_non_free" 4
.IX Item "is_non_free"
Returns a truth value if the package appears to be non-free (based on
the section field; \*(L"non\-free/*\*(R" and \*(L"restricted/*\*(R")
.Sp
Needs-Info requirements for using \fIis_non_free\fR: \*(L"source_field ([FIELD[, \s-1DEFAULT\s0]])\*(R"
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Russ Allbery <rra@debian.org> for Lintian.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIlintian\fR\|(1), \fILintian::Collect\fR\|(3), \fILintian::Relation\fR\|(3)