1 files changed, 485 insertions, 0 deletions
diff --git a/man/deb-control.pod b/man/deb-control.pod
new file mode 100644
index 0000000..4c8d006
--- /dev/null
+++ b/man/deb-control.pod
@@ -0,0 +1,485 @@
+# dpkg manual page - deb-control(5)
+#
+# Copyright © 1995 Raul Miller, Ian Jackson, Ian Murdock
+# Copyright © 1999 Ben Collins <bcollins@debian.org>
+# Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2007-2011, 2013-2015 Guillem Jover <guillem@debian.org>
+# Copyright © 2008-2012 Raphaël Hertzog <hertzog@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-control - Debian binary package control file format
+
+=head1 SYNOPSIS
+
+B<DEBIAN/control>
+
+=head1 DESCRIPTION
+
+Each Debian binary package contains a B<control> file in its B<control>
+member, and its L<deb822(5)> format is a subset of the B<debian/control>
+template source control file in Debian source packages,
+see L<deb-src-control(5)>.
+
+This file contains a number of fields.
+Each field begins with a tag, such as
+B<Package>
+or
+B<Version>
+(case insensitive), followed by a colon, and the body of the field
+(case sensitive unless stated otherwise).
+Fields are delimited only by field tags.
+In other words, field text
+may be multiple lines in length, but the installation tools will
+generally join lines when processing the body of the field (except
+in the case of the
+B<Description>
+field, see below).
+
+=head1 FIELDS
+
+=over
+
+=item B<Package:> I<package-name> (required)
+
+The value of this field determines the package name, and is used to
+generate file names by most installation tools.
+
+=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<Version:> I<version-string> (required)
+
+Typically, this is the original package's version number in whatever form
+the program's author uses.
+It may also include a Debian revision number (for non-native packages).
+The exact format and sorting algorithm
+are described in
+L<deb-version(7)>.
+
+=item B<Maintainer:> I<fullname-email> (recommended)
+
+Should be in the format “Joe Bloggs E<lt>jbloggs@foo.comE<gt>”, and is typically
+the person who created the package, as opposed to the author of the
+software that was packaged.
+
+=item B<Description:> I<short-description> (recommended)
+
+=item S< >I<long-description>
+
+The format for the 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<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.
+
+=back
+
+The
+B<Section>
+and
+B<Priority>
+fields usually have a defined set of accepted values based on the specific
+distribution policy.
+
+=over
+
+=item B<Installed-Size:> I<size>
+
+The approximate total size of the package's installed files, in KiB units.
+The algorithm to compute the size is described in L<deb-substvars(5)>.
+
+=item B<Protected:> B<yes>|B<no>
+
+This field is usually only needed when the answer is B<yes>.
+It denotes a package that is required mostly for proper booting of the system
+or used for custom system-local meta-packages.
+L<dpkg(1)> or any other installation tool will not allow a B<Protected>
+package to be removed (at least not without using one of the force options).
+
+Supported since dpkg 1.20.1.
+
+=item B<Essential:> B<yes>|B<no>
+
+This field is usually only needed when the answer is B<yes>.
+It denotes a package that is required for the packaging system, for
+proper operation of the system in general or during boot (although the latter
+should be converted to B<Protected> field instead).
+L<dpkg(1)> or any other installation tool will not allow an B<Essential>
+package to be removed (at least not without using one of the force options).
+
+=item B<Build-Essential:> B<yes>|B<no>
+
+This field is usually only needed when the answer is B<yes>, and is
+commonly injected by the archive software.
+It denotes a package that is required when building other packages.
+
+=item B<Architecture:> I<arch>|B<all> (required)
+
+The architecture specifies which type of hardware this package was compiled
+for.
+Common architectures are B<amd64>, B<armel>, B<i386>, B<powerpc>,
+etc.
+Note that the
+B<all>
+value is meant for packages that are architecture independent.
+Some examples of this are shell and Perl scripts, and documentation.
+
+=item B<Origin:> I<name>
+
+The name of the distribution this package is originating from.
+
+=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>.
+
+=item B<Homepage:> I<url>
+
+The upstream project home page I<url>.
+
+=item B<Tag:> I<tag-list>
+
+List of tags describing the qualities of the package.
+The description and
+list of supported tags can be found in the B<debtags> package.
+
+=item B<Multi-Arch:> B<no>|B<same>|B<foreign>|B<allowed>
+
+This field is used to indicate how this package should behave on a multi-arch
+installations.
+
+=over
+
+=item B<no>
+
+This value is the default when the field is omitted, in which case
+adding the field with an explicit B<no> value is generally not needed.
+
+=item B<same>
+
+This package is co-installable with itself, but it must not be used to
+satisfy the dependency of any package of a different architecture from
+itself.
+
+=item B<foreign>
+
+This package is not co-installable with itself, but should be allowed to
+satisfy a non-arch-qualified dependency of a package of a different arch
+from itself (if a dependency has an explicit arch-qualifier then the
+value B<foreign> is ignored).
+
+=item B<allowed>
+
+This allows reverse-dependencies to indicate in their B<Depends>
+field that they accept this package from a foreign architecture by
+qualifying the package name with B<:any>, but has no effect otherwise.
+
+=back
+
+=item B<Source:> I<source-name> [B<(>I<source-version>B<)>]
+
+The name of the source package that this binary package came from, if it is
+different than the name of the package itself.
+If the source version differs from the binary version, then the
+I<source-name> will be followed by a I<source-version> in parenthesis.
+This can happen for example on a binary-only non-maintainer upload, or when
+setting a different binary version via «B<dpkg-gencontrol -v>».
+
+=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 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>.
+
+=item B<Depends:> I<package-list>
+
+List of packages that are required for this package to provide a
+non-trivial amount of functionality.
+The package maintenance software
+will not allow a package to be installed if the packages listed in its
+B<Depends>
+field aren't installed (at least not without using the force options).
+In an installation, the postinst scripts of packages listed in B<Depends>
+fields are run before those of the packages which depend on them.
+On the
+opposite, in a removal, the prerm script of a package is run before
+those of the packages listed in its B<Depends> field.
+
+=item B<Pre-Depends:> I<package-list>
+
+List of packages that must be installed
+B<and>
+configured before this one can be installed.
+This is usually used in the
+case where this package requires another package for running its preinst
+script.
+
+=item B<Recommends:> I<package-list>
+
+Lists packages that would be found together with this one in all but
+unusual installations.
+The package maintenance software will warn the
+user if they install a package without those listed in its
+B<Recommends>
+field.
+
+=item B<Suggests:> I<package-list>
+
+Lists packages that are related to this one and can perhaps enhance
+its usefulness, but without which installing this package is perfectly
+reasonable.
+
+=back
+
+The syntax of
+B<Depends>,
+B<Pre-Depends>,
+B<Recommends>
+and
+B<Suggests>
+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.
+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.
+
+An architecture qualifier name can be a real Debian architecture name
+(since dpkg 1.16.5) or B<any> (since dpkg 1.16.2).
+If omitted, the default is the current binary package architecture.
+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 has been marked as B<Multi-Arch: allowed>.
+
+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.
+
+=over
+
+=item B<Breaks:> I<package-list>
+
+Lists packages that this one breaks, for example by exposing bugs
+when the named packages rely on this one.
+The package maintenance
+software will not allow broken packages to be configured; generally
+the resolution is to upgrade the packages named in a
+B<Breaks>
+field.
+
+=item B<Conflicts:> I<package-list>
+
+Lists packages that conflict with this one, for example by containing
+files with the same names.
+The package maintenance software will not allow conflicting packages to be
+installed at the same time.
+Two
+conflicting packages should each include a
+B<Conflicts>
+line mentioning the other.
+
+=item B<Replaces:> I<package-list>
+
+List of packages files from which this one replaces.
+This is used for
+allowing this package to overwrite the files of another package and
+is usually used with the
+B<Conflicts>
+field to force removal of the other package, if this one also has the
+same files as the conflicted package.
+
+=back
+
+The syntax of
+B<Breaks>,
+B<Conflicts>
+and
+B<Replaces>
+is a list of package names, separated by commas (and optional whitespace).
+In the
+B<Breaks>
+and
+B<Conflicts>
+fields, the comma should be read as “OR”.
+An optional architecture qualifier can also be appended to the package name
+with the same syntax as above, but the default is B<any> instead of the
+binary package architecture.
+An optional version can also be given with the same syntax as above for the
+B<Breaks>,
+B<Conflicts>
+and
+B<Replaces>
+fields.
+
+=over
+
+=item B<Enhances:> I<package-list>
+
+This is a list of packages that this one enhances.
+It is similar to B<Suggests> but in the opposite direction.
+
+=item B<Provides:> I<package-list>
+
+This is a list of virtual packages that this one provides.
+Usually this is used in the case of several packages all providing the
+same service.
+For example, sendmail and exim can serve as a mail server, so they
+provide a common package (“mail-transport-agent”) on which
+other packages can depend.
+This will allow sendmail or exim to serve as a valid option to satisfy
+the dependency.
+This prevents the packages that depend on a mail server from having to
+know the package names for all of them, and using ‘B<|>’ to
+separate the list.
+
+=back
+
+The syntax of
+B<Provides>
+is a list of package names, separated by commas (and optional whitespace).
+An optional architecture qualifier can also be appended to the package
+name with the same syntax as above.
+If omitted, the default is the current binary package architecture.
+An optional exact (equal to) version can also be given with the same
+syntax as above (honored since dpkg 1.17.11).
+
+=over
+
+=item B<Built-Using:> I<package-list>
+
+This dependency field lists extra source packages that were used during the
+build of this binary package, for license compliance purposes.
+This is an indication to the archive maintenance software that these extra
+source packages must be kept whilst this binary package is maintained.
+This field must be a comma-separated list of source package names with strict
+‘B<=>’ version relationships enclosed within parenthesis.
+Note that the archive maintenance software is likely to refuse to accept an
+upload which declares a B<Built-Using> relationship which cannot be satisfied
+within the archive.
+
+=item B<Static-Built-Using:> I<package-list>
+
+This dependency field lists extra source packages that were used during the
+build of this binary package, for static building purposes (for example
+linking against static libraries, builds for source-centered languages such
+as Go or Rust, usage of header-only C/C++ libraries, injecting data blobs
+into code, etc.).
+This is useful to track whether this package might need to be rebuilt when
+source packages listed here have been updated, for example due to security
+updates.
+This field must be a comma-separated list of source package names with strict
+‘B<=>’ version relationships enclosed within parenthesis.
+
+Supported since dpkg 1.21.3.
+
+=item B<Built-For-Profiles:> I<profile-list> (obsolete)
+
+This field used to specify a whitespace separated list of build profiles that
+this binary packages was built with (since dpkg 1.17.2 until 1.18.18).
+The information previously found in this field can now be found in the
+B<.buildinfo> file, which supersedes it.
+
+=item B<Auto-Built-Package:> I<reason-list>
+
+This field specifies a whitespace separated list of reasons why this package
+was auto-generated.
+Binary packages marked with this field will not appear in the
+I<debian/control> template source control file.
+The only currently used reason is B<debug-symbols>.
+
+=item B<Build-Ids:> I<elf-build-id-list>
+
+This field specifies a whitespace separated list of ELF build-ids.
+These
+are unique identifiers for semantically identical ELF objects, for each
+of these within the package.
+
+The format or the way to compute each build-id is not defined by design.
+
+=back
+
+=head1 EXAMPLE
+
+ Package: grep
+ Essential: yes
+ Priority: required
+ Section: base
+ Maintainer: Wichert Akkerman <wakkerma@debian.org>
+ Architecture: sparc
+ Version: 2.4-1
+ Pre-Depends: libc6 (>= 2.0.105)
+ Provides: rgrep
+ Conflicts: rgrep
+ Description: GNU grep, egrep and fgrep.
+  The GNU family of grep utilities may be the "fastest grep in the west".
+  GNU grep is based on a fast lazy-state deterministic matcher (about
+  twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper
+  search for a fixed string that eliminates impossible text from being
+  considered by the full regexp matcher without necessarily having to
+  look at every character. The result is typically many times faster
+  than Unix grep or egrep. (Regular expressions containing backreferencing
+  will run more slowly, however).
+
+=head1 BUGS
+
+The B<Build-Ids> field uses a rather generic name out of its original
+context within an ELF object, which serves a very specific purpose and
+executable format.
+
+=head1 SEE ALSO
+
+L<deb822(5)>,
+L<deb-src-control(5)>,
+L<deb(5)>,
+L<deb-version(7)>,
+L<debtags(1)>,
+L<dpkg(1)>,
+L<dpkg-deb(1)>.