4 The Debian distribution is based on the Debian package management
5 system, called ``dpkg``. Thus, all packages in the Debian distribution
6 must be provided in the ``.deb`` file format.
8 A ``.deb`` package contains two sets of files: a set of files to install
9 on the system when the package is installed, and a set of files that
10 provide additional metadata about the package or which are executed when
11 the package is installed or removed. This second set of files is called
12 *control information files*. Among those files are the package maintainer
13 scripts and ``control``, the :ref:`binary package control file
14 <s-binarycontrolfiles>` that contains the control fields for the
15 package. Other control information files include :ref:`symbols
16 <s-sharedlibs-symbols>` or :ref:`shlibs <s-sharedlibs-shlibdeps>` used to
17 store shared library dependency information and the ``conffiles`` file
18 that lists the package's configuration files (described in
19 :ref:`s-config-files`).
21 There is unfortunately a collision of terminology here between control
22 information files and files in the Debian control file format.
23 Throughout this document, a *control file* refers to a file in the
24 Debian control file format. These files are documented in
25 :doc:`Control files and their fields <ch-controlfields>`. Only files
26 referred to specifically as *control information files* are the files
27 included in the control information file member of the ``.deb`` file
28 format used by binary packages. Most control information files are not
29 in the Debian control file format.
36 Every package must have a name that's unique within the Debian archive.
38 The package name is included in the control field ``Package``, the
39 format of which is described in :ref:`s-f-Package`. The
40 package name is also included as a part of the file name of the ``.deb``
45 Packages with potentially offensive content
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48 As a maintainer you should make a judgement about whether the contents
49 of a package is appropriate to include, whether it needs any kind of
50 content warning, and whether some parts should be split out into a
51 separate package (so that users who want to avoid certain parts can do
52 so). In making these decisions you should take into account the
53 project's views as expressed in our Diversity Statement.
55 If you split out (potentially) offensive or disturbing material into a
56 separate package, you should usually mark this in the package name by
57 adding ``-offensive``. For example, ``cowsay`` vs
58 ``cowsay-offensive``. In this situation the ``-offensive`` package
59 can be Suggested by the core package(s), but should not be Recommended
64 The version of a package
65 ------------------------
67 Every package has a version number recorded in its ``Version`` control
68 file field, described in :ref:`s-f-Version`.
70 The package management system imposes an ordering on version numbers, so
71 that it can tell whether packages are being up- or downgraded and so
72 that package system front end applications can tell whether a package it
73 finds available is newer than the one installed on the system. The
74 version number format has the most significant parts (as far as
75 comparison is concerned) at the beginning.
77 If an upstream package has problematic version numbers they should be
78 converted to a sane form for use in the ``Version`` field.
82 Version numbers based on dates
83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
85 In general, Debian packages should use the same version numbers as the
86 upstream sources. However, upstream version numbers based on some date
87 formats (sometimes used for development or "snapshot" releases) will not
88 be ordered correctly by the package management software. For example,
89 ``dpkg`` will consider "96May01" to be greater than "96Dec24".
91 To prevent having to use epochs for every new upstream version, the
92 date-based portion of any upstream version number should be given in a
93 way that sorts correctly: four-digit year first, followed by a two-digit
94 numeric month, followed by a two-digit numeric date, possibly with
95 punctuation between the components.
97 Native Debian packages (i.e., packages which have been written
98 especially for Debian) whose version numbers include dates should also
99 follow these rules. If punctuation is desired between the date
100 components, remember that hyphen (``-``) cannot be used in native
101 package versions. Period (``.``) is normally a good choice.
105 The maintainer of a package
106 ---------------------------
108 Every package must have a maintainer, except for orphaned packages as
109 described below. The maintainer may be one person or a group of people
110 reachable from a common email address, such as a mailing list. The
111 maintainer is responsible for maintaining the Debian packaging files,
112 evaluating and responding appropriately to reported bugs, uploading new
113 versions of the package (either directly or through a sponsor), ensuring
114 that the package is placed in the appropriate archive area and included
115 in Debian releases as appropriate for the stability and utility of the
116 package, and requesting removal of the package from the Debian
117 distribution if it is no longer useful or maintainable.
119 The maintainer must be specified in the ``Maintainer`` control field
120 with their correct name and a working email address. The email address
121 given in the ``Maintainer`` control field must accept mail from those
122 role accounts in Debian used to send automated mails regarding the
123 package. This includes non-spam mail from the bug-tracking system, all
124 mail from the Debian archive maintenance software, and other role
125 accounts or automated processes that are commonly agreed on by the
126 project. [#]_ If one person or team maintains several packages, they
127 should use the same form of their name and email address in the
128 ``Maintainer`` fields of those packages.
130 The format of the ``Maintainer`` control field is described in
131 :ref:`s-f-Maintainer`.
133 If the maintainer of the package is a team of people with a shared email
134 address, the ``Uploaders`` control field must be present and must
135 contain at least one human with their personal email address. See
136 :ref:`s-f-Uploaders` for the syntax of that field.
138 An orphaned package is one with no current maintainer. Orphaned packages
139 should have their ``Maintainer`` control field set to ``Debian QA Group <packages@qa.debian.org>``. These packages are considered
140 maintained by the Debian project as a whole until someone else
141 volunteers to take over maintenance. [#]_
145 The description of a package
146 ----------------------------
148 Every Debian package must have a ``Description`` control field which
149 contains a synopsis and extended description of the package. Technical
150 information about the format of the ``Description`` field is in
151 :ref:`s-f-Description`.
153 The description should describe the package (the program) to a user
154 (system administrator) who has never met it before so that they have
155 enough information to decide whether they want to install it. This
156 description should not just be copied verbatim from the program's
159 Put important information first, both in the synopsis and extended
160 description. Sometimes only the first part of the synopsis or of the
161 description will be displayed. You can assume that there will usually be
162 a way to see the whole extended description.
164 The description should also give information about the significant
165 dependencies and conflicts between this package and others, so that the
166 user knows why these dependencies and conflicts have been declared.
168 Instructions for configuring or using the package should not be included
169 (that is what installation scripts, manual pages, info files, etc., are
170 for). Copyright statements and other administrivia should not be
171 included either (that is what the copyright file is for).
175 The single line synopsis
176 ~~~~~~~~~~~~~~~~~~~~~~~~
178 The single line synopsis should be kept brief---certainly under 80
181 Do not include the package name in the synopsis line. The display
182 software knows how to display this already, and you do not need to state
183 it. Remember that in many situations the user may only see the synopsis
184 line - make it as informative as you can.
188 The extended description
189 ~~~~~~~~~~~~~~~~~~~~~~~~
191 Do not try to continue the single line synopsis into the extended
192 description. This will not work correctly when the full description is
193 displayed, and makes no sense where only the summary (the single line
194 synopsis) is available.
196 The extended description should describe what the package does and how
197 it relates to the rest of the system (in terms of, for example, which
198 subsystem it is which part of).
200 The description field needs to make sense to anyone, even people who
201 have no idea about any of the things the package deals with. [#]_
208 Every package must specify the dependency information about other
209 packages that are required for the first to work correctly.
211 For example, a dependency entry must be provided for any shared
212 libraries required by a dynamically-linked executable binary in a
215 Packages are not required to declare any dependencies they have on other
216 packages which are marked ``Essential`` (see below), and should not do
217 so unless they depend on a particular version of that package. [#]_
219 Sometimes, unpacking one package requires that another package be first
220 unpacked *and* configured. In this case, the depending package must
221 specify this dependency in the ``Pre-Depends`` control field.
223 You should not specify a ``Pre-Depends`` entry for a package before this
224 has been discussed on the ``debian-devel`` mailing list and a consensus
225 about doing that has been reached.
227 The format of the package interrelationship control fields is described
228 in :doc:`Declaring relationships between packages <ch-relationships>`.
235 Sometimes, there are several packages which offer more-or-less the same
236 functionality. In this case, it's useful to define a *virtual package*
237 whose name describes that common functionality. (The virtual packages
238 only exist logically, not physically; that's why they are called
239 *virtual*.) The packages with this particular function will then
240 *provide* the virtual package. Thus, any other package requiring that
241 function can simply depend on the virtual package without having to
242 specify all possible packages individually.
244 All packages should use virtual package names where appropriate, and
245 arrange to create new ones if necessary. They should not use virtual
246 package names (except privately, amongst a cooperating group of
247 packages) unless they have been agreed upon and appear in the list of
248 virtual package names. (See also :ref:`s-virtual`)
250 The latest version of the authoritative list of virtual package names
251 can be found in the ``debian-policy`` package. It is also available from
252 the Debian web mirrors at
253 https://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt.
255 The procedure for updating the list is described in the preface to the
263 The ``base system`` is a minimum subset of the Debian system that is
264 installed before everything else on a new system. Only very few packages
265 are allowed to form part of the base system, in order to keep the
266 required disk usage very small.
268 The base system consists of all those packages with priority
269 ``required`` or ``important``. Many of them will be tagged ``essential``
277 Essential is defined as the minimal set of functionality that must be
278 available and usable on the system at all times, even when packages are
279 in the "Unpacked" state. Packages are tagged ``essential`` for a system
280 using the ``Essential`` control field. The format of the ``Essential``
281 control field is described in :ref:`s-f-Essential`.
283 Since these packages cannot be easily removed (one has to specify an
284 extra *force option* to ``dpkg`` to do so), this flag must not be used
285 unless absolutely necessary. A shared library package must not be tagged
286 ``essential``; dependencies will prevent its premature removal, and we
287 need to be able to remove it when it has been superseded.
289 Since dpkg will not prevent upgrading of other packages while an
290 ``essential`` package is in an unconfigured state, all ``essential``
291 packages must supply all of their core functionality even when
292 unconfigured. If the package cannot satisfy this requirement it must not
293 be tagged as essential, and any packages depending on this package must
294 instead have explicit dependency fields as appropriate.
296 Maintainers should take great care in adding any programs, interfaces,
297 or functionality to ``essential`` packages. Packages may assume that
298 functionality provided by ``essential`` packages is always available
299 without declaring explicit dependencies, which means that removing
300 functionality from the Essential set is very difficult and is almost
301 never done. Any capability added to an ``essential`` package therefore
302 creates an obligation to support that capability as part of the
303 Essential set in perpetuity.
305 You must not tag any packages ``essential`` before this has been
306 discussed on the ``debian-devel`` mailing list and a consensus about
307 doing that has been reached.
314 The package installation scripts should avoid producing output which is
315 unnecessary for the user to see and should rely on ``dpkg`` to stave off
316 boredom on the part of a user installing many packages. This means,
317 amongst other things, not passing the ``--verbose`` option to
318 ``update-alternatives``.
320 Errors which occur during the execution of an installation script must
321 be checked and the installation must not continue after an error.
323 Note that in general :ref:`s-scripts` applies to package
324 maintainer scripts, too.
326 You should not use ``dpkg-divert`` on a file belonging to another
327 package without consulting the maintainer of that package first. When
328 adding or removing diversions, package maintainer scripts must provide
329 the ``--package`` flag to ``dpkg-divert`` and must not use ``--local``.
331 All packages which supply an instance of a common command name (or, in
332 general, filename) should generally use ``update-alternatives``, so that
333 they may be installed together. If ``update-alternatives`` is not used,
334 then each package must use ``Conflicts`` to ensure that other packages
335 are removed. (In this case, it may be appropriate to specify a conflict
336 against earlier versions of something that previously did not use
337 ``update-alternatives``; this is an exception to the usual rule that
338 versioned conflicts should be avoided.)
340 .. _s-maintscriptprompt:
342 Prompting in maintainer scripts
343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345 Package maintainer scripts may prompt the user if necessary. Prompting
346 must be done by communicating through a program, such as ``debconf``,
347 which conforms to the Debian Configuration Management Specification,
350 Packages which are essential, or which are dependencies of essential
351 packages, may fall back on another prompting method if no such interface
352 is available when they are executed.
354 The Debian Configuration Management Specification is included in the
355 ``debconf_specification`` files in the debian-policy package. It is also
356 available from the Debian web mirrors at
357 https://www.debian.org/doc/packaging-manuals/debconf_specification.html.
359 Packages which use the Debian Configuration Management Specification may
360 contain the additional control information files ``config`` and
361 ``templates``. ``config`` is an additional maintainer script used for
362 package configuration, and ``templates`` contains templates used for
363 user prompting. The ``config`` script might be run before the
364 ``preinst`` script and before the package is unpacked or any of its
365 dependencies or pre-dependencies are satisfied. Therefore it must work
366 using only the tools present in *essential* packages. [#]_
368 Packages which use the Debian Configuration Management Specification
369 must allow for translation of their user-visible messages by using a
370 gettext-based system such as the one provided by the po-debconf package.
372 Packages should try to minimize the amount of prompting they need to do,
373 and they should ensure that the user will only ever be asked each
374 question once. This means that packages should try to use appropriate
375 shared configuration files (such as ``/etc/papersize`` and
376 ``/etc/news/server``), and shared debconf variables rather than each
377 prompting for their own list of required pieces of information.
379 It also means that an upgrade should not ask the same questions again,
380 unless the user has used ``dpkg --purge`` to remove the package's
381 configuration. The answers to configuration questions should be stored
382 in an appropriate place in ``/etc`` so that the user can modify them,
383 and how this has been done should be documented.
385 If a package has a vitally important piece of information to pass to the
386 user (such as "don't run me as I am, you must edit the following
387 configuration files first or you risk your system emitting
388 badly-formatted messages"), it should display this in the ``config`` or
389 ``postinst`` script and prompt the user to hit return to acknowledge the
390 message. Copyright messages do not count as vitally important (they
391 belong in ``/usr/share/doc/package/copyright``); neither do instructions
392 on how to use a program (these should be in on-line documentation, where
393 all the users can see them).
395 Any necessary prompting should almost always be confined to the
396 ``config`` or ``postinst`` script. If it is done in the ``postinst``, it
397 should be protected with a conditional so that unnecessary prompting
398 doesn't happen if a package's installation fails and the ``postinst`` is
399 called with ``abort-upgrade``, ``abort-remove`` or
400 ``abort-deconfigure``.
403 A sample implementation of such a whitelist written for the Mailman
404 mailing list management software is used for mailing lists hosted by
408 The detailed procedure for gracefully orphaning a package can be
409 found in the Debian Developer's Reference (see
413 The blurb that comes with a program in its announcements and/or
414 ``README`` files is rarely suitable for use in a description. It is
415 usually aimed at people who are already in the community where the
419 Essential is needed in part to avoid unresolvable dependency loops on
420 upgrade. If packages add unnecessary dependencies on packages in this
421 set, the chances that there **will** be an unresolvable dependency
422 loop caused by forcing these Essential packages to be configured
423 first before they need to be is greatly increased. It also increases
424 the chances that frontends will be unable to **calculate** an upgrade
425 path, even if one exists.
427 Also, functionality is rarely ever removed from the Essential set,
428 but *packages* have been removed from the Essential set when the
429 functionality moved to a different package. So depending on these
430 packages *just in case* they stop being essential does way more harm
434 Debconf or another tool that implements the Debian Configuration
435 Management Specification will also be installed, and any versioned
436 dependencies on it will be satisfied before preconfiguration begins.