5.6.1.Source

This field identifies the source package name.

Indebian/control or a.dsc file, this field must contain onlythe name of the source package.

In a binary package control file or a.changes file, the sourcepackage name may be followed by a version number in parentheses.[4]This version number may be omitted (and is, bydpkg-gencontrol) ifit has the same value as theVersion field of the binary package inquestion. The field itself may be omitted from a binary package controlfile when the source package has the same name and version as the binarypackage.

Package names (both source and binary, seePackage) must consist only of lower caseletters (a-z), digits (0-9), plus (+) and minus (-)signs, and periods (.). They must be at least two characters longand must start with an alphanumeric character.

5.6.2.Maintainer

The package maintainer’s name and email address. The name must comefirst, then the email address inside angle brackets<> (in RFC822format).

If the maintainer’s name contains a full stop then the whole field willnot work directly as an email address due to a misfeature in the syntaxspecified in RFC822; a program using this field as an address must checkfor this and correct the problem if necessary (for example by puttingthe name in round brackets and moving it to the end, and bringing theemail address forward).

SeeThe maintainer of a package for additional requirements andinformation about package maintainers.

5.6.3.Uploaders

List of the names and email addresses of co-maintainers of the package,if any. If the package has other maintainers besides the one named intheMaintainer field, their names and emailaddresses should be listed here. The format of each entry is the same asthat of the Maintainer field, and multiple entries must be commaseparated.

This is normally an optional field, but if theMaintainer controlfield names a group of people and a shared email address, theUploaders field must be present and must contain at least one humanwith their personal email address.

The Uploaders field indebian/control can be folded.

5.6.4.Changed-By

The name and email address of the person who prepared this version ofthe package, usually a maintainer. The syntax is the same as for theMaintainer field.

5.6.5.Section

This field specifies an application area into which the package has beenclassified. SeeSections.

When it appears in thedebian/control file, it gives the value forthe subfield of the same name in theFiles field of the.changesfile. It also gives the default for the same field in the binarypackages.

5.6.6.Priority

This field represents how important it is that the user have the packageinstalled. SeePriorities.

When it appears in thedebian/control file, it gives the value forthe subfield of the same name in theFiles field of the.changesfile. It also gives the default for the same field in the binarypackages.

5.6.7.Package

The name of the binary package.

Binary package names must follow the same syntax and restrictions assource package names. SeeSource for thedetails.

5.6.8.Architecture

Depending on context and the control file used, theArchitecturefield can include the following sets of values:

• A unique single word identifying a Debian machine architecture asdescribed inArchitecture specification strings.

• An architecture wildcard identifying a set of Debian machinearchitectures, seeArchitecture wildcards.any matches all Debian machine architectures and is the mostfrequently used.

• all, which indicates an architecture-independent package.

• source, which indicates a source package.

In the maindebian/control file in the source package, this fieldmay contain the special valueall, the special architecture wildcardany, or a list of specific and wildcard architectures separated byspaces. Ifall orany appears, that value must be the entirecontents of the field. Most packages will use eitherall orany.

Specifying a specific list of architectures indicates that the sourcewill build an architecture-dependent package only on architecturesincluded in the list. Specifying a list of architecture wildcardsindicates that the source will build an architecture-dependent packageon only those architectures that match any of the specified architecturewildcards. Specifying a list of architectures or architecture wildcardsother thanany is for the minority of cases where a program is notportable or is not useful on some architectures. Where possible, theprogram should be made portable instead.

In the Debian source package control file.dsc, this field contains a listof architectures and architecture wildcards separated by spaces. Whenthe list contains the architecture wildcardany, the only othervalue allowed in the list isall.

The list may include (or consist solely of) the special valueall.In other words, in.dsc files unlike thedebian/control,allmay occur in combination with specific architectures. TheArchitecture field in the Debian source package control file.dsc isgenerally constructed from theArchitecture fields in thedebian/control in the source package.

Specifying onlyany indicates that the source package isn’tdependent on any particular architecture and should compile fine on anyone. The produced binary package(s) will be specific to whatever thecurrent build architecture is.

Specifying onlyall indicates that the source package will onlybuild architecture-independent packages.

Specifyinganyall indicates that the source package isn’t dependenton any particular architecture. The set of produced binary packages willinclude at least one architecture-dependent package and onearchitecture-independent package.

