1 files changed, 510 insertions, 0 deletions
diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod
new file mode 100644
index 0000000..ea9999d
--- /dev/null
+++ b/man/deb-src-control.pod
@@ -0,0 +1,510 @@
+# dpkg manual page - deb-src-control(5)
+#
+# Copyright © 2010 Oxan van Leeuwen <oxan@oxanvanleeuwen.nl>
+# Copyright © 2011 Raphaël Hertzog <hertzog@debian.org>
+# Copyright © 2011-2015 Guillem Jover <guillem@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+deb-src-control - Debian source packages' master control file format
+
+=head1 SYNOPSIS
+
+B<debian/control>
+
+=head1 DESCRIPTION
+
+Each Debian source package contains the master «B<debian/control>» file,
+and its L<deb822(5)> format is a superset of the B<control> file
+shipped in Debian binary packages, see B<deb-control>(5).
+
+This file contains at least 2 stanzas, separated by a blank line.
+The first stanza lists all information about the source package in general,
+while each following stanza describes exactly one binary package.
+Each stanza consists of at least one field.
+A field starts with a fieldname, such as B<Package> or B<Section>
+(case insensitive), followed by a colon, the body of the field
+(case sensitive unless stated otherwise) and a newline.
+Multi-line fields are also allowed, but each supplementary line, without a
+fieldname, should start with at least one space. The content of the multi-line
+fields is generally joined to a single line by the tools (except in the case of
+the
+B<Description>
+field, see below). To insert empty lines into a multi-line
+field, insert a dot after the space.
+Lines starting with a ‘B<#>’ are treated as comments.
+
+=head1 SOURCE FIELDS
+
+=over
+
+=item B<Source:> I<source-package-name> (required)
+
+The value of this field is the name of the source package, and should
+match the name of the source package in the debian/changelog file. A package
+name must consist only of lowercase letters (a-z), digits (0-9), plus (+) and
+minus (-) signs, and periods (.). Package names must be at least two characters
+long and must start with a lowercase alphanumeric character (a-z0-9).
+
+=item B<Maintainer:> I<fullname-email> (recommended)
+
+Should be in the format «Joe Bloggs E<lt>jbloggs@foo.comE<gt>», and references the
+person who currently maintains the package, as opposed to the author of the
+software or the original packager.
+
+=item B<Uploaders:> I<fullname-email>
+
+Lists all the names and email addresses of co-maintainers of the package, in
+the same format as the B<Maintainer> field.
+Multiple co-maintainers should be separated by a comma.
+
+=item B<Standards-Version:> I<version-string>
+
+This documents the most recent version of the distribution policy standards
+this package complies with.
+
+=item B<Description> I<short-description>
+
+=item S< >I<long-description>
+
+The format for the source package description is a short brief summary on the
+first line (after the B<Description> field).
+The following lines should be used as a longer, more detailed description.
+Each line of the long description must be preceded by a space, and blank
+lines in the long description must contain a single ‘B<.>’ following
+the preceding space.
+
+=item B<Homepage:> I<url>
+
+The upstream project home page URL.
+
+=item B<Bugs:> I<url>
+
+The I<url> of the bug tracking system for this package. The current
+used format is I<bts-type>B<://>I<bts-address>, like
+B<debbugs://bugs.debian.org>. This field is usually not needed.
+
+=item B<Rules-Requires-Root:> B<no>|B<binary-targets>|I<impl-keywords>
+
+This field is used to indicate whether the B<debian/rules> file requires
+(fake)root privileges to run some of its targets, and if so when.
+
+=over
+
+=item B<no>
+
+The binary targets will not require (fake)root at all.
+
+=item B<binary-targets>
+
+The binary targets must always be run under (fake)root.
+This value is the default when the field is omitted; adding the field
+with an explicit B<binary-targets> while not strictly needed, marks
+it as having been analyzed for this requirement.
+
+=item I<impl-keywords>
+
+This is a space-separated list of keywords which define when (fake)root
+is required.
+
+Keywords consist of I<namespace>/I<cases>.
+The I<namespace> part cannot contain "/" or whitespace.
+The I<cases> part cannot contain whitespace.
+Furthermore, both parts must consist entirely of printable ASCII characters.
+
+Each tool/package will define a namespace named after itself and provide
+a number of cases where (fake)root is required.
+(See "Implementation provided keywords" in I<rootless-builds.txt>).
+
+When the field is set to one of the I<impl-keywords>, the builder will
+expose an interface that is used to run a command under (fake)root.
+(See "Gain Root API" in I<rootless-builds.txt>.)
+
+=back
+
+=item B<Testsuite:> I<name-list>
+
+=item B<Testsuite-Triggers:> I<package-list>
+
+These fields are described in the
+B<dsc>(5)
+manual page, as they are generated from information inferred from
+B<debian/tests/control> or copied literally to the source control file.
+
+=item B<Vcs-Arch:> I<url>
+
+=item B<Vcs-Bzr:> I<url>
+
+=item B<Vcs-Cvs:> I<url>
+
+=item B<Vcs-Darcs:> I<url>
+
+=item B<Vcs-Git:> I<url>
+
+=item B<Vcs-Hg:> I<url>
+
+=item B<Vcs-Mtn:> I<url>
+
+=item B<Vcs-Svn:> I<url>
+
+The I<url> of the Version Control System repository used to maintain this
+package. Currently supported are B<Arch>, B<Bzr> (Bazaar), B<Cvs>,
+B<Darcs>, B<Git>, B<Hg> (Mercurial), B<Mtn> (Monotone) and
+B<Svn> (Subversion). Usually this field points to the latest version
+of the package, such as the main branch or the trunk.
+
+=item B<Vcs-Browser:> I<url>
+
+The I<url> of a webinterface to browse the Version Control System
+repository.
+
+=item B<Origin:> I<name>
+
+The name of the distribution this package is originating from. This field is
+usually not needed.
+
+=item B<Section:> I<section>
+
+This is a general field that gives the package a category based on the
+software that it installs.
+Some common sections are B<utils>, B<net>, B<mail>, B<text>,
+B<x11>, etc.
+
+=item B<Priority:> I<priority>
+
+Sets the importance of this package in relation to the system as a whole.
+Common priorities are B<required>, B<standard>, B<optional>,
+B<extra>, etc.
+
+The
+B<Section>
+and
+B<Priority>
+fields usually have a defined set of accepted values based on the specific
+distribution policy.
+
+=item B<Build-Depends:> I<package-list>
+
+A list of packages that need to be installed and configured to be able
+to build from source package.
+These dependencies need to be satisfied when building binary architecture
+dependent or independent packages and source packages.
+Including a dependency in this field does not have the exact same effect as
+including it in both B<Build-Depends-Arch> and B<Build-Depends-Indep>,
+because the dependency also needs to be satisfied when building the source
+package.
+
+=item B<Build-Depends-Arch:> I<package-list>
+
+Same as B<Build-Depends>, but they are only needed when building the
+architecture dependent packages. The B<Build-Depends> are also
+installed in this case. This field is supported since dpkg 1.16.4; in
+order to build with older dpkg versions, B<Build-Depends>
+should be used instead.
+
+=item B<Build-Depends-Indep:> I<package-list>
+
+Same as B<Build-Depends>, but they are only needed when building the
+architecture independent packages. The B<Build-Depends> are also
+installed in this case.
+
+=item B<Build-Conflicts:> I<package-list>
+
+A list of packages that should not be installed when the package is
+built, for example because they interfere with the build system used.
+Including a dependency in this list has the same effect as including
+it in both B<Build-Conflicts-Arch> and
+B<Build-Conflicts-Indep>, with the additional effect of being
+used for source-only builds.
+
+=item B<Build-Conflicts-Arch:> I<package-list>
+
+Same as B<Build-Conflicts>, but only when building the architecture
+dependent packages. This field is supported since dpkg 1.16.4; in
+order to build with older dpkg versions, B<Build-Conflicts> should
+be used instead.
+
+=item B<Build-Conflicts-Indep:> I<package-list>
+
+Same as B<Build-Conflicts>, but only when building the architecture
+independent packages.
+
+=back
+
+The syntax of the
+B<Build-Depends>,
+B<Build-Depends-Arch>
+and
+B<Build-Depends-Indep>
+fields is a list of groups of alternative packages.
+Each group is a list of packages separated by vertical bar (or “pipe”)
+symbols, ‘B<|>’.
+The groups are separated by commas ‘B<,>’, and can end with a
+trailing comma that will be eliminated when generating the fields
+for B<deb-control>(5) (since dpkg 1.10.14).
+Commas are to be read as “AND”, and pipes as “OR”, with pipes
+binding more tightly.
+Each package name is optionally followed by an architecture qualifier
+appended after a colon ‘B<:>’,
+optionally followed by a version number specification in parentheses
+‘B<(>’ and ‘B<)>’, an
+architecture specification in square brackets ‘B<[>’ and ‘B<]>’,
+and a restriction formula
+consisting of one or more lists of profile names in angle brackets
+‘B<E<lt>>’ and ‘B<E<gt>>’.
+
+The syntax of the
+B<Build-Conflicts>,
+B<Build-Conflicts-Arch>
+and
+B<Build-Conflicts-Indep>
+fields is a list of comma-separated package names, where the comma is read
+as an “AND”, and where the list can end with a trailing comma that will
+be eliminated when generating the fields for B<deb-control>(5)
+(since dpkg 1.10.14).
+Specifying alternative packages using a “pipe” is not supported.
+Each package name is optionally followed by a version number specification in
+parentheses, an architecture specification in square brackets, and a
+restriction formula consisting of one or more lists of profile names in
+angle brackets.
+
+An architecture qualifier name can be a real Debian architecture name
+(since dpkg 1.16.5), B<any> (since dpkg 1.16.2) or B<native>
+(since dpkg 1.16.5).
+If omitted, the default for B<Build-Depends> fields is the current host
+architecture, the default for B<Build-Conflicts> fields is B<any>.
+A real Debian architecture name will match exactly that architecture for
+that package name, B<any> will match any architecture for that package
+name if the package is marked with B<Multi-Arch: allowed>, and
+B<native> will match the current build architecture if the package
+is not marked with B<Multi-Arch: foreign>.
+
+A version number may start with a ‘B<E<gt>E<gt>>’, in which case any
+later version will match, and may specify or omit the Debian packaging
+revision (separated by a hyphen).
+Accepted version relationships are ‘B<E<gt>E<gt>>’ for greater than,
+‘B<E<lt>E<lt>>’ for less than, ‘B<E<gt>=>’ for greater than or
+equal to, ‘B<E<lt>=>’ for less than or equal to, and ‘B<=>’
+for equal to.
+
+An architecture specification consists of one or more architecture names,
+separated by whitespace. Exclamation marks may be prepended to each of the
+names, meaning “NOT”.
+
+A restriction formula consists of one or more restriction lists, separated
+by whitespace. Each restriction list is enclosed in angle brackets. Items
+in the restriction list are build profile names, separated by whitespace
+and can be prefixed with an exclamation mark, meaning “NOT”.
+A restriction formula represents a disjunctive normal form expression.
+
+Note that dependencies on packages in the
+B<build-essential>
+set can be omitted and that declaring build conflicts against them is
+impossible. A list of these packages is in the build-essential package.
+
+=head1 BINARY FIELDS
+
+Note that the
+B<Priority>, B<Section>
+and
+B<Homepage>
+fields can also be in a binary stanza to override the global value from the
+source package.
+
+=over
+
+=item B<Package:> I<binary-package-name> (required)
+
+This field is used to name the binary package name. The same restrictions as
+to a source package name apply.
+
+=item B<Package-Type:> B<deb>|B<udeb>|I<type>
+
+This field defines the type of the package.
+B<udeb> is for size-constrained packages used by the debian installer.
+B<deb> is the default value, it is assumed if the field is absent.
+More types might be added in the future.
+
+=item B<Architecture:> I<arch>|B<all>|B<any> (required)
+
+The architecture specifies on which type of hardware this package runs. For
+packages that run on all architectures, use the
+B<any>
+value. For packages that are architecture independent, such as shell and Perl
+scripts or documentation, use the
+B<all>
+value. To restrict the packages to a certain set of architectures, specify the
+architecture names, separated by a space. It's also possible to put
+architecture wildcards in that list (see
+B<dpkg-architecture>(1)
+for more information about them).
+
+=item B<Build-Profiles:> I<restriction-formula>
+
+This field specifies the conditions for which this binary package does or
+does not build.
+To express that condition, the same restriction formula syntax from the
+B<Build-Depends> field is used (including the angle brackets).
+
+If a binary package stanza does not contain this field, then it implicitly
+means that it builds with all build profiles (including none at all).
+
+In other words, if a binary package stanza is annotated with a non-empty
+B<Build-Profiles> field, then this binary package is generated if and
+only if the condition expressed by the conjunctive normal form expression
+evaluates to true.
+
+=item B<Protected:> B<yes>|B<no>
+
+=item B<Essential:> B<yes>|B<no>
+
+=item B<Build-Essential:> B<yes>|B<no>
+
+=item B<Multi-Arch:> B<same>|B<foreign>|B<allowed>|B<no>
+
+=item B<Tag:> I<tag-list>
+
+=item B<Description:> I<short-description> (recommended)
+
+These fields are described in the
+B<deb-control>(5)
+manual page, as they are copied literally to the control file of the binary
+package.
+
+=item B<Depends:> I<package-list>
+
+=item B<Pre-Depends:> I<package-list>
+
+=item B<Recommends:> I<package-list>
+
+=item B<Suggests:> I<package-list>
+
+=item B<Breaks:> I<package-list>
+
+=item B<Enhances:> I<package-list>
+
+=item B<Replaces:> I<package-list>
+
+=item B<Conflicts:> I<package-list>
+
+=item B<Provides:> I<package-list>
+
+=item B<Built-Using:> I<package-list>
+
+=item B<Static-Built-Using:> I<package-list>
+
+These fields declare relationships between packages. They are discussed in
+the
+B<deb-control>(5)
+manpage.
+When these fields are found in I<debian/control> they can also end with
+a trailing comma (since dpkg 1.10.14), have architecture specifications and
+restriction formulas which will all get reduced when generating the fields
+for B<deb-control>(5).
+
+=item B<Subarchitecture:> I<value>
+
+=item B<Kernel-Version:> I<value>
+
+=item B<Installer-Menu-Item:> I<value>
+
+These fields are used by the debian-installer in B<udeb>s and are
+usually not needed.
+For more details about them, see
+L<https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt>.
+
+=back
+
+=head1 USER-DEFINED FIELDS
+
+It is allowed to add additional user-defined fields to the control file. The
+tools will ignore these fields. If you want the fields to be copied over to
+the output files, such as the binary packages, you need to use a custom naming
+scheme: the fields should start with an B<X>, followed by zero or more of
+the letters B<SBC> and a hyphen.
+
+=over
+
+=item B<S>
+
+The field will appear in the source package control file, see B<dsc>(5).
+
+=item B<B>
+
+The field will appear in the control file in the binary package, see
+B<deb-control>(5).
+
+=item B<C>
+
+The field will appear in the upload control (.changes) file, see
+B<deb-changes>(5).
+
+=back
+
+Note that the B<X>[B<SBC>]B<-> prefixes are stripped when the
+fields are copied over to the output files. A field B<XC-Approved-By>
+will appear as B<Approved-By> in the changes file and will not appear
+in the binary or source package control files.
+
+Take into account that these user-defined fields will be using the global
+namespace, which might at some point in the future collide with officially
+recognized fields. To avoid such potential situation you can prefix those
+fields with B<Private->, such as B<XB-Private-New-Field>.
+
+=head1 EXAMPLE
+
+ # Comment
+ Source: dpkg
+ Section: admin
+ Priority: required
+ Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
+ # this field is copied to the binary and source packages
+ XBS-Upstream-Release-Status: stable
+ Homepage: https://wiki.debian.org/Teams/Dpkg
+ Vcs-Browser: https://git.dpkg.org/cgit/dpkg/dpkg.git
+ Vcs-Git: https://git.dpkg.org/git/dpkg/dpkg.git
+ Standards-Version: 3.7.3
+ Build-Depends: pkg-config, debhelper (>= 4.1.81),
+  libselinux1-dev (>= 1.28-4) [!linux-any]
+
+ Package: dpkg-dev
+ Section: utils
+ Priority: optional
+ Architecture: all
+ # this is a custom field in the binary package
+ XB-Mentoring-Contact: Raphael Hertzog <hertzog@debian.org>
+ Depends: dpkg (>= 1.14.6), perl5, perl-modules, cpio (>= 2.4.2-2),
+  bzip2, lzma, patch (>= 2.2-1), make, binutils, libtimedate-perl
+ Recommends: gcc | c-compiler, build-essential
+ Suggests: gnupg, debian-keyring
+ Conflicts: dpkg-cross (<< 2.0.0), devscripts (<< 2.10.26)
+ Replaces: manpages-pl (<= 20051117-1)
+ Description: Debian package development tools
+  This package provides the development tools (including dpkg-source)
+  required to unpack, build and upload Debian source packages.
+  .
+  Most Debian source packages will require additional tools to build;
+  for example, most packages need make and the C compiler gcc.
+
+=head1 SEE ALSO
+
+I<%PKGDOCDIR%/spec/rootless-builds.txt>,
+L<deb822(5)>,
+B<deb-control>(5),
+B<deb-version>(7),
+B<dpkg-source>(1)