deb-buildinfo

title: deb-buildinfo(5)

summary: Debian build information file format

text:
# deb-buildinfo(5)

## NAME
deb-buildinfo - Debian build information file format

## SYNOPSIS
filename.buildinfo

## DESCRIPTION
Each Debian source package build can record the build information in a .buildinfo control file, which contains a number of fields in deb822(5) format.

Each field begins with a tag, such as Source or Binary (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 case of the multiline fields Binary-Only-Changes, Installed-Build-Depends, Environment, Checksums-Md5, Checksums-Sha1 and Checksums-Sha256, see below).

The control data might be enclosed in an OpenPGP ASCII Armored signature, as specified in RFC4880.

The name of the .buildinfo file will depend on the type of build and will be as specific as necessary but not more; for a build that includes any the name will be source-name_binary-version_arch.buildinfo, or otherwise for a build that includes all the name will be source-name_binary-version_all.buildinfo, or otherwise for a build that includes source the name will be source-name_source-version_source.buildinfo.

## FIELDS
Format: format-version (required)

The value of this field declares the format version of the file. The syntax of the field value is a version number with a major and minor component. Backward incompatible changes to the format will bump the major version, and backward compatible changes (such as field additions) will bump the minor version. The current format version is 1.0.

Source: source-name [(source-version)] (required)

The name of the source package. If the source version differs from the binary version, then the source-name will be followed by a source-version in parenthesis. This can happen when the build is for a binary-only non-maintainer upload.

Binary: binary-package-list (required in context)

This folded field is a space-separated list of binary packages built. If the build is source-only, then the field is omitted (since dpkg 1.20.0).

Architecture: arch-list (required)

This space-separated field lists the architectures of the files currently being built. Common architectures are amd64, armel, i386, etc. Note that the all value is meant for packages that are architecture independent. If the source for the package is also being built, the special entry source is also present. Architecture wildcards must never be present in the list.

Version: 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 deb-version(7).

Binary-Only-Changes:

changelog-entry

This multiline field contains the concatenated text of the changelog entry for a binary-only non-maintainer upload (binNMU) if that is the case. To make this a valid multiline field empty lines are replaced with a single full stop (‘.’) and all lines are indented by one space character. The exact content depends on the changelog format.

Checksums-Md5: (required)

Checksums-Sha1: (required)

Checksums-Sha256: (required)

checksum size filename

These multiline fields contain a list of files with a checksum and size for each one. These fields have the same syntax and differ only in the checksum algorithm used: MD5 for Checksums-Md5, SHA-1 for Checksums-Sha1 and SHA-256 for Checksums-Sha256. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of space-separated entries describing the file: the checksum, the file size, and the file name.

These fields list all files that make up the build.

Build-Origin: name

The name of the distribution this package is originating from.

Build-Architecture: arch (required)

The Debian architecture for the installation the packages is being built in. Common architectures are amd64, armel, i386, etc.

Build-Date: build-date

The date the package was built. It must be in the same format as the date in a deb-changelog(5) entry.

Build-Kernel-Version: build-kernel-version

The release and version (in an unspecified format) of the kernel running on the build system. This field is only going to be present if the builder has explicitly requested it, to avoid leaking possibly sensitive information.

Build-Path: build-path

The absolute build path, which correspond to the unpacked source tree. This field is only going to be present if the vendor has allowed it via some pattern match to avoid leaking possibly sensitive information. On Debian and derivatives only build paths starting with /build/ will emit this field.

Build-Tainted-By:

taint-reason-list

This folded field contains a space-separated list of non-exhaustive reason tags (formed by alphanumeric and dash characters) which identify why the current build has been tainted (since dpkg 1.19.5). On Debian and derivatives the following reason tags can be emitted:

merged-usr-via-aliased-dirs

The system has a merged /usr via aliased directories (previously known as merged-usr-via-symlinks). This will confuse dpkg-query, dpkg-statoverride, dpkg-trigger, update-alternatives and any other tool using pathnames as keys into their databases, as it creates filesystem aliasing problems, and messes with the understanding of the filesystem that dpkg has recorded in its database. For build systems that hardcode pathnames to specific binaries or libraries on the resulting artifacts, it can also produce packages that will be incompatible with non-/usr-merged filesystems.

usr-local-has-configs

The system has configuration files under /usr/local/etc.

usr-local-has-includes

The system has header files under /usr/local/include.

usr-local-has-programs

The system has programs under /usr/local/bin or /usr/local/sbin.

usr-local-has-libraries

The system has libraries, either static or shared under /usr/local/lib.

can-execute-cross-built-programs

The system can execute cross built programs, either directly or via some emulation layer. Since dpkg 1.21.10.

Installed-Build-Depends: (required)

package-list

The list of installed and configured packages that might affect the package build process. The list consists of each package name, optionally arch-qualified for foreign architectures, with an exact version restriction, separated by commas.

The list includes all essential packages, packages listed in Build-Depends, Build-Depends-Arch, Build-Depends-Indep source control fields, any vendor specific builtin dependencies, and all their recursive dependencies. On Debian and derivatives the dependency builtin is build-essential.

For dependencies coming from the source control fields, all dependency alternatives and all providers of virtual packages depended on will be included.

Environment:

variable-list

The list of environment variables that are known to affect the package build process, with each environment variable followed by an equal sign (‘=’) and the variable's quoted value, using double quotes (‘"’), and backslashes escaped (‘\\’).

## SEE ALSO
deb822(5), deb-changes(5), deb-version(7), dpkg-genbuildinfo(1).


deb-changelog

package: dpkg

title: deb-changelog(5)

text:
# deb-changelog(5)

## NAME
deb-changelog - dpkg source packages' changelog file format

## SYNOPSIS
debian/changelog

## DESCRIPTION
Changes in the packaged version of a project are explained in the changelog file debian/changelog. This includes modifications made in the source package compared to the upstream one as well as other changes and updates to the package.

The format of the debian/changelog allows the package building tools to discover which version of the package is being built and find out other release-specific information.

That format is a series of entries like this:

package (version) distributions; metadata

[optional blank line(s), stripped]

* change-details

more-change-details

[blank line(s), included in dpkg-parsechangelog(1) output]

* even-more-change-details

[optional blank line(s), stripped]

-- maintainer-name <email-address> date

package and version are the source package name and version number. version is delimited by parenthesis U+00028 ‘(’ and U+0029 ‘)’.

distributions lists one or more space-separated distributions where this version should be installed when it is uploaded; it is copied to the Distribution field in the .changes file. distributions must be terminated by a semicolon (U+003B ‘;’).

metadata lists zero or more comma-separated keyword=value items. Each keyword can contain only minus and case insensitive alphanumeric characters, as they need to be mapped to deb822(5) field names. The only keywords currently supported by dpkg are urgency and binary-only. urgency's value is used for the Urgency field in the .changes file for the upload. binary-only with a yes value, is used to denote that this changelog entry is for a binary-only non-maintainer upload (an automatic binary rebuild with the only change being the changelog entry).

The change details may in fact be any series of lines starting with at least two spaces (U+0020 SPACE), but conventionally each change starts with an asterisk and a separating space and continuation lines are indented so as to bring them in line with the start of the text above. Blank lines may be used here to separate groups of changes, if desired.

If this upload resolves bugs recorded in the distribution bug tracking system, they may be automatically closed on the inclusion of this package into the distribution archive by including the string:

Closes: #nnnnn

in the change details, where #nnnnn is the bug number. The exact Perl regular expression is:

/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i

That is, the string should consist of the word closes: followed by a comma-separated list of bug numbers. Bug numbers may be preceded by the word bug and/or a # sign, as in "Closes: 42, bug#43, #44, bug 45". The words closes: and bug are not case sensitive. The list of bug numbers may span multiple lines.

This information is conveyed via the Closes field in the .changes file. Where, depending on the archive maintenance software, all the bug numbers listed might get automatically closed.

The maintainer name and email address used in the changelog should be the details of the person who prepared this release of the package. They are not necessarily those of the uploader or usual package maintainer. The information here will be copied to the Changed-By field in the .changes file, and then later might be used to send an acknowledgment when the upload has been installed in the distribution archive.

The date has the following format (compatible and with the same semantics of RFC2822 and RFC5322, or what «date -R» generates):

day-of-week, dd month yyyy hh:mm:ss +zzzz

where:

day-of-week

Is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun.

dd

