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-src-control.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/deb-src-control.pod | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod new file mode 100644 index 0000000..996037b --- /dev/null +++ b/man/deb-src-control.pod @@ -0,0 +1,511 @@ +# 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 paragraphs, separated by a blank line. +The first paragraph lists +all information about the source package in general, while each following +paragraph describes exactly one binary package. Each paragraph 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 B<> 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 paragraph 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. + +If a binary package paragraph 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 paragraph 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<Byes>|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> + +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. +See /usr/share/doc/debian-installer/devel/modules.txt from the +B<debian-installer> +package for more details about them. + +=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 + +L<deb822(5)>, +B<deb-control>(5), +B<deb-version>(7), +B<dpkg-source>(1) |