Specifying a list of architectures or architecture wildcards indicatesthat the source will build an architecture-dependent package, and willonly work correctly on the listed or matching architectures. If thesource package also builds at least one architecture-independentpackage,all will also be included in the list.

In a.changes file, theArchitecture field lists thearchitecture(s) of the package(s) currently being uploaded. This will bea list; if the source for the package is also being uploaded, thespecial entrysource is also present.all will be present if anyarchitecture-independent packages are being uploaded. Architecturewildcards such asany must never occur in theArchitecture fieldin the.changes file.

SeeMain building script: debian/rules for information on how to getthe architecture for the build process.

5.6.9.Essential

This is a boolean field which may occur only in the control file of abinary package or in a binary package stanza of a source packagetemplate control file.

If set toyes then the package management system will refuse toremove the package (upgrading and replacing it is still possible). Theother possible value isno, which is the same as not having thefield at all.

5.6.10.Package interrelationship fields:Depends,Pre-Depends,Recommends,Suggests,Breaks,Conflicts,Provides,Replaces,Enhances

These fields describe the package’s relationships with other packages.Their syntax and semantics are described inDeclaring relationships between packages.

5.6.11.Standards-Version

The most recent version of the standards (the policy manual andassociated texts) with which the package complies. SeeStandards conformance.

The version number has four components: major and minor version numberand major and minor patch level. When the standards change in a way thatrequires every package to change the major number will be changed.Significant changes that will require work in many packages will besignaled by a change to the minor number. The major patch level will bechanged for any change to the meaning of the standards, however small;the minor patch level will be changed when only cosmetic, typographicalor other edits are made which neither change the meaning of the documentnor affect the contents of packages.

Thus only the first three components of the policy version aresignificant in theStandards-Version control field, and so eitherthese three components or all four components may be specified.[5]

udebs and source packages that only produce udebs do not useStandards-Version.

5.6.12.Version

The version number of a package. The format is:[epoch:]upstream_version[-debian_revision].

The three components here are:

epoch

This is a single (generally small) unsigned integer. It may beomitted, in which case zero is assumed.

Epochs can help when the upstream version numbering schemechanges, but they must be used with care. You should not changethe epoch, even in experimental, without getting consensus ondebian-devel first.

upstream_version

This is the main part of the version number. It is usually theversion number of the original (“upstream”) package from which the.deb file has been made, if this is applicable. Usually thiswill be in the same format as that specified by the upstreamauthor(s); however, it may need to be reformatted to fit into thepackage management system’s format and comparison scheme.

The comparison behavior of the package management system withrespect to theupstream_version is described below. Theupstream_version portion of the version number is mandatory.

Theupstream_version must contain only alphanumerics[6] andthe characters.+-~ (full stop, plus, hyphen,tilde) and should start with a digit. If there is nodebian_revision then hyphens are not allowed.

debian_revision

This part of the version number specifies the version of the Debianpackage based on the upstream version. It must contain onlyalphanumerics and the characters+.~ (plus, full stop,tilde) and is compared in the same way as theupstream_version is.

It is conventional to restart thedebian_revision at1 eachtime theupstream_version is increased.

The package management system will break the version number apart atthe last hyphen in the string (if there is one) to determine theupstream_version anddebian_revision. The absence of adebian_revision is equivalent to adebian_revision of0.

Presence of thedebian_revision part indicates this package is anon-native package (seeSource packages). Absence indicatesthe package is a native package.

When comparing two version numbers, first the epoch of each arecompared, then theupstream_version if epoch is equal, and thendebian_revision ifupstream_version is also equal. epoch is comparednumerically. Theupstream_version anddebian_revision parts arecompared by the package management system using the following algorithm:

The strings are compared from left to right.

First the initial part of each string consisting entirely of non-digitcharacters is determined. These two parts (one of which may be empty)are compared lexically. If a difference is found it is returned. Thelexical comparison is a comparison of ASCII values modified so that allthe letters sort earlier than all the non-letters and so that a tildesorts before anything, even the end of a part. For example, thefollowing parts are in sorted order from earliest to latest:~~,~~a,~, the empty part,a.[7]