Is a one- or two-digit day of the month (01-31), where the leading zero is optional, but conventionally does not get omitted.

month

Is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.

yyyy

Is the four-digit year (e.g. 2010).

hh

Is the two-digit hour (00-23).

mm

Is the two-digit minutes (00-59).

ss

Is the two-digit seconds (00-60).

[+-]zzzz

Is the time zone offset from Coordinated Universal Time (UTC). ‘+’ indicates that the time is ahead of (i.e., east of) UTC and ‘-’ indicates that the time is behind (i.e., west of) UTC. The first two digits indicate the hour difference from UTC and the last two digits indicate the number of additional minutes difference from UTC. The last two digits must be in the range 00-59.

The first “title” line with the package name must start at the left hand margin. The “trailer” line with the maintainer and date details must be preceded by exactly one space (U+0020 SPACE). The maintainer details and the date must be separated by exactly two spaces (U+0020 SPACE). Each part of the date can be separated by one or more spaces (U+0020 SPACE), except after the comma where it can be separated by zero or more spaces (U+0020 SPACE).

Any line that consists entirely (i.e., no leading whitespace) of # or /* */ style comments or RCS keywords.

Vim modelines or Emacs local variables, and ancient changelog entries with other formats at the end of the file should be accepted and preserved on output, but their contents might be otherwise ignored and parsing stopped at that point.

The entire changelog must be encoded in UTF-8.

## FILES
debian/changelog

## EXAMPLES

```
 dpkg (1.17.18) unstable; urgency=low
  [ Guillem Jover ]
  * Handle empty minimum versions when initializing dependency versions,
    as the code is mapping the minimum version 0 to '' to avoid outputting
    useless versions. Regression introduced in dpkg 1.17.17. Closes: #764929
  [ Updated programs translations ]
  * Catalan (Guillem Jover).
  [ Updated dselect translations ]
  * Catalan (Guillem Jover).
  * German (Sven Joachim).
  -- Guillem Jover <guillem@debian.org>  Sun, 12 Oct 2014 15:47:44 +0200
```

## SEE ALSO
deb822(5), deb-version(7), deb-changes(5), dpkg-parsechangelog(1).


deb-changes

title: deb-changes(5)

summary: Debian changes file format

text:
# deb-changes(5)

## NAME
deb-changes - Debian changes file format

## SYNOPSIS
filename.changes

## DESCRIPTION
Each Debian upload is composed of a .changes control file, which contains a number of fields in deb822(5) format.

Each field begins with a tag, such as Source or Binary (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 case of the multiline fields Description, Changes, Files, Checksums-Sha1 and Checksums-Sha256, see below).

The control data might be enclosed in an OpenPGP ASCII Armored signature, as specified in RFC4880.

## FIELDS
Format: format-version (required)

The value of this field declares the format version of the file. The syntax of the field value is a version number with a major and minor component. Backward incompatible changes to the format will bump the major version, and backward compatible changes (such as field additions) will bump the minor version. The current format version is 1.8.

Date: release-date (required)

The date the package was built or last edited. It must be in the same format as the date in a deb-changelog(5) entry. The value of this field is usually extracted from the debian/changelog file.

Source: source-name [(source-version)] (required)

The name of the source package. If the source version differs from the binary version, then the source-name will be followed by a source-version in parenthesis. This can happen when the upload is a binary-only non-maintainer upload.

Binary: binary-package-list (required in context)

This folded field is a space-separated list of binary packages to upload. If the upload is source-only, then the field is omitted (since dpkg 1.19.3).

Architecture: arch-list

Lists the architectures of the files currently being uploaded. Common architectures are amd64, armel, i386, etc. Note that the all value is meant for packages that are architecture independent. If the source for the package is also being uploaded, the special entry source is also present. Architecture wildcards must never be present in the list.

Version: 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 deb-version(7).

Distribution: distributions (required)

Lists one or more space-separated distributions where this version should be installed when it is uploaded to the archive.

Urgency: urgency (recommended)

The urgency of the upload. The currently known values, in increasing order of urgency, are: low, medium, high, critical and emergency.

Maintainer: fullname-email (required)

Should be in the format “Joe Bloggs <jbloggs@example.org>”, and is typically the person who created the package, as opposed to the author of the software that was packaged.

Changed-By: fullname-email

Should be in the format “Joe Bloggs <jbloggs@example.org>”, and is typically the person who prepared the package changes for this release.

Description: (recommended)

binary-package-name - binary-package-summary

This multiline field contains a list of binary package names followed by a space, a dash (‘-’) and their possibly truncated short descriptions. If the upload is source-only, then the field is omitted (since dpkg 1.19.3).

Closes: bug-number-list

A space-separated list of bug report numbers for bug reports that have been resolved with this upload. The distribution archive software might use this field to automatically close the referred bug numbers in the distribution bug tracking system.

Binary-Only: yes

This field denotes that the upload is a binary-only non-maintainer build. It originates from the binary-only=yes key/value from the changelog metadata entry.

Built-For-Profiles: profile-list

This field specifies a whitespace separated list of build profiles that this upload was built with.

Changes: (required)

changelog-entries

This multiline field contains the concatenated text of all changelog entries that are part of the upload. To make this a valid multiline field empty lines are replaced with a single full stop (‘.’) and all lines are indented by one space character. The exact content depends on the changelog format.

Files: (required)

md5sum size section priority filename

This multiline field contains a list of files with an md5sum, size, section and priority for each one. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of space-separated entries describing the file: the md5sum, the file size, the file section, the file priority, and the file name.

This field lists all files that make up the upload. The list of files in this field must match the list of files in the other related Checksums fields.

Checksums-Sha1: (required)

Checksums-Sha256: (required)

checksum size filename

These multiline fields contain a list of files with a checksum and size for each one. These fields have the same syntax and differ only in the checksum algorithm used: SHA-1 for Checksums-Sha1 and SHA-256 for Checksums-Sha256. The first line of the field value (the part on the same line as the field name followed by a colon) is always empty. The content of the field is expressed as continuation lines, one line per file. Each line consists of space-separated entries describing the file: the checksum, the file size, and the file name.

These fields list all files that make up the upload. The list of files in these fields must match the list of files in the Files field and the other related Checksums fields.

## BUGS
The Files field is inconsistent with the other Checksums fields. The Changed-By and Maintainer fields have confusing names. The Distribution field contains information about what is commonly referred to as a suite.

## SEE ALSO
deb822(5), deb-src-control(5), deb-version(7).


deb-conffiles

title: deb-conffiles(5)

summary: package conffiles

text:
# deb-conffiles(5)

## NAME
deb-conffiles - package conffiles

## SYNOPSIS
DEBIAN/conffiles

## DESCRIPTION
A package declares its list of conffiles by including a conffiles file in its control archive (i.e. DEBIAN/conffiles during package creation).

This file contains a list of files, one per line, with an optional leading flag separated by whitespace. The conffiles must be listed as absolute pathnames. Trailing whitespace will be trimmed, but empty or whitespace-only lines are not accepted.

Files without a flag should exist in the binary package, otherwise dpkg(1) will ignore them.

There is currently only one flag supported, remove-on-upgrade, to mark that a conffile needs to be removed on the next upgrade (since dpkg 1.20.6). These files must not exist in the binary package, as both dpkg(1) and dpkg-deb(1) will not accept building nor processing such binary packages.

## EXAMPLE

```
 /etc/alternatives/README
 /etc/cron.daily/dpkg
 /etc/dpkg/dpkg.cfg
 /etc/logrotate.d/dpkg
 remove-on-upgrade /etc/some-old-file.conf
```

## SEE ALSO
dpkg-deb(1), dpkg(1).


deb-control

title: deb-control(5)

text:
# deb-control(5)

## NAME
deb-control - Debian binary packages' master control file format

## SYNOPSIS
DEBIAN/control

## DESCRIPTION
Each Debian binary package contains a control file in its control member, and its deb822(5) format is a subset of the master debian/control file in Debian source packages, see deb-src-control(5).

This file contains a number of fields. Each field begins with a tag, such as Package or 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 Description field, see below).

## FIELDS
Package: package-name (required)

The value of this field determines the package name, and is used to generate file names by most installation tools.

Package-Type: deb|udeb|type

This field defines the type of the package. udeb is for size-constrained packages used by the debian installer. deb is the default value, it is assumed if the field is absent. More types might be added in the future.

Version: 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 deb-version(7).

Maintainer: fullname-email (recommended)

