diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/deb-control.pod | |
parent | Initial commit. (diff) | |
download | dpkg-b86570f63e533abcbcb97c2572e0e5732a96307b.tar.xz dpkg-b86570f63e533abcbcb97c2572e0e5732a96307b.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/deb-control.pod')
-rw-r--r-- | man/deb-control.pod | 449 |
1 files changed, 449 insertions, 0 deletions
diff --git a/man/deb-control.pod b/man/deb-control.pod new file mode 100644 index 0000000..3d7bf84 --- /dev/null +++ b/man/deb-control.pod @@ -0,0 +1,449 @@ +# 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 packages' master 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 master +B<debian/control> file in Debian source packages, see B<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 +B<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 B<> 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. + +=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 for proper booting of the system. +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). + +=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 proper operation of the system. +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> (recommended) + +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. +See /usr/share/doc/debian-installer/devel/modules.txt from the +B<debian-installer> +package for more details about them. + +=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 field lists extra source packages that were used during the build of this +binary package. 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 list of source package names with strict ‘B<=>’ +version relationships. 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<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> master 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)>, +B<deb-src-control>(5), +B<deb>(5), +B<deb-version>(7), +B<debtags>(1), +B<dpkg>(1), +B<dpkg-deb>(1). |