Then the initial part of the remainder of each string which consistsentirely of digit characters is determined. The numerical values ofthese two parts are compared, and any difference found is returned asthe result of the comparison. For these purposes an empty string (whichcan only occur at the end of one or both version strings being compared)counts as zero.

These two steps (comparing and removing initial non-digit strings andinitial digit strings) are repeated until a difference is found or bothstrings are exhausted.

5.6.13.Description

In a source template control file or binary control file, theDescriptionfield contains a description of the binary package, consisting of two parts,the synopsis or the short description, and the long description. It is amultiline field with the following format:

Description: single line synopsis extended description over several lines

The lines in the extended description can have these formats:

• Those starting with a single space are part of a paragraph.Successive lines of this form will be word-wrapped when displayed.The leading space will usually be stripped off. The line must containat least one non-whitespace character.

• Those starting with two or more spaces. These will be displayedverbatim. If the display cannot be panned horizontally, thedisplaying program will line wrap them “hard” (i.e., without takingaccount of word breaks). If it can they will be allowed to trail offto the right. None, one or two initial spaces may be deleted, but thenumber of spaces deleted from each line will be the same (so that youcan have indenting work correctly, for example). The line mustcontain at least one non-whitespace character.

• Those containing a single space followed by a single full stopcharacter. These are rendered as blank lines. This is theonly wayto get a blank line.[9]

• Those containing a space, a full stop and some more characters. Theseare for future expansion. Do not use them.

Do not use tab characters. Their effect is not predictable.

SeeThe description of a package for further information onthis.

In a.changes file, theDescription field contains a summary ofthe descriptions of the binary packages being uploaded. If no binarypackages are being uploaded, this field will not be present.

When used inside a.changes file, theDescription field has adifferent format than in source or binary control files. It is a multilinefield with one line per binary package. The first line of the field value(the part on the same line asDescription:) is always empty. Eachsubsequent line is indented by one space and contains the name of a binarypackage, a space, a hyphen (-), a space, and the short descriptionline from that package.

5.6.14.Distribution

In a.changes file or parsed changelog output this contains the(space-separated) name(s) of the distribution(s) where this version ofthe package should be installed. Valid distributions are determined bythe archive maintainers.[10] The Debian archive software onlysupports listing a single distribution. Migration of packages to otherdistributions is handled outside of the upload process.

5.6.15.Date

This field includes the date the package was built or last edited. Itmust be in the same format as the date in adebian/changelog entry.

The value of this field is usually extracted from thedebian/changelog file - seeDebian changelog: debian/changelog).

5.6.16.Format

In.changes files, this field declares the format version ofthat file. The syntax of the field value is the same as that of apackage version number except that no epoch orDebian revision is allowed. The format described in this document is1.8.

In.dsc Debian source control files, this field declares the format of the sourcepackage. The field value is used by programs acting on a sourcepackage to interpret the list of files in the source package anddetermine how to unpack it. The syntax of the field value is a numericmajor revision, a period, a numeric minor revision, and then anoptional subtype after whitespace, which if specified is analphanumeric word in parentheses. The subtype is optional in thesyntax but may be mandatory for particular source format revisions.[11]

5.6.17.Urgency

This is a description of how important it is to upgrade to this versionfrom previous ones. It consists of a single keyword taking one of thevalueslow,medium,high,emergency, orcritical[12] (not case-sensitive) followed by an optional commentary(separated by a space) which is usually in parentheses. For example:

Urgency:low (HIGH for users of diversions)

The value of this field is usually extracted from thedebian/changelog file - seeDebian changelog: debian/changelog.

5.6.18.Changes

This multiline field contains the human-readable changes data,describing the differences between the last version and the current one.

The first line of the field value (the part on the same line asChanges:) is always empty. The content of the field is expressed ascontinuation lines, with each line indented by at least one space. Blanklines must be represented by a line consisting only of a space and afull stop (.).

The value of this field is usually extracted from thedebian/changelog file - seeDebian changelog: debian/changelog.

Each version’s change information should be preceded by a “title” linegiving at least the version, distribution(s) and urgency, in ahuman-readable way.

If data from several versions is being returned the entry for the mostrecent version should be returned first, and entries should be separatedby the representation of a blank line (the “title” line may also befollowed by the representation of a blank line).