Should be in the format “Joe Bloggs <jbloggs@foo.com>”, and is typically the person who created the package, as opposed to the author of the software that was packaged.

Description: short-description (recommended)

long-description

The format for the package description is a short brief summary on the first line (after the 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 ‘.’ following the preceding space.

Section: section

This is a general field that gives the package a category based on the software that it installs. Some common sections are utils, net, mail, text, x11, etc.

Priority: priority

Sets the importance of this package in relation to the system as a whole. Common priorities are required, standard, optional, extra, etc.

The Section and Priority fields usually have a defined set of accepted values based on the specific distribution policy.

Installed-Size: size

The approximate total size of the package's installed files, in KiB units. The algorithm to compute the size is described in deb-substvars(5).

Protected: yes|no

This field is usually only needed when the answer is yes. It denotes a package that is required mostly for proper booting of the system or used for custom system-local meta-packages. dpkg(1) or any other installation tool will not allow a Protected package to be removed (at least not without using one of the force options). Supported since dpkg 1.20.1.

Essential: yes|no

This field is usually only needed when the answer is 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 Protected field instead). dpkg(1) or any other installation tool will not allow an Essential package to be removed (at least not without using one of the force options).

Build-Essential: yes|no

This field is usually only needed when the answer is yes, and is commonly injected by the archive software. It denotes a package that is required when building other packages.

Architecture: arch|all (required)

The architecture specifies which type of hardware this package was compiled for. Common architectures are amd64, armel, i386, powerpc, etc. Note that the all value is meant for packages that are architecture independent. Some examples of this are shell and Perl scripts, and documentation.

Origin: name

The name of the distribution this package is originating from.

Bugs: url

The url of the bug tracking system for this package. The current used format is bts-type://bts-address, like debbugs://bugs.debian.org.

Homepage: url

The upstream project home page url.

Tag: tag-list

List of tags describing the qualities of the package. The description and list of supported tags can be found in the debtags package.

Multi-Arch: no|same|foreign|allowed

This field is used to indicate how this package should behave on a multi-arch installations.

no

This value is the default when the field is omitted, in which case adding the field with an explicit no value is generally not needed.

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.

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 foreign is ignored).

allowed

This allows reverse-dependencies to indicate in their Depends field that they accept this package from a foreign architecture by qualifying the package name with :any, but has no effect otherwise.

Source: source-name [(source-version)]

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 source-name will be followed by a source-version in parenthesis. This can happen for example on a binary-only non-maintainer upload, or when setting a different binary version via «dpkg-gencontrol -v».

Subarchitecture: value

Kernel-Version: value

Installer-Menu-Item: value

These fields are used by the debian-installer and are usually not needed. For more details about them, see <https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt>.

Depends: 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 Depends field aren't installed (at least not without using the force options). In an installation, the postinst scripts of packages listed in 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 Depends field.

Pre-Depends: package-list

List of packages that must be installed 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.

Recommends: 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 Recommends field.

Suggests: 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.

The syntax of Depends, Pre-Depends, Recommends and Suggests fields is a list of groups of alternative packages. Each group is a list of packages separated by vertical bar (or “pipe”) symbols, ‘|’. 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 ‘:’, 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 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, any will match any architecture for that package name if the package has been marked as Multi-Arch: allowed.

A version number may start with a ‘>>’, 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 ‘>>’ for greater than, ‘<<’ for less than, ‘>=’ for greater than or equal to, ‘<=’ for less than or equal to, and ‘=’ for equal to.

Breaks: 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 Breaks field.

Conflicts: 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 Conflicts line mentioning the other.

Replaces: 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 Conflicts field to force removal of the other package, if this one also has the same files as the conflicted package.

The syntax of Breaks, Conflicts and Replaces is a list of package names, separated by commas (and optional whitespace). In the Breaks and 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 any instead of the binary package architecture. An optional version can also be given with the same syntax as above for the Breaks, Conflicts and Replaces fields.

Enhances: package-list

This is a list of packages that this one enhances. It is similar to Suggests but in the opposite direction.

Provides: 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 ‘|’ to separate the list.

The syntax of 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).

Built-Using: 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 ‘=’ version relationships enclosed within parenthesis. Note that the archive maintenance software is likely to refuse to accept an upload which declares a Built-Using relationship which cannot be satisfied within the archive.

Static-Built-Using: 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 ‘=’ version relationships enclosed within parenthesis. Supported since dpkg 1.21.3.

Built-For-Profiles: 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 .buildinfo file, which supersedes it.

Auto-Built-Package: 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 debian/control master source control file. The only currently used reason is debug-symbols.

Build-Ids: 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.

## 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).
```

## BUGS
The 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.

## SEE ALSO
deb822(5), deb-src-control(5), deb(5), deb-version(7), debtags(1), dpkg(1), dpkg-deb(1).


deb-extra-override

title: deb-extra-override(5)

summary: Debian archive extra override file

text:
# deb-extra-override(5)

## NAME
deb-extra-override - Debian archive extra override file

## SYNOPSIS
override

## DESCRIPTION
While most information about a binary/source package can be found in the control/.dsc file, all of it can be overridden when it's exported to Packages/Sources files. The extra override file contains those overrides.

The extra override file has a simple whitespace-delimited format. Comments are allowed (denoted with a #).

package field-name value

package is the name of the binary/source package.

field-name is the name of the field that is overridden.

value is the value to put in the field. It can contain spaces as the line is split in no more than 3 columns when it's parsed.

The extra override files used to make the official Packages lists may be found in the indices directory on any Debian mirror.

## SEE ALSO
dpkg-scanpackages(1), dpkg-scansources(1), apt-ftparchive(1).


title: deb-md5sums(5)

summary: package MD5 file digests

text:
# deb-md5sums(5)

## NAME
deb-md5sums - package MD5 file digests

## SYNOPSIS
DEBIAN/md5sums

## DESCRIPTION
A package declares the MD5 digests for the package file contents by including an md5sums file in its control archive (i.e. DEBIAN/md5sums during package creation). This file is used for integrity verification and deduplication purposes, and not for any kind of security purpose.

This file contains a list of MD5 digests (as 32 case-insensitive hexadecimal characters) followed by two spaces (U+0020 SPACE) and the absolute pathname of a plain file, one per line.

Trailing slashes (U+002F /) in the pathname will be trimmed. Neither trailing whitespace nor empty or whitespace-only lines are accepted.

If the control file does not exist in the binary package, dpkg(1) will generate the matching information at unpack time (since dpkg 1.16.3).

## EXAMPLE

```
 53c0d4afe4bc4eccb5cb234d2e06ef4d  usr/bin/dpkg
 f8da2bc74cdcad8b81c48a4f0d7bb0a8  usr/bin/dpkg-deb
 70b913132de56e95e75de504979309b4  usr/bin/dpkg-divert
 […]
