3.Binary packages
The Debian distribution is based on the Debian package managementsystem, calleddpkg. Thus, all packages in the Debian distributionmust be provided in the.deb file format.
A.deb package contains two sets of files: a set of files to installon the system when the package is installed, and a set of files thatprovide additional metadata about the package or which are executed whenthe package is installed or removed. This second set of files is calledpackage metadata files. Among those files are the package maintainerscripts andcontrol, thebinary package control file that contains the control fields for thepackage. Other package metadata files includesymbols orshlibs used tostore shared library dependency information and theconffiles filethat lists the package’s configuration files (described inConfiguration files).
There is unfortunately a collision of terminology here between controlinformation files and files in the Debian control file format.Throughout this document, acontrol file refers to a file in theDebian control file format. These files are documented inControl files and their fields. Only filesreferred to specifically aspackage metadata files are the filesincluded in the package metadata member (calledcontrol.tar) of the.deb file format used by binary packages. Most package metadata filesare not in the Debian control file format.
3.1.The package name
Every package must have a name that’s unique within the Debian archive.
The package name is included in the control fieldPackage, theformat of which is described inPackage. Thepackage name is also included as a part of the file name of the.debfile.
3.1.1.Packages with potentially offensive content
As a maintainer you should make a judgement about whether the contentsof a package is appropriate to include, whether it needs any kind ofcontent warning, and whether some parts should be split out into aseparate package (so that users who want to avoid certain parts can doso). In making these decisions you should take into account theproject’s views as expressed in our Diversity Statement.
If you split out (potentially) offensive or disturbing material into aseparate package, you should usually mark this in the package name byadding-offensive. For example,cowsay vscowsay-offensive. In this situation the-offensive packagecan be Suggested by the core package(s), but should not be Recommendedor Depended on.
3.2.The version of a package
Every package has a version number recorded in itsVersion controlfile field, described inVersion.
The package management system imposes an ordering on version numbers, sothat it can tell whether packages are being up- or downgraded and sothat package system front end applications can tell whether a package itfinds available is newer than the one installed on the system. Theversion number format has the most significant parts (as far ascomparison is concerned) at the beginning.
If an upstream package has problematic version numbers they should beconverted to a sane form for use in theVersion field.
3.2.1.Version numbers based on dates
In general, Debian packages should use the same version numbers as theupstream sources. However, upstream version numbers based on some dateformats (sometimes used for development or “snapshot” releases) will notbe ordered correctly by the package management software. For example,dpkg will consider “96May01” to be greater than “96Dec24”.
To prevent having to use epochs for every new upstream version, thedate-based portion of any upstream version number should be given in away that sorts correctly: four-digit year first, followed by a two-digitnumeric month, followed by a two-digit numeric date, possibly withpunctuation between the components.
Native Debian packages (i.e., packages which have been writtenespecially for Debian) whose version numbers include dates should alsofollow these rules. If punctuation is desired between the datecomponents, remember that hyphen (-) cannot be used in nativeversion numbers. Period (.) is normally a good choice.
3.2.2.Uniqueness of version numbers
The part of the version number after the epoch must not be reused fora version of the package with different contents once the package hasbeen accepted into the archive, even if the version of the packagepreviously using that part of the version number is no longer presentin any archive suites.
This uniqueness requirement applies to the version numbers of sourcepackages and of binary packages, even if the source package producinga given binary package changes. Thus the version numbers which abinary package must not reuse includes the version numbers of anyversions of the binary package ever accepted into the archive, underany source package.
Additionally, for non-native packages, the upstream version must notbe reused for different upstream source code, so that for each sourcepackage name and upstream version number there exists exactly oneoriginal source archive contents (seeFiles).
The reason for these restrictions is as follows. Epochs are notincluded in the names of the files that compose source packages, or inthe filenames of binary packages, so reusing a version number, even ifthe epoch differs, results in identically named files with differentcontents. This can cause various problems.
If you find yourself wanting to reuse the part of a version numberafter the epoch, you can just increment the Debian revision, whichdoesn’t need to start at 1 or be consecutive.
3.3.The maintainer of a package
Every package must have a maintainer, except for orphaned packages asdescribed below. The maintainer may be one person or a group of peoplereachable from a common email address, such as a mailing list. Themaintainer is responsible for maintaining the Debian packaging files,evaluating and responding appropriately to reported bugs, uploading newversions of the package (either directly or through a sponsor), ensuringthat the package is placed in the appropriate archive area and includedin Debian releases as appropriate for the stability and utility of thepackage, and requesting removal of the package from the Debiandistribution if it is no longer useful or maintainable.
The maintainer must be specified in theMaintainer control fieldwith their correct name and a working email address. The email addressgiven in theMaintainer control field must accept mail from thoserole accounts in Debian used to send automated mails regarding thepackage. This includes non-spam mail from the bug-tracking system, allmail from the Debian archive maintenance software, and other roleaccounts or automated processes that are commonly agreed on by theproject.[1] If one person or team maintains several packages, theyshould use the same form of their name and email address in theMaintainer fields of those packages.
The format of theMaintainer control field is described inMaintainer.
If the maintainer of the package is a team of people with a shared emailaddress, theUploaders control field must be present and mustcontain at least one human with their personal email address. SeeUploaders for the syntax of that field.
An orphaned package is one with no current maintainer. Orphaned packagesshould have theirMaintainer control field set toDebianQAGroup<packages@qa.debian.org>. These packages are consideredmaintained by the Debian project as a whole until someone elsevolunteers to take over maintenance.[2]
3.4.The description of a package
Every Debian package must have aDescription control field whichcontains a synopsis and extended description of the package. Technicalinformation about the format of theDescription field is inDescription.
The description should describe the package (the program) to a user(system administrator) who has never met it before so that they haveenough information to decide whether they want to install it. Thisdescription should not just be copied verbatim from the program’sdocumentation.
Put important information first, both in the synopsis and extendeddescription. Sometimes only the first part of the synopsis or of thedescription will be displayed. You can assume that there will usually bea way to see the whole extended description.
The description should also give information about the significantdependencies and conflicts between this package and others, so that theuser knows why these dependencies and conflicts have been declared.
Instructions for configuring or using the package should not be included(that is what installation scripts, manual pages, info files, etc., arefor). Copyright statements and other administrivia should not beincluded either (that is what the copyright file is for).
3.4.1.The single line synopsis
The single line synopsis should be kept brief—certainly under 80characters.
Do not include the package name in the synopsis line. The displaysoftware knows how to display this already, and you do not need to stateit. Remember that in many situations the user may only see the synopsisline - make it as informative as you can.
3.4.2.The extended description
Do not try to continue the single line synopsis into the extendeddescription. This will not work correctly when the full description isdisplayed, and makes no sense where only the summary (the single linesynopsis) is available.
The extended description should describe what the package does and howit relates to the rest of the system (in terms of, for example, whichsubsystem it is which part of).
The description field needs to make sense to anyone, even people whohave no idea about any of the things the package deals with.[3]
3.5.Dependencies
Every package must specify the dependency information about otherpackages that are required for the first to work correctly.
For example, a dependency entry must be provided for any sharedlibraries required by a dynamically-linked executable binary in apackage.
Packages are not required to declare any dependencies they have on otherpackages which are markedEssential (see below), and should not doso unless they depend on a particular version of that package.[4]
Sometimes, unpacking one package requires that another package be firstunpackedand configured. In this case, the depending package mustspecify this dependency in thePre-Depends control field.
You should not specify aPre-Depends entry for a package before thishas been discussed on thedebian-devel mailing list and a consensusabout doing that has been reached.
The format of the package interrelationship control fields is describedinDeclaring relationships between packages.
3.6.Virtual packages
Sometimes, there are several packages which offer more-or-less the samefunctionality. In this case, it’s useful to define avirtual packagewhose name describes that common functionality. (The virtual packagesonly exist logically, not physically; that’s why they are calledvirtual.) The packages with this particular function will thenprovide the virtual package. Thus, any other package requiring thatfunction can simply depend on the virtual package without having tospecify all possible packages individually.
All packages should use virtual package names where appropriate, andarrange to create new ones if necessary. They should not use virtualpackage names (except privately, amongst a cooperating group ofpackages) unless they have been agreed upon and appear in the list ofvirtual package names. (See alsoVirtual packages - Provides)
The latest version of the authoritative list of virtual package namescan be found in thedebian-policy package. It is also available fromthe Debian web mirrors athttps://www.debian.org/doc/packaging-manuals/virtual-package-names-list.yaml.
The procedure for updating the list is described in the preface to thelist.
3.7.Base system
Thebasesystem is a minimum subset of the Debian system that isinstalled before everything else on a new system. Only very few packagesare allowed to form part of the base system, in order to keep therequired disk usage very small.
The base system consists of all those packages with priorityrequired orimportant. Many of them will be taggedessential(see below).
3.8.Essential packages
Essential is defined as the minimal set of functionality that must beavailable and usable on the system at all times, even when packages arein the “Unpacked” state. Packages are taggedessential for a systemusing theEssential control field. The format of theEssentialcontrol field is described inEssential.
Since these packages cannot be easily removed (one has to specify anextraforce option todpkg to do so), this flag must not be usedunless absolutely necessary. A shared library package must not be taggedessential; dependencies will prevent its premature removal, and weneed to be able to remove it when it has been superseded.
Since dpkg will not prevent upgrading of other packages while anessential package is in an unconfigured state, allessentialpackages must supply all of their core functionality even whenunconfigured after being configured at least once. If the package cannotsatisfy this requirement it must not be tagged as essential, and anypackages depending on this package must instead have explicit dependencyfields as appropriate.
Maintainers should take great care in adding any programs, interfaces,or functionality toessential packages. Packages may assume thatfunctionality provided byessential packages is always availablewithout declaring explicit dependencies, which means that removingfunctionality from the Essential set is very difficult and is almostnever done. Any capability added to anessential package thereforecreates an obligation to support that capability as part of theEssential set in perpetuity.
You must not tag any packagesessential before this has beendiscussed on thedebian-devel mailing list and a consensus aboutdoing that has been reached.
3.9.Maintainer Scripts
The package installation scripts should avoid producing output which isunnecessary for the user to see and should rely ondpkg to stave offboredom on the part of a user installing many packages. This means,amongst other things, not passing the--verbose option toupdate-alternatives.
Errors which occur during the execution of an installation script mustbe checked and the installation must not continue after an error.
Note that in generalScripts applies to packagemaintainer scripts, too.
You should not usedpkg-divert on a file belonging to anotherpackage without consulting the maintainer of that package first. Whenadding or removing diversions, package maintainer scripts must providethe--package flag todpkg-divert and must not use--local.
All packages which supply an instance of a common command name (or, ingeneral, filename) should generally useupdate-alternatives so thatthey can be installed together. Ifupdate-alternatives is not used,then each package must useConflicts to ensure that other packagesare removed. (In this case, it may be appropriate to specify a conflictagainst earlier versions of something that previously did not useupdate-alternatives; this is an exception to the usual rule thatversioned conflicts should be avoided.)
Diversions are primarily intended as a tool for local administrators and localpackages to override the behavior of Debian. While there are somecircumstances where one Debian package may need to divert a file installed byanother Debian package, such circumstances are rare. Maintainers shouldstrongly prefer using other overriding mechanisms, instead of diversions,whenever those other mechanisms are sufficient to accomplish the same goal. Inother words, diversions in packages should be considered a last resort.Diversion of a file in one Debian package by another Debian package should becoordinated between the maintainers of those packages.
One specific case of this rule is that configuration files used bysystemdcomponents, such asunits,udev rules,tmpfiles.d,modules-load.d,sysusersand other such files, including those specific to systemd daemons(e.g.:/etc/systemd/system.conf).must not be diverted by any Debian package. Instead, usemasking and drop-ins.
Alternatives must not be used forsystemd configuration files. Thealternatives system does not know how to apply changes to services when updatingalternatives, so the resulting behavior would be confusing and unpredictable.Instead,aliasescan be used to provide alternative implementations of the same named unit.
3.9.1.Prompting in maintainer scripts
Package maintainer scripts may prompt the user if necessary. Promptingmust be done by communicating through a program, such asdebconf,which conforms to the Debian Configuration Management Specification,version 2 or higher.
Packages which are essential, or which are dependencies of essentialpackages, may fall back on another prompting method if no such interfaceis available when they are executed.
The Debian Configuration Management Specification is included in thedebconf_specification files in the debian-policy package. It is alsoavailable from the Debian web mirrors athttps://www.debian.org/doc/packaging-manuals/debconf_specification.html.
Packages which use the Debian Configuration Management Specification maycontain the additional package metadata filesconfig andtemplates.config is an additional maintainer script used forpackage configuration, andtemplates contains templates used foruser prompting. Theconfig script might be run before thepreinst script and before the package is unpacked or any of itsdependencies or pre-dependencies are satisfied. Therefore it must workusing only the tools present inessential packages.[5]
Packages which use the Debian Configuration Management Specificationmust allow for translation of their user-visible messages by using agettext-based system such as the one provided by the po-debconf package.
Packages should try to minimize the amount of prompting they need to do,and they should ensure that the user will only ever be asked eachquestion once. This means that packages should try to use appropriateshared configuration files (such as/etc/papersize and/etc/news/server), and shared debconf variables rather than eachprompting for their own list of required pieces of information.
It also means that an upgrade should not ask the same questions again,unless the user has useddpkg--purge to remove the package’sconfiguration. The answers to configuration questions should be storedin an appropriate place in/etc so that the user can modify them,and how this has been done should be documented.
If a package has a vitally important piece of information to pass to theuser (such as “don’t run me as I am, you must edit the followingconfiguration files first or you risk your system emittingbadly-formatted messages”), it should display this in theconfig orpostinst script and prompt the user to hit return to acknowledge themessage. Copyright messages do not count as vitally important (theybelong in/usr/share/doc/PACKAGE/copyright); neither do instructionson how to use a program (these should be in on-line documentation, whereall the users can see them).
Any necessary prompting should almost always be confined to theconfig orpostinst script. If it is done in thepostinst, itshould be protected with a conditional so that unnecessary promptingdoesn’t happen if a package’s installation fails and thepostinst iscalled withabort-upgrade,abort-remove orabort-deconfigure.
A sample implementation of such a whitelist written for the Mailmanmailing list management software is used for mailing lists hosted byhttps://alioth-lists.debian.net/.
[2]The detailed procedure for gracefully orphaning a package can befound in the Debian Developer’s Reference (seeRelated documents).
[3]The blurb that comes with a program in its announcements and/orREADME files is rarely suitable for use in a description. It isusually aimed at people who are already in the community where thepackage is used.
Essential is needed in part to avoid unresolvable dependency loops onupgrade. If packages add unnecessary dependencies on packages in thisset, the chances that therewill be an unresolvable dependencyloop caused by forcing these Essential packages to be configuredfirst before they need to be is greatly increased. It also increasesthe chances that frontends will be unable tocalculate an upgradepath, even if one exists.
Also, functionality is rarely ever removed from the Essential set,butpackages have been removed from the Essential set when thefunctionality moved to a different package. So depending on thesepackagesjust in case they stop being essential does way more harmthan good.
[5]Debconf or another tool that implements the Debian ConfigurationManagement Specification will also be installed, and any versioneddependencies on it will be satisfied before preconfiguration begins.