5.6.19.Binary

This folded field is a list of binary packages. Its syntax and meaningvaries depending on the control file in which it appears.

When it appears in the.dsc file, it lists binary packages which asource package can produce, separated by commas[13]. The sourcepackage does not necessarily produce all of these binary packages forevery architecture. The source control file doesn’t contain details ofwhich architectures are appropriate for which of the binary packages.

When it appears in a.changes file, it lists the names of the binarypackages being uploaded, separated by whitespace (not commas). If nobinary packages are being uploaded, this field will not be present.

5.6.20.Installed-Size

This field appears in the binary package control files, and in thePackages files. It gives an estimate of the total amount of diskspace required to install the named package. Actual installed size mayvary based on block size, file system properties, or actions taken bypackage maintainer scripts.

The disk space is given as the accumulated size of each regular file andsymlink rounded to 1 KiB used units, and a baseline of 1 KiB for any otherfilesystem object type.

5.6.21.Files

This field contains a list of files with information about each one. Theexact information and syntax varies with the context.

In all cases,Files is a multiline field. The first line of the fieldvalue (the part on the same line asFiles:) is always empty. Thecontent of the field is expressed as continuation lines, one line perfile. Each line must be indented by one space and contain a number ofsub-fields, separated by spaces, as described below.

In the.dsc file, each line contains the MD5 checksum, size andfilename of the tar file and (if applicable) diff file which make up theremainder of the source package.[14] For example:

Files:c6f698f19f2a2aa07dbb9bbda90a2754571925example_1.2.orig.tar.gz938512f08422f3509ff36f125f5873ba6220example_1.2-1.diff.gz

The exact forms of the filenames are described inSource packages as archives.

In the.changes file this contains one line per file being uploaded.Each line contains the MD5 checksum, size, section and priority and thefilename. For example:

Files:4c31ab7bfc40d3cf49d78119873903571428textextraexample_1.2-1.dscc6f698f19f2a2aa07dbb9bbda90a2754571925textextraexample_1.2.orig.tar.gz938512f08422f3509ff36f125f5873ba6220textextraexample_1.2-1.diff.gz7c98fe853b3bbb47a00e5cd129b6cb56703542textextraexample_1.2-1_i386.deb

Thesection andpriority are thevalues of the corresponding fields in the source template control file. Ifno section or priority is specified then- should be used, thoughsection and priority values must be specified for new packages to beinstalled properly.

The special valuebyhand for the section in a.changes fileindicates that the file in question is not an ordinary package file andmust be installed by hand by the distribution maintainers. If thesection isbyhand the priority should be-.

If a new Debian revision of a package is being shipped and no neworiginal source archive is being distributed the.dsc must stillcontain theFiles field entry for the original source archivepackage_upstream-version.orig.tar.gz, but the.changes fileshould leave it out. In this case the original source archive on thedistribution site must match exactly, byte-for-byte, the original sourcearchive which was used to generate the.dsc file and diff which arebeing uploaded.

5.6.22.Closes

A space-separated list of bug report numbers that the upload governed bythe.changes file closes.

5.6.23.Homepage

The URL of the web site for this package, preferably (when applicable)the site from which the original source can be obtained and anyadditional upstream documentation or information may be found. Thecontent of this field is a simple URL without any surrounding characterssuch as<>.

5.6.24.Checksums-Sha1 andChecksums-Sha256

These multiline fields contain a list of files with a checksum and sizefor each one. BothChecksums-Sha1 andChecksums-Sha256 have thesame syntax and differ only in the checksum algorithm used: SHA-1 forChecksums-Sha1 and SHA-256 forChecksums-Sha256.

Checksums-Sha1 andChecksums-Sha256 are multiline fields. Thefirst line of the field value (the part on the same line asChecksums-Sha1: orChecksums-Sha256:) is always empty. Thecontent of the field is expressed as continuation lines, one line perfile. Each line consists of the checksum, a space, the file size, aspace, and the file name. For example (from a.changes file):

