diff options
Diffstat (limited to '')
| -rw-r--r-- | man/deb-src-control.pod | 541 |
1 files changed, 541 insertions, 0 deletions
diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod new file mode 100644 index 0000000..5f3a0fd --- /dev/null +++ b/man/deb-src-control.pod @@ -0,0 +1,541 @@ +# 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 package template control file format + +=head1 SYNOPSIS + +B<debian/control> + +=head1 DESCRIPTION + +Each Debian source package contains the «B<debian/control>» template source +control file, +and its L<deb822(5)> format is a superset of the B<control> file +shipped in Debian binary packages, see L<deb-control(5)>. + +This file contains at least 2 stanzas, separated by a blank line. +The first stanza is called the source package stanza and lists all +information about the source package in general, +while each following stanzas are called the binary package stanzas and +describe exactly one binary package per stanza. +Each stanza consists of at least one field. +A field starts with a field name, 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 +field name, 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. +This is the default in B<dpkg-build-api> level >= 1. + +=item B<binary-targets> + +The binary targets must always be run under (fake)root. +This value is the default in B<dpkg-build-api> level 0, +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 +L<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 web interface 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 L<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 L<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 +L<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 +L<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 +L<deb-control(5)> +manual page. +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 L<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 L<dsc(5)>. + +=item B<B> + +The field will appear in the control file in the binary package, see +L<deb-control(5)>. + +=item B<C> + +The field will appear in the upload control (.changes) file, see +L<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: pkgconf, 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)>, +L<deb-control(5)>, +L<deb-version(7)>, +L<dpkg-source(1)> |