<p>
Essential is defined as the minimal set of functionality that
must be available and usable on the system at all times, even
- when packages are in an unconfigured (but unpacked) state.
+ when packages are in the "Unpacked" state.
Packages are tagged <tt>essential</tt> for a system using the
<tt>Essential</tt> control field. The format of the
<tt>Essential</tt> control field is described in <ref
The package installation scripts should avoid producing
output which is unnecessary for the user to see and
should rely on <prgn>dpkg</prgn> to stave off boredom on
- the part of a user installing many packages. This means,
- amongst other things, using the <tt>--quiet</tt> option on
- <prgn>install-info</prgn>.
+ the part of a user installing many packages. This means,
+ amongst other things, not passing the <tt>--verbose</tt>
+ option to <prgn>update-alternatives</prgn>.
</p>
<p>
installed together. If <prgn>update-alternatives</prgn>
is not used, then each package must use
<tt>Conflicts</tt> to ensure that other packages are
- de-installed. (In this case, it may be appropriate to
+ removed. (In this case, it may be appropriate to
specify a conflict against earlier versions of something
that previously did not use
<prgn>update-alternatives</prgn>; this is an exception to
<p>
The following targets are required and must be implemented
by <file>debian/rules</file>: <tt>clean</tt>, <tt>binary</tt>,
- <tt>binary-arch</tt>, <tt>binary-indep</tt>, and <tt>build</tt>.
+ <tt>binary-arch</tt>, <tt>binary-indep</tt>, <tt>build</tt>,
+ <tt>build-arch</tt> and <tt>build-indep</tt>.
These are the targets called by <prgn>dpkg-buildpackage</prgn>.
</p>
composed of US-ASCII characters excluding control characters,
space, and colon (i.e., characters in the ranges 33-57 and
59-126, inclusive). Field names must not begin with the comment
- character, <tt>#</tt>.
+ character, <tt>#</tt>, nor with the hyphen character, <tt>-</tt>.
</p>
<p>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
<item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
<item><qref id="f-VCS-fields"><tt>Vcs-Browser</tt>, <tt>Vcs-Git</tt>, et al.</qref></item>
+ <item><qref id="f-Dgit"><tt>Dgit</tt></qref></item>
<item><qref id="f-Standards-Version"><tt>Standards-Version</tt></qref> (recommended)</item>
<item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
<item><qref id="f-Package-List"><tt>Package-List</tt></qref> (recommended)</item>
this value is assumed for paragraphs lacking this field.
</p>
</sect1>
+
+ <sect1 id="f-Dgit">
+ <heading><tt>Dgit</tt></heading>
+
+ <p>
+ Folded field containing a single git commit hash, presented in
+ full, followed optionally by whitespace and other data to be
+ defined in future extensions.
+ </p>
+
+ <p>
+ Declares that the source package corresponds exactly to a
+ referenced commit in a Git repository available at the canonical
+ location called <em>dgit-repos</em>, used by <prgn>dgit</prgn>, a
+ bidirectional gateway between the Debian archive and Git. The
+ commit is reachable from at least one reference whose name matches
+ <tt>refs/dgit/*</tt>. See the manual page of <prgn>dgit</prgn> for
+ further details.
+ </p>
+ </sect1>
</sect>
<sect>
Programs called from maintainer scripts should not normally
have a path prepended to them. Before installation is
started, the package management system checks to see if the
- programs <prgn>ldconfig</prgn>,
- <prgn>start-stop-daemon</prgn>, <prgn>install-info</prgn>,
+ programs <prgn>ldconfig</prgn>, <prgn>start-stop-daemon</prgn>,
and <prgn>update-rc.d</prgn> can be found via the
<tt>PATH</tt> environment variable. Those programs, and any
other program that one would expect to be in the
pre-dependencies (<tt>Pre-Depends</tt>) may be assumed to be
available. Pre-dependencies will have been configured at
least once, but at the time the <prgn>preinst</prgn> is
- called they may only be in an unpacked or "Half-Configured"
+ called they may only be in an "Unpacked" or "Half-Configured"
state if a previous version of the pre-dependency was
completely configured and has not been removed since then.
</item>
partly from the new version or partly missing, so the script
cannot rely on files included in the package. Package
dependencies may not be available. Pre-dependencies will be
- at least unpacked following the same rules as above, except
+ at least "Unpacked" following the same rules as above, except
they may be only "Half-Installed" if an upgrade of the
pre-dependency failed.<footnote>
This can happen if the new version of the package no
<var>most-recently-configured-version</var></tag>
<item>
The files contained in the package will be unpacked. All
- package dependencies will at least be unpacked. If there
+ package dependencies will at least be "Unpacked". If there
are no circular dependencies involved, all package
dependencies will be configured. For behavior in the case
of circular dependencies, see the discussion
will have previously been configured and not removed.
However, dependencies may not be configured or even fully
unpacked in some error situations.<footnote>
- For example, suppose packages foo and bar are installed
+ For example, suppose packages foo and bar are "Installed"
with foo depending on bar. If an upgrade of bar were
started and then aborted, and then an attempt to remove
foo failed because its <prgn>prerm</prgn> script failed,
at least "Half-Installed". All package dependencies will at
least be "Half-Installed" and will have previously been
configured and not removed. If there was no error, all
- dependencies will at least be unpacked, but these actions
+ dependencies will at least be "Unpacked", but these actions
may be called in various error states where dependencies are
only "Half-Installed" due to a partial upgrade.
</item>
The <prgn>postrm</prgn> script is called after the package's
files have been removed or replaced. The package
whose <prgn>postrm</prgn> is being called may have
- previously been deconfigured and only be unpacked, at which
+ previously been deconfigured and only be "Unpacked", at which
point subsequent package changes do not consider its
dependencies. Therefore, all <prgn>postrm</prgn> actions
may only rely on essential packages and must gracefully skip
<item>
<enumlist>
<item>
- If a version of the package is already installed, call
+ If a version of the package is already "Installed", call
<example compact="compact">
<var>old-prerm</var> upgrade <var>new-version</var>
</example>
<item>
Otherwise, if the package had some configuration
files from a previous version installed (i.e., it
- is in the "configuration files only" state):
+ is in the "Config-Files" state):
<example compact="compact">
<var>new-preinst</var> install <var>old-version</var>
</example>
If the error-unwind fails, the package is in a
"Half-Installed" phase, and requires a
reinstall. If the error unwind works, the
- package is in a not installed state.
+ package is in the "Not-Installed" state.
</item>
</enumlist>
</item>
</item>
<item>
It is noted in the status database as being in a
- sane state, namely not installed (any conffiles
+ sane state, namely "Not-Installed" (any conffiles
it may have are ignored, rather than being
removed by <prgn>dpkg</prgn>). Note that
disappearing packages do not have their prerm
<item>
<p>
The new package's status is now sane, and recorded as
- "unpacked".
+ "Unpacked".
</p>
<p>
<p>
No attempt is made to unwind after errors during
configuration. If the configuration fails, the package is in
- a "Failed Config" state, and an error message is generated.
+ a "Half-Configured" state, and an error message is generated.
</p>
<p>
dependencies on other packages, the package names listed may
also include lists of alternative package names, separated
by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
- if any one of the alternative packages is installed, that
- part of the dependency is considered to be satisfied.
+ that part of the dependency can be satisfied by any one of
+ the alternative packages.
</p>
<p>
be <em>unpacked</em> the pre-dependency can be
satisfied if the depended-on package is either fully
configured, <em>or even if</em> the depended-on
- package(s) are only unpacked or in the "Half-Configured"
+ package(s) are only in the "Unpacked" or the "Half-Configured"
state, provided that they have been configured
correctly at some point in the past (and not removed
or partially removed since). In this case, both the
- previously-configured and currently unpacked or
+ previously-configured and currently "Unpacked" or
"Half-Configured" versions must satisfy any version
clause in the <tt>Pre-Depends</tt> field.
</p>
<prgn>dpkg</prgn> does not know of any files it still
contains, it is considered to have "disappeared". It will
be marked as not wanted on the system (selected for
- removal) and not installed. Any <tt>conffile</tt>s
+ removal) and "Not-Installed". Any <tt>conffile</tt>s
details noted for the package will be ignored, as they
will have been taken over by the overwriting package. The
package's <prgn>postrm</prgn> script will be run with a
The <file>shlibs</file> control files for all the
packages currently installed on the system. These are
normally found
- in <file>/var/lib/dpkg/info/*.symbols</file>, but
+ in <file>/var/lib/dpkg/info/*.shlibs</file>, but
packages should not rely on this and instead should
use <tt>dpkg-query --control-path <var>package</var>
shlibs</tt> if for some reason these files need to be
stable release of Debian supports <file>/run</file>.
</p>
</item>
- <item>
- <p>
- The following directories in the root filesystem are
- additionally allowed: <file>/sys</file> and
- <file>/selinux</file>. <footnote>These directories
- are used as mount points to mount virtual filesystems
- to get access to kernel information.</footnote>
- </p>
- </item>
+ <item>
+ <p>
+ The <file>/sys</file> directory in the root filesystem is
+ additionally allowed. <footnote>This directory is used as
+ mount point to mount virtual filesystems to get access to
+ kernel information.</footnote>
+ </p>
+ </item>
<item>
<p>
On GNU/Hurd systems, the following additional
<heading>Menus</heading>
<p>
- The Debian <tt>menu</tt> package provides a standard
- interface between packages providing applications and
- <em>menu programs</em> (either X window managers or
- text-based menu programs such as <prgn>pdmenu</prgn>).
+ Packages shipping applications that comply with minimal requirements
+ described below for integration with desktop environments should
+ register these applications in the desktop menu, following the
+ <em>FreeDesktop</em> standard, using text files called
+ <em>desktop entries</em>. Their format is described in the
+ <em>Desktop Entry Specification</em> at
+ <url id="http://standards.freedesktop.org/desktop-entry-spec/latest/">
+ and complementary information can be found in the
+ <em>Desktop Menu Specification</em> at
+ <url id="http://standards.freedesktop.org/menu-spec/latest/">.
</p>
<p>
- All packages that provide applications that need not be
- passed any special command line arguments for normal
- operation should register a menu entry for those
- applications, so that users of the <tt>menu</tt> package
- will automatically get menu entries in their window
- managers, as well in shells like <tt>pdmenu</tt>.
+ The desktop entry files are installed by the packages in the
+ directory <file>/usr/share/applications</file> and the FreeDesktop
+ menus are refreshed using <em>dpkg triggers</em>. It is therefore
+ not necessary to depend on packages providing FreeDesktop menu
+ systems.
</p>
<p>
- Menu entries should follow the current menu policy.
+ Entries displayed in the FreeDesktop menu should conform to the
+ following minima for relevance and visual integration.
+
+ <list>
+ <item>
+ Unless hidden by default, the desktop entry must point to a PNG
+ or SVG icon with a transparent background, providing at least
+ the 22×22 size, and preferably up to 64×64. The icon
+ should be neutral enough to integrate well with the default icon
+ themes. It is encouraged to ship the icon in the default
+ <em>hicolor</em> icon theme directories, or to use an existing
+ icon from the <em>hicolor</em> theme.
+ </item>
+
+ <item>
+ If the menu entry is not useful in the general case as a
+ standalone application, the desktop entry should set the
+ <tt>NoDisplay</tt> key to <var>true</var>, so that it can be
+ configured to be displayed only by those who need it.
+ </item>
+
+ <item>
+ In doubt, the package maintainer should coordinate with the
+ maintainers of menu implementations through the
+ <em>debian-desktop</em> mailing list in order to avoid problems
+ with categories or bad interactions with other icons. Especially
+ for packages which are part of installation tasks, the contents
+ of the <tt>NotShowIn</tt>/<tt>OnlyShowIn</tt> keys should be
+ validated by the maintainers of the relevant environments.
+ </item>
+ </list>
</p>
<p>
- The menu policy can be found in the <tt>menu-policy</tt>
- files in the <tt>debian-policy</tt> package.
- It is also available from the Debian web mirrors at
- <tt><url name="/doc/packaging-manuals/menu-policy/"
- id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
+ Since the FreeDesktop menu is a cross-distribution standard, the
+ desktop entries written for Debian should be forwarded upstream,
+ where they will benefit to other users and are more likely to
+ receive extra contributions such as translations.
</p>
- <p>
- Please also refer to the <em>Debian Menu System</em>
- documentation that comes with the <package>menu</package>
- package for information about how to register your
- applications.
+ <p>
+ Packages can, to be compatible with Debian additions to some window
+ managers that do not support the FreeDesktop standard, also provide a
+ <em>Debian menu</em> file, following the <em>Debian menu policy</em>,
+ which can be found in the <tt>menu-policy</tt> files in the
+ <tt>debian-policy</tt> package. It is also available from the Debian
+ web mirrors at <tt><url name="/doc/packaging-manuals/menu-policy/"
+ id="http://www.debian.org/doc/packaging-manuals/menu-policy/"></tt>.
</p>
</sect>
<heading>Multimedia handlers</heading>
<p>
- MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049)
- is a mechanism for encoding files and data streams and
- providing meta-information about them, in particular their
- type (e.g. audio or video) and format (e.g. PNG, HTML,
- MP3).
+ Media types (formerly known as MIME types, Multipurpose Internet Mail
+ Extensions, RFCs 2045-2049) is a mechanism for encoding files and
+ data streams and providing meta-information about them, in particular
+ their type and format (e.g. <tt>image/png</tt>, <tt>text/html</tt>,
+ <tt>audio/ogg</tt>).
</p>
<p>
- Registration of MIME type handlers allows programs like mail
+ Registration of media type handlers allows programs like mail
user agents and web browsers to invoke these handlers to
- view, edit or display MIME types they don't support directly.
+ view, edit or display media types they don't support directly.
</p>
<p>
- Packages which provide programs to view/show/play, compose, edit or
- print MIME types should register them as such by placing a file in
- <manref name="mailcap" section="5"> format (RFC 1524) in the directory
- <file>/usr/lib/mime/packages/</file>. The file name should be the
- binary package's name.
+ There are two overlapping systems to associate media types to programs
+ which can handle them. The <em>mailcap</em> system is found on a
+ large number of Unix systems. The <em>FreeDesktop</em> system is
+ aimed at Desktop environments. In Debian, FreeDesktop entries are
+ automatically translated in mailcap entries, therefore packages
+ already using desktop entries should not use the mailcap system
+ directly.
</p>
- <p>
- The <package>mime-support</package> package provides the
- <prgn>update-mime</prgn> program, which integrates these
- registrations in the <file>/etc/mailcap</file> file, using dpkg
- triggers<footnote>
- Creating, modifying or removing a file in
- <file>/usr/lib/mime/packages/</file> using maintainer scripts will
- not activate the trigger. In that case, it can be done by calling
- <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from
- the maintainer script after creating, modifying, or removing
- the file.
- </footnote>.
- Packages using this facility <em>should not</em> depend on,
- recommend, or suggest <prgn>mime-support</prgn>.
- </p>
+ <sect1 id="media-types-freedesktop">
+ <heading>Registration of media type handlers with desktop entries</heading>
+
+ <p>
+ Packages shipping an application able to view, edit or point to
+ files of a given media type, or open links with a given URI scheme,
+ should list it in the <tt>MimeType</tt> key of the application's
+ <qref id="menus">desktop entry</qref>. For URI schemes,
+ the relevant MIME types are <tt>x-scheme-handler/*</tt> (e.g.
+ <tt>x-scheme-handler/https</tt>).
+ </p>
+ </sect1>
+
+ <sect1 id="mailcap">
+ <heading>Registration of media type handlers with mailcap entries</heading>
+
+ <p>
+ Packages that are not using desktop entries for registration should
+ install a file in <manref name="mailcap" section="5"> format (RFC
+ 1524) in the directory <file>/usr/lib/mime/packages/</file>. The
+ file name should be the binary package's name.
+ </p>
+
+ <p>
+ The <package>mime-support</package> package provides the
+ <prgn>update-mime</prgn> program, which integrates these
+ registrations in the <file>/etc/mailcap</file> file, using dpkg
+ triggers<footnote>
+ Creating, modifying or removing a file in
+ <file>/usr/lib/mime/packages/</file> using maintainer scripts will
+ not activate the trigger. In that case, it can be done by calling
+ <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from
+ the maintainer script after creating, modifying, or removing
+ the file.
+ </footnote>.
+
+ <p>
+ Packages installing desktop entries should not install mailcap
+ entries for the same program, because the
+ <package>mime-support</package> package already reads desktop
+ entries.
+ </p>
+
+ <p>
+ Packages using these facilities <em>should not</em> depend on,
+ recommend, or suggest <prgn>mime-support</prgn>.
+ </p>
+ </sect1>
+
+ <sect1 id="file-media-type">
+ <heading>Providing media types to files</heading>
+
+ <p>
+ The media type of a file is discovered by inspecting the file's
+ extension or its <manref name="magic" section="5"> pattern, and
+ interrogating a database associating them with media types.
+ </p>
+
+ <p>
+ To support new associations between media types and files, their
+ characteristic file extensions and magic patterns should be
+ registered to the IANA (Internet Assigned Numbers Authority). See
+ <url id="http://www.iana.org/assignments/media-types"> and RFC 6838
+ for details. This information will then propagate to the systems
+ discovering file media types in Debian, provided by the
+ <package>shared-mime-info</package>,
+ <package>mime-support</package> and <package>file</package>
+ packages. If registration and propagation can not be waited for,
+ support can be asked to the maintainers of the packages mentioned
+ above.
+ </p>
+
+ <p>
+ For files that are produced and read by a single application, it
+ is also possible to declare this association to the
+ <em>Shared MIME Info</em> system by installing in the directory
+ <file>/usr/share/mime/packages</file> a file in the XML format
+ specified at <url id="http://standards.freedesktop.org/shared-mime-info-spec/latest/">.
+ </p>
+ </sect1>
</sect>
<sect>
</p>
<p>
- A symbolic link pointing to a compressed file should always
+ A symbolic link pointing to a compressed file (in the sense
+ that it is meant to be uncompressed with <prgn>unzip</prgn>
+ or <prgn>zless</prgn> etc.) should always
have the same file extension as the referenced file. (For
example, if a file <file>foo.gz</file> is referenced by a
symbolic link, the filename of the link has to end with
package is purged.
</item>
</list>
- Obsolete configuration files without local changes may be
- removed by the package during upgrade.
+ Obsolete configuration files without local changes should be
+ removed by the package during upgrade.<footnote>
+ The <prgn>dpkg-maintscript-helper</prgn> tool, available from the
+ <package>dpkg</package> package, can help for this task.</footnote>
</p>
<p>
</p>
</sect1>
</sect>
+
+ <sect id="filenames">
+ <heading>File names</heading>
+
+ <p>
+ The name of the files installed by binary packages in the system PATH
+ (namely <tt>/bin</tt>, <tt>/sbin</tt>, <tt>/usr/bin</tt>,
+ <tt>/usr/sbin</tt> and <tt>/usr/games</tt>) must be encoded in
+ ASCII.
+ </p>
+
+ <p>
+ The name of the files and directories installed by binary packages
+ outside the system PATH must be encoded in UTF-8 and should be
+ restricted to ASCII when it is possible to do so.
+ </p>
+ </sect>
</chapt>
</item>
<item>
- <p>Access to HTML documents</p>
-
- <p>
- HTML documents for a package are stored in
- <file>/usr/share/doc/<var>package</var></file>
- and can be referred to as
- <example compact="compact">
-http://localhost/doc/<var>package</var>/<var>filename</var>
- </example>
- </p>
-
- <p>
- The web server should restrict access to the document
- tree so that only clients on the same host can read
- the documents. If the web server does not support such
- access controls, then it should not provide access at
- all, or ask about providing access during installation.
- </p>
+ <p>(Deleted)</p>
</item>
<item>
<p>
The <prgn>install-info</prgn> program maintains a directory of
- installed info documents in <file>/usr/share/info/dir</file> for
- the use of info readers.<footnote>
- It was previously necessary for packages installing info
- documents to run <prgn>install-info</prgn> from maintainer
- scripts. This is no longer necessary. The installation
- system now uses dpkg triggers.
- </footnote>
- This file must not be included in packages. Packages containing
- info documents should depend on <tt>dpkg (>= 1.15.4) |
- install-info</tt> to ensure that the directory file is properly
- rebuilt during partial upgrades from Debian 5.0 (lenny) and
- earlier.
+ installed info documents in <file>/usr/share/info/dir</file> for the
+ use of info readers. This file must not be included in packages
+ other than <package>install-info</package>.
+ </p>
+
+ <p>
+ <prgn>install-info</prgn> is automatically invoked when
+ appropriate using dpkg triggers. Packages other than
+ <package>install-info</package> <em>should not</em> invoke
+ <prgn>install-info</prgn> directly and <em>should not</em>
+ depend on, recommend, or suggest <package>install-info</package>
+ for this purpose.
+ </p>
+
+ <p>
+ Info readers requiring the <file>/usr/share/info/dir</file> file
+ should depend on <package>install-info</package>.
</p>
<p>
there is a time, after it has been diverted but before
<prgn>dpkg</prgn> has installed the new version, when the file
does not exist.</p>
+
+ <p>
+ Do not attempt to divert a conffile, as <prgn>dpkg</prgn> does not
+ handle it well.
+ </p>
</appendix>
</book>
projects / debian / debian-policy.git / blobdiff