Checksums-Sha1:1f418afaa01464e63cc1ee8a66a05f0848bd155c1276example_1.0-1.dsca0ed1456fad61116f868b1855530dbe948e20f06171602example_1.0.orig.tar.gz5e86ecf0671e113b63388dac81dd8d00e00ef2986137example_1.0-1.debian.tar.gz71a0ff7da0faaf608481195f9cf30974b142c183548402example_1.0-1_i386.debChecksums-Sha256:ac9d57254f7e835bed299926fd51bf6f534597cc3fcc52db01c4bffedae812721276example_1.0-1.dsc0d123be7f51e61c4bf15e5c492b484054be7e90f3081608a5517007bfb1fd128171602example_1.0.orig.tar.gzf54ae966a5f580571ae7d9ef5e1df0bd42d63e27cb505b27957351a495bc62886137example_1.0-1.debian.tar.gz3bec05c03974fdecd11d020fc2e8250de8404867a8a2ce865160c250eb723664548402example_1.0-1_i386.deb

In the.dsc file, these fields list all files that make up thesource package. In the.changes file, these fields list all filesbeing uploaded. The list of files in these fields must match the list offiles in theFiles field.

5.6.25.DM-Upload-Allowed

Obsolete, seebelow.

5.6.26.Version Control System (VCS) fields

Debian source packages are increasingly developed using VCSs. Thepurpose of the following fields is to indicate a publicly accessiblerepository where the Debian source package is developed.

Vcs-Browser

URL of a web interface for browsing the repository.

Vcs-<type>

The field name identifies the VCS. The field’s value uses the versioncontrol system’s conventional syntax for describing repositorylocations and should be sufficient to locate the repository used forpackaging. Ideally, it also locates the branch used for development ofnew versions of the Debian package.

The following values for <type> are supported, with the correspondingVCS indicated in parentheses if it isn’t obvious:

• Arch

• Bzr (Bazaar)

• Cvs (CVS)

• Darcs

• Git

• Hg (Mercurial)

• Mtn (Monotone)

• Svn (Subversion)

In the case of Git, the value must have the following syntax:

<url>[" -b "<branch>][" ["<path>"]"]

where the portions enclosed in brackets are optional and the portionsenclosed in double quotes are literal strings.<url> indicatesthe repository. If the<branch> portion is present, it names abranch in the indicated repository. If no branch is specified, thepackaging should be on the default branch. If the<path> portionis present, it specifies the relative path to the top of the packagingtree (the parent directory of thedebian directory). If no pathis specified, it defaults to. (the top level of the indicatedrepository and branch).

For example:

Vcs-Git:https://example.org/repo -b debian [p/package]

indicates a subdirectory namedp/package in thedebian branchof the repository athttps://example.org/repo.

In the case of Mercurial, the value must have the following syntax:

<url>[" -b "<branch>]

This is interpreted the same way as the Git syntax except a pathwithin the repository is not supported.

A package control file must not have more than oneVcs-<type>field. If the package is maintained in multiple version controlsystems, the maintainer should specify the one that they wouldprefer other people to use as the basis for proposing changes tothe package.

For both fields, any URLs given should use a scheme that providesconfidentiality (https, for example, rather thanhttp orgit)if the VCS repository supports it.

5.6.27.Package-List

Multiline field listing all the packages that can be built from thesource package, considering every architecture. The first line of thefield value is empty. Each one of the next lines describes one binarypackage, by listing its name, type, section and priority separated byspaces. Fifth and subsequent space-separated items may be present andparsers must allow them. See thePackage-Typefield for a list of package types.

5.6.28.Package-Type

Simple field containing a word indicating the type of package:debfor binary packages andudeb for micro binary packages. Other typesnot defined here may be indicated. In source package template control files,thePackage-Type field should be omitted instead of giving it a value ofdeb, as this value is assumed for stanzas lacking this field.

5.6.29.Dgit

Folded field containing a single git commit hash, presented in full,followed optionally by whitespace and other data to be defined in futureextensions.