```

## SEE ALSO
md5sum(1), dpkg-deb(1), dpkg(1).


deb-old

title: deb-old(5)

summary: old style Debian binary package format

text:
# deb-old(5)

## NAME
deb-old - old style Debian binary package format

## SYNOPSIS
filename.deb

## DESCRIPTION
The .deb format is the Debian binary package file format. This manual page describes the old format, used before Debian 0.93. Please see deb(5) for details of the new format.

## FORMAT
The file is two lines of format information as ASCII text, followed by two concatenated gzipped ustar files.

The first line is the format version number padded to 8 digits, and is 0.939000 for all old-format archives.

The second line is a decimal string (without leading zeroes) giving the length of the first gzipped tarfile.

Each of these lines is terminated with a single newline character.

The first tarfile contains the control information, as a series of ordinary files. The file control must be present, as it contains the core control information.

In some very old archives, the files in the control tarfile may optionally be in a DEBIAN subdirectory. In that case, the DEBIAN subdirectory will be in the control tarfile too, and the control tarfile will have only files in that directory. Optionally the control tarfile may contain an entry for ‘.’, that is, the current directory.

The second gzipped tarfile is the filesystem archive, containing pathnames relative to the root directory of the system to be installed on. The pathnames do not have leading slashes.

## SEE ALSO
deb(5), dpkg-deb(1), deb-control(5).


deb-origin

title: deb-origin(5)

summary: Vendor\-specific information files

text:
# deb-origin(5)

## NAME
deb-origin - Vendor-specific information files

## SYNOPSIS
/etc/dpkg/origins/filename

## DESCRIPTION
The files in /etc/dpkg/origins can provide information about various vendors who are providing Debian packages.

They contain a number of fields, or comments when the line starts with ‘#’. Each field begins with a tag, such as Vendor or Parent, followed by a colon and the body of the field. Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the tools will join lines when processing the body of the field.

The file should be named according to the vendor name. The usual convention is to name the vendor file using the vendor name in all lowercase, but some variation is permitted.

Namely (since dpkg 1.21.10), first, non-alphanumeric characters (‘[^A-Za-z0-9]’) are mapped to dashes (‘-’), then the resulting name will be tried in sequence by lower-casing it, keeping it as is, lower-casing then capitalizing it (that is upper-casing the first character), and only capitalizing it.

In addition, for historical and backwards compatibility, the name will be tried keeping it as is without non-alphanumeric characters remapping, then the resulting name will be tried in sequence by lower-casing it, keeping it as is, lower-casing then capitalizing it, and only capitalizing it. And finally the name will be tried by remapping spaces to dashes (‘-’), then the resulting name will be tried in sequence by lower-casing it, keeping it as is, lower-casing then capitalizing it, and only capitalizing it.

But these backwards compatible module lookups will be removed during the dpkg 1.22.x release cycle.

## FIELDS
Vendor: vendor-name (required)

The value of this field determines the vendor name.

Vendor-URL: vendor-url

The value of this field determines the vendor URL.

Bugs: bug-url

The value of this field determines the type and address of the bug tracking system used by this vendor. It can be a mailto URL or a debbugs URL (e.g., debbugs://bugs.debian.org/).

Parent: vendor-name

The value of this field determines the vendor name of the vendor that this vendor derives from.

## EXAMPLE

```
 Vendor: Debian
 Vendor-URL: https://www.debian.org/
 Bugs: debbugs://bugs.debian.org
```

## SEE ALSO
dpkg-vendor(1)


deb-override

title: deb-override(5)

summary: Debian archive override file

text:
# deb-override(5)

## NAME
deb-override - Debian archive override file

## SYNOPSIS
override

## DESCRIPTION
While most information about a package can be found in the control file, some is managed centrally by the distribution czars rather than by the maintainer in order to offer some global consistency. This information is found in the override file.

The override file has a simple whitespace-delimited format. Comments are allowed (denoted with a #).

package priority section [maintainer-info]

package is the name of the package. Entries in the override file for packages not found in the tree of binary packages are ignored.

priority and section correspond to the respective control fields available in the .deb. The allowed values are specific to each distribution archive.

maintainer-info, if present, can be either the name of a maintainer for an unconditional override, or else old-maintainer => new-maintainer to perform a substitution.

The override files used to make the official Packages lists may be found in the indices directory on any Debian mirror.

## SEE ALSO
dpkg-scanpackages(1), dpkg-scansources(1), apt-ftparchive(1).


deb-postinst

title: deb-postinst(5)

summary: package post\-installation maintainer script

text:
# deb-postinst(5)

## NAME
deb-postinst - package post-installation maintainer script

## SYNOPSIS
DEBIAN/postinst

## DESCRIPTION
A package can perform several post-installation actions via maintainer scripts, by including an executable postinst file in its control archive (i.e. DEBIAN/postinst during package creation).

The script can be called in the following ways:

postinst configure old-version

After the package was installed.

postinst triggered "trigger-name..."

After the package was triggered. The list of space-separated trigger-names is passed as the second argument.

old-postinst abort-upgrade new-version

If prerm fails during upgrade or fails on failed-upgrade.

old-postinst abort-remove

If prerm fails during remove.

postinst abort-deconfigure in-favour new-package new-version

[ removing old-package old-version ]

If prerm fails during deconfigure in-favour of a package.

postinst abort-remove in-favour new-package new-version

If prerm fails during remove in-favour for replacement due to conflict.

## SEE ALSO
dpkg(1).


deb-postrm

title: deb-postrm(5)

summary: package post\-removal maintainer script

text:
# deb-postrm(5)

## NAME
deb-postrm - package post-removal maintainer script

## SYNOPSIS
DEBIAN/postrm

## DESCRIPTION
A package can perform several post-removal actions via maintainer scripts, by including an executable postrm file in its control archive (i.e. DEBIAN/postrm during package creation).

The script can be called in the following ways:

postrm remove

After the package was removed.

postrm purge

After the package was purged.

old-postrm upgrade new-version

After the package was upgraded.

new-postrm failed-upgrade old-version new-version

If the above upgrade call fails. The new-version is passed only since dpkg 1.18.5.

postrm disappear overwriter-package overwriter-version

After all of the packages files have been replaced.

new-postrm abort-install

If preinst fails during install.

new-postrm abort-install old-version new-version

If preinst fails during install for an upgrade of a removed package. The new-version is passed only since dpkg 1.18.5.

new-postrm abort-upgrade old-version new-version

If preinst fails during upgrade. The new-version is passed only since dpkg 1.18.5.

## SEE ALSO
dpkg(1).


deb-preinst

title: deb-preinst(5)

summary: package pre\-installation maintainer script

text:
# deb-preinst(5)

## NAME
deb-preinst - package pre-installation maintainer script

## SYNOPSIS
DEBIAN/preinst

## DESCRIPTION
A package can perform several pre-installation actions via maintainer scripts, by including an executable preinst file in its control archive (i.e. DEBIAN/preinst during package creation).

The script can be called in the following ways:

new-preinst install

Before the package is installed.

new-preinst install old-version new-version

Before a removed package is upgraded. The new-version is passed only since dpkg 1.18.5.

new-preinst upgrade old-version new-version

Before the package is upgraded. The new-version is passed only since dpkg 1.18.5.

old-preinst abort-upgrade new-version

If postrm fails during upgrade or fails on failed upgrade.

## SEE ALSO
dpkg(1).


deb-prerm

title: deb-prerm(5)

summary: package pre\-removal maintainer script

text:
# deb-prerm(5)

## NAME
deb-prerm - package pre-removal maintainer script

## SYNOPSIS
DEBIAN/prerm

## DESCRIPTION
A package can perform several pre-removal actions via maintainer scripts, by including an executable prerm file in its control archive (i.e. DEBIAN/prerm during package creation).

The script can be called in the following ways:

prerm remove

Before the package is removed.

old-prerm upgrade new-version

Before an upgrade.

new-prerm failed-upgrade old-version new-version

If the above upgrade fails. The new-version is passed only since dpkg 1.18.5.

prerm deconfigure in-favour new-package new-version

[ removing old-package old-version ]

Before package is deconfigured while dependency is replaced due to conflict.

prerm remove in-favour new-package new-version

Before the package is replaced due to conflict.

## SEE ALSO
dpkg(1).


deb-shlibs

title: deb-shlibs(5)

summary: Debian shared library information file

text:
# deb-shlibs(5)

## NAME
deb-shlibs - Debian shared library information file

## SYNOPSIS
debian/shlibs, debian/binary-name.shlibs, DEBIAN/shlibs

## DESCRIPTION
shlibs files map shared library names and versions (SONAMEs) to dependencies suitable for a package control file. There is one entry per line. Blank lines are not allowed. Lines beginning with a # character are considered commentary, and are ignored. All other lines must have the format:

[type:] library version dependencies

The library and version fields are whitespace-delimited, but the dependencies field extends to the end of the line. The type field is optional and normally not needed.

The dependencies field has the same syntax as the Depends field in a binary control file, see deb-control(5).

## SONAME FORMATS
The SONAME formats supported are:

name.so.version

and

name-version.so

where name is usually prefixed by lib.

## EXAMPLES
The shlibs file for a typical library package, named libcrunch1, that provides one library whose SONAME is libcrunch.so.1, might read

```
 libcrunch 1 libcrunch1 (>= 1.2-1)
