.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Debbugs::Packages 3pm"
.TH Debbugs::Packages 3pm "2010-08-06" "perl v5.10.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"
Debbugs::Packages \- debbugs binary/source package handling
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Debbugs::Packages module provides support functions to map binary
packages to their corresponding source packages and vice versa. (This makes
sense for software distributions, where developers may work on a single
source package which produces several binary packages for use by users; it
may not make sense in other contexts.)
.SH "METHODS"
.IX Header "METHODS"
.SS "getpkgsrc"
.IX Subsection "getpkgsrc"
Returns a reference to a hash of binary package names to their corresponding
source package names.
.SS "getpkgcomponent"
.IX Subsection "getpkgcomponent"
Returns a reference to a hash of binary package names to the component of
the archive containing those binary packages (e.g. \*(L"main\*(R", \*(L"contrib\*(R",
\&\*(L"non-free\*(R").
.SS "getsrcpkgs"
.IX Subsection "getsrcpkgs"
Returns a list of the binary packages produced by a given source package.
.SS "binary_to_source"
.IX Subsection "binary_to_source"
.Vb 3
\&     binary_to_source(package => \*(Aqfoo\*(Aq,
\&                      version => \*(Aq1.2.3\*(Aq,
\&                      arch    => \*(Aqi386\*(Aq);
.Ve
.PP
Turn a binary package (at optional version in optional architecture)
into a single (or set) of source packages (optionally) with associated
versions.
.PP
By default, in \s-1LIST\s0 context, returns a \s-1LIST\s0 of array refs of source
package, source version pairs corresponding to the binary package(s),
arch(s), and verion(s) passed.
.PP
In \s-1SCALAR\s0 context, only the corresponding source packages are
returned, concatenated with ', ' if necessary.
.PP
If no source can be found, returns undef in scalar context, or the
empty list in list context.
.IP "binary \*(-- binary package name(s) as a \s-1SCALAR\s0 or \s-1ARRAYREF\s0" 4
.IX Item "binary  binary package name(s) as a SCALAR or ARRAYREF"
.PD 0
.IP "version \*(-- binary package version(s) as a \s-1SCALAR\s0 or \s-1ARRAYREF\s0; optional, defaults to all versions." 4
.IX Item "version  binary package version(s) as a SCALAR or ARRAYREF; optional, defaults to all versions."
.IP "arch \*(-- binary package architecture(s) as a \s-1SCALAR\s0 or \s-1ARRAYREF\s0; optional, defaults to all architectures." 4
.IX Item "arch  binary package architecture(s) as a SCALAR or ARRAYREF; optional, defaults to all architectures."
.IP "source_only \*(-- return only the source name (forced on if in \s-1SCALAR\s0 context), defaults to false." 4
.IX Item "source_only  return only the source name (forced on if in SCALAR context), defaults to false."
.IP "scalar_only \*(-- return a scalar only (forced true if in \s-1SCALAR\s0 context, also causes source_only to be true), defaults to false." 4
.IX Item "scalar_only  return a scalar only (forced true if in SCALAR context, also causes source_only to be true), defaults to false."
.IP "cache \*(-- optional \s-1HASHREF\s0 to be used to cache results of binary_to_source." 4
.IX Item "cache  optional HASHREF to be used to cache results of binary_to_source."
.PD
.SS "sourcetobinary"
.IX Subsection "sourcetobinary"
Returns a list of references to triplets of binary package names, versions,
and architectures corresponding to a given source package name and version.
If the given source package name and version cannot be found in the database
but the source package name is in the unversioned package-to-source map
file, then a reference to a binary package name and version pair will be
returned, without the architecture.
.SS "getversions"
.IX Subsection "getversions"
Returns versions of the package in a distribution at a specific
architecture
.SS "get_versions"
.IX Subsection "get_versions"
.Vb 4
\&     get_versions(package=>\*(Aqfoopkg\*(Aq,
\&                  dist => \*(Aqunstable\*(Aq,
\&                  arch => \*(Aqi386\*(Aq,
\&                 );
.Ve
.PP
Returns a list of the versions of package in the distributions and
architectures listed. This routine only returns unique values.
.IP "package \*(-- package to return list of versions" 4
.IX Item "package  package to return list of versions"
.PD 0
.IP "dist \*(-- distribution (unstable, stable, testing); can be an arrayref" 4
.IX Item "dist  distribution (unstable, stable, testing); can be an arrayref"
.IP "arch \*(-- architecture (i386, source, ...); can be an arrayref" 4
.IX Item "arch  architecture (i386, source, ...); can be an arrayref"
.IP "time \*(-- returns a version=>time hash at which the newest package matching this version was uploaded" 4
.IX Item "time  returns a version=>time hash at which the newest package matching this version was uploaded"
.IP "source \*(-- returns source/version instead of just versions" 4
.IX Item "source  returns source/version instead of just versions"
.IP "no_source_arch \*(-- discards the source architecture when arch is not passed. [Used for finding the versions of binary packages only.] Defaults to 0, which does not discard the source architecture. (This may change in the future, so if you care, please code accordingly.)" 4
.IX Item "no_source_arch  discards the source architecture when arch is not passed. [Used for finding the versions of binary packages only.] Defaults to 0, which does not discard the source architecture. (This may change in the future, so if you care, please code accordingly.)"
.IP "return_archs \*(-- returns a version=>[archs] hash indicating which architectures are at which versions." 4
.IX Item "return_archs  returns a version=>[archs] hash indicating which architectures are at which versions."
.IP "largest_source_version_only \*(-- if there is more than one source version in a particular distribution, discards all versions but the largest in that distribution. Defaults to 1, as this used to be the way that the Debian archive worked." 4
.IX Item "largest_source_version_only  if there is more than one source version in a particular distribution, discards all versions but the largest in that distribution. Defaults to 1, as this used to be the way that the Debian archive worked."
.PD
.PP
When called in scalar context, this function will return hashrefs or
arrayrefs as appropriate, in list context, it will return paired lists
or unpaired lists as appropriate.
.SS "makesourceversions"
.IX Subsection "makesourceversions"
.Vb 1
\&     @{$cgi_var{found}} = makesourceversions($cgi_var{package},undef,@{$cgi_var{found}});
.Ve
.PP
Canonicalize versions into source versions, which have an explicitly
named source package. This is used to cope with source packages whose
names have changed during their history, and with cases where source
version numbers differ from binary version numbers.
.SS "make_source_versions"
.IX Subsection "make_source_versions"
.Vb 7
\&     make_source_versions(package => \*(Aqfoo\*(Aq,
\&                          arch    => \*(Aqsource\*(Aq,
\&                          versions => \*(Aq0.1.1\*(Aq,
\&                          guess_source => 1,
\&                          debug    => \e$debug,
\&                          warnings => \e$warnings,
\&                         );
.Ve
.PP
An extended version of makesourceversions (which calls this function
internally) that allows for multiple packages, architectures, and
outputs warnings and debugging information to provided SCALARREFs or
HANDLEs.
.PP
The guess_source option determines whether the source package is
guessed at if there is no obviously correct package. Things that use
this function for non-transient output should set this to false,
things that use it for transient output can set this to true.
Currently it defaults to true, but that is not a sane option.