Declares that the source package corresponds exactly to a referencedcommit in a Git repository available at the canonical location calleddgit-repos, used bydgit, a bidirectional gateway between theDebian archive and Git. The commit is reachable from at least onereference whose name matchesrefs/dgit/*. See the manual page ofdgit for further details.

5.6.30.Testsuite

Simple field containing a comma-separated list of values allowing testexecution environments to discover packages which provide tests.

This field is automatically added to Debian source control files(.dsc) bydpkg, with the valueautopkgtest, when adebian/tests/control file is present in the source package. Thisfield may also be used in source package template control files(debian/control) if needed in other situations.

5.6.31.Rules-Requires-Root

Simple field that defines if the source package requires access toroot (or fakeroot) during selected targets in theMain buildingscript: debian/rules.

The field can consist of exactly one of the following three items:

• no (default): Declares that neither root nor fakeroot is required.Package builders (e.g. dpkg-buildpackage) may choose to invoke any targetindebian/rules with an unprivileged user.

• binary-targets (previous default): Declares that thepackage will need the root (or fakeroot) when either of thebinary,binary-arch orbinary-indep targets are called. This is how everytool behaved before this field was defined.

• A space separated list of keywords described below. These keywordsmust always contain a forward slash, which sets them apart from theother possible values ofRules-Requires-Root. When this listis provided, the builder must provide a “gain root command” (asdefined indebian/rules and Rules-Requires-Root)or pretend that the value was settobinary-targets, and both the builder and the package’sdebian/rules script must downgrade accordingly (see below).

The default depends on the dpkg-build-api level (see dpkg-build-api(7)).If the dpkg-build-api level is undeclared, it is equivalent to level 0.

If the package builder supports theRules-Requires-Root field andwants to enable the feature, then it must set the environment variableDEB_RULES_REQUIRES_ROOT when invoking the package building scriptdebian/rules. The value ofDEB_RULES_REQUIRES_ROOT should beone of:

• The value ofRules-Requires-Root if the builder can supportthat value. The builder may trim unnecessary whitespace used toformat the field for readability.

• The valuebinary-targets if it cannot support the value ofRules-Requires-Root.

A compliant builder may also leaveDEB_RULES_REQUIRES_ROOT unsetor set it tobinary-targets if it has been requested to testwhether the package it builds correctly implements the fall-back forlegacy builders.

5.8.1.DM-Upload-Allowed

Indicates that Debian Maintainers may upload this package to the Debianarchive. The only valid value isyes. This field was used toregulate uploads by Debian Maintainers, See the General ResolutionEndorse the concept of DebianMaintainers for moredetails.

dpkg’s internal databases are in a similar format.

The stanzas somtimes used to be referred to as paragraphs, but thatcaused confusion with text paragraphs in prose, so it is now considereda discouraged term.

This folding method is similar to RFC 5322, allowing control filesthat contain only one stanza and no multiline fields to be read byparsers written for RFC 5322.

It is customary to leave a space after the package name if a versionnumber is specified.

In the past, people specified the full version number in theStandards-Version field, for example “2.3.0.0”. Since minorpatch-level changes don’t introduce new policy, it was thought itwould be better to relax policy and only require the first 3components to be specified, in this example “2.3.0”. All fourcomponents may still be used if someone wishes to do so.

Alphanumerics areA-Za-z0-9 only.

One common use of~ is for upstream pre-releases. For example,1.0~beta1~svn1245 sorts earlier than1.0~beta1, which sortsearlier than1.0.

The author of this manual has heard of a package whose versions went1.1,1.2,1.3,1,2.1,2.2,2 and soforth.

Completely empty lines will not be rendered as blank lines. Instead,they will cause the parser to think you’re starting a whole newrecord in the control file, and will therefore likely abort with anerror.

Example distribution names in the Debian archive used in.changesfiles are:

unstable

This distribution value refers to thedevelopmental part of theDebian distribution tree. Most new packages, new upstreamversions of packages and bug fixes go into theunstabledirectory tree.

experimental

The packages with this distribution value are deemed by theirmaintainers to be high risk. Oftentimes they represent early betaor developmental packages from various sources that themaintainers want people to try, but are not ready to be a part ofthe other parts of the Debian distribution tree.

Others are used for updating stable releases or for security uploads.More information is available in the Debian Developer’s Reference,section “The Debian archive”.

The source formats currently supported by the Debian archive softwareare1.0,3.0(native), and3.0(quilt).

Other urgency values are supported with configuration changes in thearchive software but are not used in Debian. The urgency affects howquickly a package will be considered for inclusion into thetesting distribution and gives an indication of the importance ofany fixes included in the upload.Emergency andcritical aretreated as synonymous.

A space after each comma is conventional.

That is, the parts which are not the.dsc.