```

The dependencies must mention the most recent version of the package that added new symbols to the library: in the above example, new symbols were added to version 1.2 of libcrunch. This is not the only reason the dependencies might need to be tightened.

## SEE ALSO
deb-control(5), dpkg-shlibdeps(1), deb-symbols(5).


deb-split

title: deb-split(5)

summary: Debian multi\-part binary package format

text:
# deb-split(5)

## NAME
deb-split - Debian multi-part binary package format

## SYNOPSIS
filename.deb

## DESCRIPTION
The multi-part .deb format is used to split big packages into smaller pieces to ease transport in small media.

## FORMAT
The file is an ar archive with a magic value of !<arch>. The file names might contain a trailing slash (since dpkg 1.15.6).

The first member is named debian-split and contains a series of lines, separated by newlines. Currently eight lines are present:

- The format version number, 2.1 at the time this manual page was written.

- The package name.

- The package version.

- The md5sum of the package.

- The total size of the package.

- The maximum part size.

- The current part number, followed by a slash and the total amount of parts (as in ‘1/10’).

- The package architecture (since dpkg 1.16.1).

Programs which read multi-part archives should be prepared for the minor format version number to be increased and additional lines to be present, and should ignore these if this is the case.

If the major format version number has changed, an incompatible change has been made and the program should stop. If it has not, then the program should be able to safely continue, unless it encounters an unexpected member in the archive (except at the end), as described below.

The second, last required member is named data.N, where N denotes the part number. It contains the raw part data.

These members must occur in this exact order. Current implementations should ignore any additional members after data.N. Further members may be defined in the future, and (if possible) will be placed after these two.

## SEE ALSO
deb(5), dpkg-split(1).


deb-src-control

title: deb-src-control(5)

text:
# deb-src-control(5)

## NAME
deb-src-control - Debian source packages' master control file format

## SYNOPSIS
debian/control

## DESCRIPTION
Each Debian source package contains the master «debian/control» file, and its deb822(5) format is a superset of the control file shipped in Debian binary packages, see 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 Package or 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 Description field, see below). To insert empty lines into a multi-line field, insert a dot after the space. Lines starting with a ‘#’ are treated as comments.

## SOURCE FIELDS
Source: 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).

Maintainer: fullname-email (recommended)

Should be in the format «Joe Bloggs <jbloggs@foo.com>», and references the person who currently maintains the package, as opposed to the author of the software or the original packager.

Uploaders: fullname-email

Lists all the names and email addresses of co-maintainers of the package, in the same format as the Maintainer field. Multiple co-maintainers should be separated by a comma.

Standards-Version: version-string

This documents the most recent version of the distribution policy standards this package complies with.

Description short-description

long-description

The format for the source package description is a short brief summary on the first line (after the 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 ‘.’ following the preceding space.

Homepage: url

The upstream project home page URL.

Bugs: url

The url of the bug tracking system for this package. The current used format is bts-type://bts-address, like debbugs://bugs.debian.org. This field is usually not needed.

Rules-Requires-Root: no|binary-targets|impl-keywords

This field is used to indicate whether the debian/rules file requires (fake)root privileges to run some of its targets, and if so when.

no

The binary targets will not require (fake)root at all.

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 binary-targets while not strictly needed, marks it as having been analyzed for this requirement.

impl-keywords

This is a space-separated list of keywords which define when (fake)root is required. Keywords consist of namespace/cases. The namespace part cannot contain "/" or whitespace. The 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 rootless-builds.txt).

When the field is set to one of the impl-keywords, the builder will expose an interface that is used to run a command under (fake)root. (See "Gain Root API" in rootless-builds.txt.)

Testsuite: name-list

Testsuite-Triggers: package-list

These fields are described in the dsc(5) manual page, as they are generated from information inferred from debian/tests/control or copied literally to the source control file.

Vcs-Arch: url

Vcs-Bzr: url

Vcs-Cvs: url

Vcs-Darcs: url

Vcs-Git: url

Vcs-Hg: url

Vcs-Mtn: url

Vcs-Svn: url

The url of the Version Control System repository used to maintain this package. Currently supported are Arch, Bzr (Bazaar), Cvs, Darcs, Git, Hg (Mercurial), Mtn (Monotone) and Svn (Subversion). Usually this field points to the latest version of the package, such as the main branch or the trunk.

Vcs-Browser: url

The url of a webinterface to browse the Version Control System repository.

Origin: name

The name of the distribution this package is originating from. This field is usually not needed.

Section: section

This is a general field that gives the package a category based on the software that it installs. Some common sections are utils, net, mail, text, x11, etc.

Priority: priority

Sets the importance of this package in relation to the system as a whole. Common priorities are required, standard, optional, extra, etc. The Section and Priority fields usually have a defined set of accepted values based on the specific distribution policy.

Build-Depends: 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 Build-Depends-Arch and Build-Depends-Indep, because the dependency also needs to be satisfied when building the source package.

Build-Depends-Arch: package-list

Same as Build-Depends, but they are only needed when building the architecture dependent packages. The 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, Build-Depends should be used instead.

Build-Depends-Indep: package-list

Same as Build-Depends, but they are only needed when building the architecture independent packages. The Build-Depends are also installed in this case.

Build-Conflicts: 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 Build-Conflicts-Arch and Build-Conflicts-Indep, with the additional effect of being used for source-only builds.

Build-Conflicts-Arch: package-list

Same as 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, Build-Conflicts should be used instead.

Build-Conflicts-Indep: package-list

Same as Build-Conflicts, but only when building the architecture independent packages.

The syntax of the Build-Depends, Build-Depends-Arch and 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, ‘|’. The groups are separated by commas ‘,’, and can end with a trailing comma that will be eliminated when generating the fields for 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 ‘:’, optionally followed by a version number specification in parentheses ‘(’ and ‘)’, an architecture specification in square brackets ‘[’ and ‘]’, and a restriction formula consisting of one or more lists of profile names in angle brackets ‘<’ and ‘>’.

The syntax of the Build-Conflicts, Build-Conflicts-Arch and 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 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), any (since dpkg 1.16.2) or native (since dpkg 1.16.5). If omitted, the default for Build-Depends fields is the current host architecture, the default for Build-Conflicts fields is any. A real Debian architecture name will match exactly that architecture for that package name, any will match any architecture for that package name if the package is marked with Multi-Arch: allowed, and native will match the current build architecture if the package is not marked with Multi-Arch: foreign.

A version number may start with a ‘>>’, 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 ‘>>’ for greater than, ‘<<’ for less than, ‘>=’ for greater than or equal to, ‘<=’ for less than or equal to, and ‘=’ 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 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.

## BINARY FIELDS
Note that the Priority, Section and Homepage fields can also be in a binary stanza to override the global value from the source package.

Package: binary-package-name (required)

This field is used to name the binary package name. The same restrictions as to a source package name apply.

Package-Type: deb|udeb|type

This field defines the type of the package. udeb is for size-constrained packages used by the debian installer. deb is the default value, it is assumed if the field is absent. More types might be added in the future.

Architecture: arch|all|any (required)

The architecture specifies on which type of hardware this package runs. For packages that run on all architectures, use the any value. For packages that are architecture independent, such as shell and Perl scripts or documentation, use the 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 dpkg-architecture(1) for more information about them).

Build-Profiles: 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 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 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.

Protected: yes|no

Essential: yes|no

Build-Essential: yes|no

Multi-Arch: same|foreign|allowed|no

Tag: tag-list

Description: short-description (recommended)

These fields are described in the deb-control(5) manual page, as they are copied literally to the control file of the binary package.

Depends: package-list

Pre-Depends: package-list

Recommends: package-list

Suggests: package-list

Breaks: package-list

Enhances: package-list

Replaces: package-list

Conflicts: package-list

Provides: package-list

Built-Using: package-list

Static-Built-Using: package-list

These fields declare relationships between packages. They are discussed in the deb-control(5) manpage. When these fields are found in 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 deb-control(5).

Subarchitecture: value

Kernel-Version: value

Installer-Menu-Item: value

These fields are used by the debian-installer in udebs and are usually not needed. For more details about them, see <https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt>.

## 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 X, followed by zero or more of the letters SBC and a hyphen.

S

The field will appear in the source package control file, see dsc(5).

B

The field will appear in the control file in the binary package, see deb-control(5).

C

The field will appear in the upload control (.changes) file, see deb-changes(5).

Note that the X[SBC]- prefixes are stripped when the fields are copied over to the output files. A field XC-Approved-By will appear as 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 Private-, such as XB-Private-New-Field.

## 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.
```

## SEE ALSO
/usr/share/doc/dpkg/spec/rootless-builds.txt, deb822(5), deb-control(5), deb-version(7), dpkg-source(1)


deb-src-files

title: deb-src-files(5)

summary: Debian distribute files format

text:
# deb-src-files(5)

## NAME
deb-src-files - Debian distribute files format

## SYNOPSIS
debian/files

## DESCRIPTION
This file contains the list of artifacts that are to be distributed via the .changes control file.

The debian/files file has a simple whitespace-delimited format.

filename section priority [ keyword=value... ]

filename is the name of the artifact to distribute.

section and priority correspond to the respective control fields available in the .deb. The allowed values are specific to each distribution archive.

keyword=value... corresponds to an optional whitespace-delimited list of attributes for this entry. The only currently supported keyword is automatic with value yes, to mark automatically generated files.

## NOTES
This file is not intended to be modified directly, please use one of dpkg-gencontrol or dpkg-distaddfile to add entries to it.

## SEE ALSO
dpkg-genchanges(1), dpkg-distaddfile(1).


deb-src-rules

title: deb-src-rules(5)

summary: Debian source package rules file

text:
# deb-src-rules(5)

## NAME
deb-src-rules - Debian source package rules file

## SYNOPSIS
debian/rules

## DESCRIPTION
This file contains the instructions necessary to build the binary packages from the source package.

The debian/rules file is an executable Makefile, with a shebang that is usually set to "#!/usr/bin/make -f".

It must support the following make targets:

clean

Clean up the source tree, by undoing any change done by any of the build and binary targets. This target will be called with root privileges.

build-indep

Build architecture independent files required to build any architecture independent binary package. If there are no architecture independent binary packages to generate, the target must still exist but do nothing. This target must not require root privileges.

build-arch

Build architecture dependent files required to build any architecture dependent binary package. If there are no architecture dependent binary packages to generate, the target must still exist but do nothing. This target must not require root privileges.

build

Build architecture independent and dependent files, either by depending (at least transitively) on build-indep and/or build-arch or by inlining what those targets would do. This target must not require root privileges.

binary-indep

Build architecture independent binary packages. This target must depend (at least transitively) on either build-indep or build. This target will be called with root privileges.

binary-arch

Build architecture dependent binary packages. This target must depend (at least transitively) on either build-arch or build. This target will be called with root privileges.

binary

Build architecture independent and dependent binary packages, either by depending (at least transitively) on binary-indep and/or binary-arch or by inlining what those targets would do. This target will be called with root privileges.

## SEE ALSO
dpkg-architecture(1), dpkg-vendor(1), dpkg-buildflags(1), dpkg-parsechangelog(1), dpkg-shlibdeps(1), dpkg-gencontrol(1), dpkg-deb(1), dpkg-distaddfile(1).


deb-src-symbols

title: deb-src-symbols(5)

text:
# deb-src-symbols(5)

## NAME
deb-src-symbols - Debian's extended shared library template file

## SYNOPSIS
debian/package.symbols.arch, debian/symbols.arch, debian/package.symbols, debian/symbols

## DESCRIPTION
The symbol file templates are shipped in Debian source packages, and its format is a superset of the symbols files shipped in binary packages, see deb-symbols(5).

### Comments
Comments are supported in template symbol files. Any line with ‘#’ as the first character is a comment except if it starts with ‘#include’ (see section Using includes). Lines starting with ‘#MISSING:’ are special comments documenting symbols that have disappeared.

### Using #PACKAGE# substitution
In some rare cases, the name of the library varies between architectures. To avoid hardcoding the name of the package in the symbols file, you can use the marker #PACKAGE#. It will be replaced by the real package name during installation of the symbols files. Contrary to the #MINVER# marker, #PACKAGE# will never appear in a symbols file inside a binary package.

### Using symbol tags
Symbol tagging is useful for marking symbols that are special in some way. Any symbol can have an arbitrary number of tags associated with it. While all tags are parsed and stored, only some of them are understood by dpkg-gensymbols and trigger special handling of the symbols. See subsection Standard symbol tags for reference of these tags.

Tag specification comes right before the symbol name (no whitespace is allowed in between). It always starts with an opening bracket (, ends with a closing bracket ) and must contain at least one tag. Multiple tags are separated by the | character. Each tag can optionally have a value which is separated form the tag name by the = character. Tag names and values can be arbitrary strings except they cannot contain any of the special ) | = characters. Symbol names following a tag specification can optionally be quoted with either ' or " characters to allow whitespaces in them. However, if there are no tags specified for the symbol, quotes are treated as part of the symbol name which continues up until the first space.

```
  (tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
  (optional)tagged_unquoted_symbol@Base 1.0 1
  untagged_symbol@Base 1.0
```

The first symbol in the example is named tagged quoted symbol and has two tags: tag1 with value i am marked and tag name with space that has no value. The second symbol named tagged_unquoted_symbol is only tagged with the tag named optional. The last symbol is an example of the normal untagged symbol.

Since symbol tags are an extension of the deb-symbols(5) format, they can only be part of the symbols files used in source packages (those files should then be seen as templates used to build the symbols files that are embedded in binary packages). When dpkg-gensymbols is called without the -t option, it will output symbols files compatible to the deb-symbols(5) format: it fully processes symbols according to the requirements of their standard tags and strips all tags from the output. On the contrary, in template mode (-t) all symbols and their tags (both standard and unknown ones) are kept in the output and are written in their original form as they were loaded.

### Standard symbol tags
optional

A symbol marked as optional can disappear from the library at any time and that will never cause dpkg-gensymbols to fail. However, disappeared optional symbols will continuously appear as MISSING in the diff in each new package revision. This behaviour serves as a reminder for the maintainer that such a symbol needs to be removed from the symbol file or readded to the library. When the optional symbol, which was previously declared as MISSING, suddenly reappears in the next revision, it will be upgraded back to the “existing” status with its minimum version unchanged. This tag is useful for symbols which are private where their disappearance do not cause ABI breakage. For example, most of C++ template instantiations fall into this category. Like any other tag, this one may also have an arbitrary value: it could be used to indicate why the symbol is considered optional.

arch=architecture-list

arch-bits=architecture-bits

arch-endian=architecture-endianness

These tags allow one to restrict the set of architectures where the symbol is supposed to exist. The arch-bits and arch-endian tags are supported since dpkg 1.18.0. When the symbols list is updated with the symbols discovered in the library, all arch-specific symbols which do not concern the current host architecture are treated as if they did not exist. If an arch-specific symbol matching the current host architecture does not exist in the library, normal procedures for missing symbols apply and it may cause dpkg-gensymbols to fail. On the other hand, if the arch-specific symbol is found when it was not supposed to exist (because the current host architecture is not listed in the tag or does not match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits and arch-endian tags are dropped and the symbol will appear in the diff due to this change), but it is not considered as new. When operating in the default non-template mode, among arch-specific symbols only those that match the current host architecture are written to the symbols file. On the contrary, all arch-specific symbols (including those from foreign arches) are always written to the symbol file when operating in template mode.

The format of architecture-list is the same as the one used in the Build-Depends field of debian/control (except the enclosing square brackets []). For example, the first symbol from the list below will be considered only on alpha, any-amd64 and ia64 architectures, the second only on linux architectures, while the third one anywhere except on armel.

```
  (arch=alpha any-amd64 ia64)64bit_specific_symbol@Base 1.0
  (arch=linux-any)linux_specific_symbol@Base 1.0
  (arch=!armel)symbol_armel_does_not_have@Base 1.0

```

The architecture-bits is either 32 or 64.

```
  (arch-bits=32)32bit_specific_symbol@Base 1.0
  (arch-bits=64)64bit_specific_symbol@Base 1.0

```

The architecture-endianness is either little or big.

```
  (arch-endian=little)little_endian_specific_symbol@Base 1.0
  (arch-endian=big)big_endian_specific_symbol@Base 1.0

```

Multiple restrictions can be chained.

```
  (arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0

```

allow-internal

dpkg-gensymbols has a list of internal symbols that should not appear in symbols files as they are usually only side-effects of implementation details of the toolchain (since dpkg 1.20.1). If for some reason, you really want one of those symbols to be included in the symbols file, you should tag the symbol with allow-internal. It can be necessary for some low level toolchain libraries like “libgcc”.

ignore-blacklist

A deprecated alias for allow-internal (since dpkg 1.20.1, supported since dpkg 1.15.3).

c++

Denotes c++ symbol pattern. See Using symbol patterns subsection below.

symver

Denotes symver (symbol version) symbol pattern. See Using symbol patterns subsection below.

regex

Denotes regex symbol pattern. See Using symbol patterns subsection below.

### Using symbol patterns
Unlike a standard symbol specification, a pattern may cover multiple real symbols from the library. dpkg-gensymbols will attempt to match each pattern against each real symbol that does not have a specific symbol counterpart defined in the symbol file. Whenever the first matching pattern is found, all its tags and properties will be used as a basis specification of the symbol. If none of the patterns matches, the symbol will be considered as new.

A pattern is considered lost if it does not match any symbol in the library. By default this will trigger a dpkg-gensymbols failure under -c1 or higher level. However, if the failure is undesired, the pattern may be marked with the optional tag. Then if the pattern does not match anything, it will only appear in the diff as MISSING. Moreover, like any symbol, the pattern may be limited to the specific architectures with the arch tag. Please refer to Standard symbol tags subsection above for more information.

Patterns are an extension of the deb-symbols(5) format hence they are only valid in symbol file templates. Pattern specification syntax is not any different from the one of a specific symbol. However, symbol name part of the specification serves as an expression to be matched against name@version of the real symbol. In order to distinguish among different pattern types, a pattern will typically be tagged with a special tag.

At the moment, dpkg-gensymbols supports three basic pattern types:

c++

This pattern is denoted by the c++ tag. It matches only C++ symbols by their demangled symbol name (as emitted by c++filt(1) utility). This pattern is very handy for matching symbols which mangled names might vary across different architectures while their demangled names remain the same. One group of such symbols is non-virtual thunks which have architecture specific offsets embedded in their mangled names. A common instance of this case is a virtual destructor which under diamond inheritance needs a non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32bit architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64bit ones, it can be matched with a single c++ pattern:

```
 libdummy.so.1 libdummy1 #MINVER#
  [...]
  (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
  [...]

```

The demangled name above can be obtained by executing the following command:

```
  $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt

```

Please note that while mangled name is unique in the library by definition, this is not necessarily true for demangled names. A couple of distinct real symbols may have the same demangled name. For example, that's the case with non-virtual thunk symbols in complex inheritance configurations or with most constructors and destructors (since g++ typically generates two real symbols for them). However, as these collisions happen on the ABI level, they should not degrade quality of the symbol file.

symver

This pattern is denoted by the symver tag. Well maintained libraries have versioned symbols where each version corresponds to the upstream version where the symbol got added. If that's the case, you can use a symver pattern to match any symbol associated to the specific version. For example:

```
 libc.so.6 libc6 #MINVER#
  (symver)GLIBC_2.0 2.0
  [...]
  (symver)GLIBC_2.7 2.7
  access@GLIBC_2.0 2.2

```

All symbols associated with versions GLIBC_2.0 and GLIBC_2.7 will lead to minimal version of 2.0 and 2.7 respectively with the exception of the symbol access@GLIBC_2.0. The latter will lead to a minimal dependency on libc6 version 2.2 despite being in the scope of the "(symver)GLIBC_2.0" pattern because specific symbols take precedence over patterns.

Please note that while old style wildcard patterns (denoted by "*@version" in the symbol name field) are still supported, they have been deprecated by new style syntax "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should be written as "(symver|optional)GLIBC_2.0 2.0" if the same behaviour is needed.

regex

Regular expression patterns are denoted by the regex tag. They match by the perl regular expression specified in the symbol name field. A regular expression is matched as it is, therefore do not forget to start it with the ^ character or it may match any part of the real symbol name@version string. For example:

```
 libdummy.so.1 libdummy1 #MINVER#
  (regex)"^mystack_.*@Base$" 1.0
  (regex|optional)"private" 1.0

```

Symbols like "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base", etc., will be matched by the first pattern while "ng_mystack_new@Base" would not. The second pattern will match all symbols having the string "private" in their names and matches will inherit optional tag from the pattern.

Basic patterns listed above can be combined where it makes sense. In that case, they are processed in the order in which the tags are specified. For example, both:

```
  (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
  (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
```

will match symbols "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" and "_ZN3NSA6ClassA7Private11privmethod2Ei@Base". When matching the first pattern, the raw symbol is first demangled as C++ symbol, then the demangled name is matched against the regular expression. On the other hand, when matching the second pattern, regular expression is matched against the raw symbol name, then the symbol is tested if it is C++ one by attempting to demangle it. A failure of any basic pattern will result in the failure of the whole pattern. Therefore, for example, "__N3NSA6ClassA7Private11privmethod\dEi@Base" will not match either of the patterns because it is not a valid C++ symbol.

In general, all patterns are divided into two groups: aliases (basic c++ and symver) and generic patterns (regex, all combinations of multiple basic patterns). Matching of basic alias-based patterns is fast (O(1)) while generic patterns are O(N) (N - generic pattern count) for each symbol. Therefore, it is recommended not to overuse generic patterns.

When multiple patterns match the same real symbol, aliases (first c++, then symver) are preferred over generic patterns. Generic patterns are matched in the order they are found in the symbol file template until the first success. Please note, however, that manual reordering of template file entries is not recommended because dpkg-gensymbols generates diffs based on the alphanumerical order of their names.

### Using includes
When the set of exported symbols differ between architectures, it may become inefficient to use a single symbol file. In those cases, an include directive may prove to be useful in a couple of ways:

- You can factorize the common part in some external file and include that file in your package.symbols.arch file by using an include directive like this:

```
 #include "I<packages>.symbols.common"

```

- The include directive may also be tagged like any symbol:

```
 (tag|...|tagN)#include "file-to-include"

```

As a result, all symbols included from file-to-include will be considered to be tagged with tag ... tagN by default. You can use this feature to create a common package.symbols file which includes architecture specific symbol files:

```
  common_symbol1@Base 1.0
 (arch=amd64 ia64 alpha)#include "package.symbols.64bit"
 (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
  common_symbol2@Base 1.0

```

The symbols files are read line by line, and include directives are processed as soon as they are encountered. This means that the content of the included file can override any content that appeared before the include directive and that any content after the directive can override anything contained in the included file. Any symbol (or even another #include directive) in the included file can specify additional tags or override values of the inherited tags in its tag specification. However, there is no way for the symbol to remove any of the inherited tags.

An included file can repeat the header line containing the SONAME of the library. In that case, it overrides any header line previously read. However, in general it's best to avoid duplicating header lines. One way to do it is the following:

```
 #include "libsomething1.symbols.common"
  arch_specific_symbol@Base 1.0
```

## SEE ALSO
deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).


deb-substvars

title: deb-substvars(5)

summary: Debian source substitution variables

text:
# deb-substvars(5)

## NAME
deb-substvars - Debian source substitution variables

## SYNOPSIS
debian/substvars, debian/binary-package.substvars, variables

## DESCRIPTION
Before dpkg-source, dpkg-gencontrol and dpkg-genchanges write their control information (to the source control file .dsc for dpkg-source and to standard output for dpkg-gencontrol and dpkg-genchanges) they perform some variable substitutions on the output file.

### Variable Syntax
A variable substitution has the form ${variable-name}. Variable names consist of alphanumerics (a-zA-Z0-9), hyphens (-) and colons (:) and start with an alphanumeric, and are case-sensitive, even though they might refer to other entities which are case-preserving. Variable substitutions are performed repeatedly until none are left; the full text of the field after the substitution is rescanned to look for more substitutions.

### File Syntax
Substitution variables can be specified in a file. These files consist of lines of the form name=value or name?=value. The = operator assigns a normal substitution variable, while the ?= operator (since dpkg 1.21.8) assigns an optional substitution variable which will emit no warnings even if unused. Trailing whitespace on each line, blank lines, and lines starting with a # symbol (comments) are ignored.

### Substitution
Variables can be set using the -V common option. They can be also specified in the file debian/substvars (or whatever other file is specified using the -T common option).

After all the substitutions have been done each occurrence of the string ${} (which is not an actual substitution variable) is replaced with a $ sign. This can be used as an escape sequence such as ${}{VARIABLE} which will end up as ${VARIABLE} on the output.

If a variable is referred to but not defined it generates a warning and an empty value is assumed.

While variable substitution is done on all control fields, some of those fields are used and needed during the build when the substitution did not yet occur. That's why you can't use variables in the Package, Source and Architecture fields.

Variable substitution happens on the content of the fields after they have been parsed, thus if you want a variable to expand over multiple lines you do not have to include a space after the newline. This is done implicitly when the field is output. For example, if the variable ${Description} is set to "foo is bar.${Newline}foo is great." and if you have the following field:

```
 Description: foo application
  ${Description}
  .
  More text.
```

It will result in:

```
 Description: foo application
  foo is bar.
  foo is great.
  .
  More text.
```

### Built-in Variable
Additionally, the following standard variables are always available:

Arch

The current host architecture (i.e. the architecture the package is being built for, the equivalent of DEB_HOST_ARCH).

vendor:Name

The current vendor name (since dpkg 1.20.0). This value comes from the Vendor field for the current vendor's origin file, as dpkg-vendor(1) would retrieve it.

vendor:Id

The current vendor ID (since dpkg 1.20.0). This is just the lowercase variant of vendor:Name.

source:Version

The source package version (since dpkg 1.13.19).

source:Upstream-Version

The upstream source package version, including the Debian version epoch if any (since dpkg 1.13.19).

binary:Version

The binary package version (which may differ from source:Version in a binNMU for example; since dpkg 1.13.19).

Source-Version

The source package version (from the changelog file). This variable is now obsolete and emits an error when used as its meaning is different from its function, please use the source:Version or binary:Version as appropriate.

source:Synopsis

The source package synopsis, extracted from the source stanza Description field, if it exists (since dpkg 1.19.0).

source:Extended-Description

The source package extended description, extracted from the source stanza Description field, if it exists (since dpkg 1.19.0).

Installed-Size

The approximate total size of the package's installed files. This value is copied into the corresponding control file field; setting it will modify the value of that field. If this variable is not set dpkg-gencontrol will compute the default value by accumulating the size of each regular file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for any other filesystem object type. With hardlinks only being counted once as a regular file. Note: Take into account that this can only ever be an approximation, as the actual size used on the installed system will depend greatly on the filesystem used and its parameters, which might end up using either more or less space than the specified in this field.

Extra-Size

Additional disk space used when the package is installed. If this variable is set its value is added to that of the Installed-Size variable (whether set explicitly or using the default value) before it is copied into the Installed-Size control file field.

S:fieldname

The value of the source stanza field fieldname (which must be given in the canonical capitalization; since dpkg 1.18.11). Setting these variables has no effect other than on places where they are expanded explicitly. These variables are only available when generating binary control files.

F:fieldname

The value of the output field fieldname (which must be given in the canonical capitalization). Setting these variables has no effect other than on places where they are expanded explicitly.

Format

The .changes file format version generated by this version of the source packaging scripts. If you set this variable the contents of the Format field in the .changes file will change too.

Newline, Space, Tab

These variables each hold the corresponding character.

shlibs:dependencyfield

Variable settings with names of this form are generated by dpkg-shlibdeps.

dpkg:Upstream-Version

The upstream version of dpkg (since dpkg 1.13.19).

dpkg:Version

The full version of dpkg (since dpkg 1.13.19).

## FILES
debian/substvars

List of substitution variables and values.

## SEE ALSO
dpkg(1), dpkg-vendor(1), dpkg-genchanges(1), dpkg-gencontrol(1), dpkg-shlibdeps(1), dpkg-source(1).


deb-symbols

title: deb-symbols(5)

text:
# deb-symbols(5)

## NAME
deb-symbols - Debian's extended shared library information file

## SYNOPSIS
DEBIAN/symbols

## DESCRIPTION
The symbol files are shipped in Debian binary packages, and its format is a subset of the template symbol files used by dpkg-gensymbols(1) in Debian source packages, see deb-src-symbols(5).

The format for an extended shared library dependency information entry in these files is:

library-soname main-dependency-template

[| alternative-dependency-template]

[...]

[* field-name: field-value]

[...]

symbol minimal-version [id-of-dependency-template]

The library-soname is exactly the value of the SONAME field as exported by objdump(1). A dependency-template is a dependency where #MINVER# is dynamically replaced either by a version check like “(>= minimal-version)” or by nothing (if an unversioned dependency is deemed sufficient).

Each exported symbol (listed as name@version, with version being “Base” if the library is not versioned) is associated to a minimal-version of its dependency template (the main dependency template is always used and will end up being combined with the dependency template referenced by id-of-dependency-template if present). The first alternative dependency template is numbered 1, the second one 2, etc. Each column is separated by exactly a single whitespace.

Each entry for a library can also have some fields of meta-information. Those fields are stored on lines starting with an asterisk. Currently, the only valid fields are:

Build-Depends-Package

It indicates the name of the “-dev” package associated to the library and is used by dpkg-shlibdeps to make sure that the dependency generated is at least as strict as the corresponding build dependency (since dpkg 1.14.13).

Build-Depends-Packages

The same as Build-Depends-Package but accepts a comma-separated list of package names (since dpkg 1.20.0). This field will override any Build-Depends-Package field present, and is mostly useful with “-dev” packages and metapackages depending on these, say for a transition period.

Allow-Internal-Symbol-Groups

It indicates what internal symbol groups should be ignored, as a whitespace separated list, so that the symbols contained in those groups get included in the output file (since dpkg 1.20.1). This should only be necessary for toolchain packages providing those internal symbols. The available groups are system dependent, for ELF and GNU-based systems these are aeabi and gomp.

Ignore-Blacklist-Groups

A deprecated alias for Allow-Internal-Symbol-Groups (since dpkg 1.20.1, supported since dpkg 1.17.6).

## EXAMPLES

### Simple symbols file

```
 libftp.so.3 libftp3 #MINVER#
  DefaultNetbuf@Base 3.1-1-6
  FtpAccess@Base 3.1-1-6
  [...]
```

### Advanced symbols file

```
 libGL.so.1 libgl1
 | libgl1-mesa-glx #MINVER#
 * Build-Depends-Package: libgl1-mesa-dev
  publicGlSymbol@Base 6.3-1
  [...]
  implementationSpecificSymbol@Base 6.5.2-7 1
  [...]
```

## SEE ALSO
<https://wiki.debian.org/Projects/ImprovedDpkgShlibdeps>, deb-src-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).


deb-triggers

title: deb-triggers(5)

summary: package triggers

text:
# deb-triggers(5)

## NAME
deb-triggers - package triggers

## SYNOPSIS
debian/triggers, debian/binary-package.triggers, DEBIAN/triggers

## DESCRIPTION
A package declares its relationship to some trigger(s) by including a triggers file in its control archive (i.e. DEBIAN/triggers during package creation).

This file contains directives, one per line. Leading and trailing whitespace and everything after the first # on any line will be trimmed, and empty lines will be ignored.

The trigger control directives currently supported are:

interest trigger-name

interest-await trigger-name

interest-noawait trigger-name

Specifies that the package is interested in the named trigger. All triggers in which a package is interested must be listed using this directive in the triggers control file. The “await” variants put the triggering package in triggers-awaited state depending on how the trigger was activated. The “noawait” variant does not put the triggering packages in triggers-awaited state, even if the triggering package declared an “await” activation (either with an activate-await or activate directive, or by using the dpkg-trigger --no-await command-line option). The “noawait” variant should be used when the functionality provided by the trigger is not crucial.

activate trigger-name

activate-await trigger-name

activate-noawait trigger-name

Arranges that changes to this package's state will activate the specified trigger. The trigger will be activated at the start of the following operations: unpack, configure, remove (including for the benefit of a conflicting package), purge and deconfigure. The “await” variants only put the triggering package in triggers-awaited state if the interest directive is also “await”. The “noawait” variant never puts the triggering packages in triggers-awaited state. The “noawait” variant should be used when the functionality provided by the trigger is not crucial.

If this package disappears during the unpacking of another package the trigger will be activated when the disappearance is noted towards the end of the unpack. Trigger processing, and transition from triggers-awaited to installed, does not cause activations. In the case of unpack, triggers mentioned in both the old and new versions of the package will be activated.

Unknown directives are an error which will prevent installation of the package.

The “-noawait” variants should always be favored when possible since triggering packages are not put in triggers-awaited state and can thus be immediately configured without requiring the processing of the trigger. If the triggering packages are dependencies of other upgraded packages, it will avoid an early trigger processing run and make it possible to run the trigger only once as one of the last steps of the upgrade.

The “-noawait” variants are supported since dpkg 1.16.1, and will lead to errors if used with an older dpkg.

The “-await” alias variants are supported since dpkg 1.17.21, and will lead to errors if used with an older dpkg.

When a package provides an interest-noawait directive, any activation will set the triggering package into “noawait” mode, regardless of the awaiting mode requested by the activation (either “await” or “noawait”). When a package provides an interest or interest-await directive, any activation will set the triggering package into “await” or “noawait“ depending on how it was activated.

## SEE ALSO
dpkg-trigger(1), dpkg(1), /usr/share/doc/dpkg/spec/triggers.txt.