<enumlist>
<item>Russ Allbery</item>
<item>Bill Allombert</item>
- <item>Andrew McMillan</item>
- <item>Manoj Srivastava</item>
- <item>Colin Watson</item>
+ <item>Andreas Barth</item>
+ <item>Jonathan Nieder</item>
</enumlist>
</p>
<p>
The maintainer name and email address used in the changelog
- should be the details of the person uploading <em>this</em>
- version. They are <em>not</em> necessarily those of the
- usual package maintainer.<footnote>
- If the developer uploading the package is not one of the usual
- maintainers of the package (as listed in
+ should be the details of the person who prepared this release of
+ the package. They are <em>not</em> necessarily those of the
+ uploader or usual package maintainer.<footnote>
+ In the case of a sponsored upload, the uploader signs the
+ files, but the changelog maintainer name and address are those
+ of the person who prepared this release. If the preparer of
+ the release is not one of the usual maintainers of the package
+ (as listed in
the <qref id="f-Maintainer"><tt>Maintainer</tt></qref>
or <qref id="f-Uploaders"><tt>Uploaders</tt></qref> control
fields of the package), the first line of the changelog is
any target that these targets depend on must also be
non-interactive.
</p>
+ <p>
+ For packages in the main archive, no required targets
+ may attempt network access.
+ </p>
<p>
The targets are as follows:
This is an optional, recommended configuration file for the
<tt>uscan</tt> utility which defines how to automatically scan
ftp or http sites for newly available updates of the
- package. This is used
- by <url id="http://dehs.alioth.debian.org/"> and other Debian QA
+ package. This is used Debian QA
tools to help with quality control and maintenance of the
distribution as a whole.
</p>
the field name is <tt>Package</tt> and the field value
<tt>libc6</tt>.
</p>
-
+ <p> Empty field values are only permitted in source package control files
+ (<file>debian/control</file>). Such fields are ignored.
+ </p>
<p>
A paragraph must not contain more than one instance of a
particular field name.
file. These tools are responsible for removing the line
breaks from such fields when using fields from
<file>debian/control</file> to generate other control files.
+ They are also responsible for discarding empty fields.
</p>
<p>
<p>
The special value <tt>byhand</tt> for the section in a
<tt>.changes</tt> file indicates that the file in question
- is not an ordinary package file and must by installed by
+ is not an ordinary package file and must be installed by
hand by the distribution maintainers. If the section is
<tt>byhand</tt> the priority should be <tt>-</tt>.
</p>
exceptions to the FHS apply:
<enumlist>
+ <item>
+ <p>
+ The FHS requirement that architecture-independent
+ application-specific static files be located in
+ <file>/usr/share</file> is relaxed to a suggestion.
+
+ In particular, a subdirectory of <file>/usr/lib</file> may
+ be used by a package (or a collection of packages) to hold a
+ mixture of architecture-independent and
+ architecture-dependent files. However, when a directory is
+ entirely composed of architecture-independent files, it
+ should be located in <file>/usr/share</file>.
+ </p>
+ </item>
<item>
<p>
The optional rules related to user specific
<footnote>
This is necessary in order to reserve the directories for
use in cross-installation of library packages from other
- architectures, as part of the planned deployment of
- <tt>multiarch</tt>.
+ architectures, as part of <tt>multiarch</tt>.
+ </footnote>
+ </p>
+ <p>
+ The requirement for C and C++ headers files to be
+ accessible through the search path
+ <file>/usr/include/</file> is amended, permitting files to
+ be accessible through the search path
+ <file>/usr/include/<var>triplet</var></file> where
+ <tt><var>triplet</var></tt> is as above. <footnote>
+ This is necessary for architecture-dependant headers
+ file to coexist in a <tt>multiarch</tt> setup.
</footnote>
</p>
<p>
kernel information.</footnote>
</p>
</item>
+ <item>
+ <p>
+ The <file>/var/www</file> directory is additionally allowed.
+ </p>
+ </item>
+ <item>
+ <p>
+ The requirement for <file>/usr/local/lib<qual></file>
+ to exist if <file>/lib<qual></file> or
+ <file>/usr/lib<qual></file> exists (where
+ <file>lib<qual></file> is a variant of
+ <file>lib</file> such as <file>lib32</file> or
+ <file>lib64</file>) is removed.
+ </p>
+ </item>
<item>
<p>
On GNU/Hurd systems, the following additional
</item>
<tag>65535:</tag>
+ <item>
+ <p>
+ This value <em>must not</em> be used, because it was
+ the error return sentinel value when <tt>uid_t</tt>
+ was 16 bits.
+ </p>
+ </item>
+
+ <tag>65536-4294967293:</tag>
+ <item>
+ <p>
+ Dynamically allocated user accounts. By
+ default <prgn>adduser</prgn> will not allocate UIDs
+ and GIDs in this range, to ease compatibility with
+ legacy systems where <tt>uid_t</tt> is still 16
+ bits.
+ </p>
+ </item>
+
+ <tag>4294967294:</tag>
+ <item>
+ <p>
+ <tt>(uid_t)(-2) == (gid_t)(-2)</tt> <em>must not</em> be
+ used, because it is used as the anonymous, unauthenticated
+ user by some NFS implementations.
+ </p>
+ </item>
+
+ <tag>4294967295:</tag>
<item>
<p>
<tt>(uid_t)(-1) == (gid_t)(-1)</tt> <em>must
<heading>Menus</heading>
<p>
- 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/">.
+ 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>).
</p>
<p>
- 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.
+ 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>.
</p>
<p>
- 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>
+ Menu entries should follow the current menu policy.
</p>
<p>
- 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.
+ 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>.
</p>
- <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>
+ 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>
</sect>
<heading>Multimedia handlers</heading>
<p>
- 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>).
+ 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).
</p>
<p>
- Registration of media type handlers allows programs like mail
+ Registration of MIME type handlers allows programs like mail
user agents and web browsers to invoke these handlers to
- view, edit or display media types they don't support directly.
+ view, edit or display MIME types they don't support directly.
</p>
<p>
- 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.
+ 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.
</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>
+ <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>
</sect>
<sect>
renamed. If a consensus cannot be reached, <em>both</em>
programs must be renamed.
</p>
-
+ <p>
+ Binary executables must not be statically linked with the GNU C
+ library, since this prevents the binary from benefiting from
+ fixes and improvements to the C library without being rebuilt
+ and complicates security updates. This requirement may be
+ relaxed for binary executables whose intended purpose is to
+ diagnose and fix the system in situations where the GNU C
+ library may not be usable (such as system recovery shells or
+ utilities like ldconfig) or for binary executables where the
+ security benefits of static linking outweigh the drawbacks.
+ </p>
<p>
By default, when a package is being built, any binaries
created should include debugging information, as well as
would point to <file>/srv/run</file> rather than the intended
target.
</footnote>
+ Symbolic links must not traverse above the root directory.
</p>
<p>
Cgi-bin executable files are installed in the
directory
<example compact="compact">
-/usr/lib/cgi-bin/<var>cgi-bin-name</var>
+/usr/lib/cgi-bin
</example>
- or a subdirectory of that directory, and should be
- referred to as
+ or a subdirectory of that directory, and the script
<example compact="compact">
-http://localhost/cgi-bin/<var>cgi-bin-name</var>
+/usr/lib/cgi-bin/.../<var>cgi-bin-name</var>
+ </example>
+ should be referred to as
+ <example compact="compact">
+http://localhost/cgi-bin/.../<var>cgi-bin-name</var>
</example>
- (possibly with a subdirectory name
- before <var>cgi-bin-name</var>).
</item>
<item>
<package>doc-base</package> package. If access to the
web document root is unavoidable then use
<example compact="compact">
-/var/www
+/var/www/html
</example>
as the Document Root. This might be just a symbolic
link to the location where the system administrator
</p>
</sect>
- <sect>
+ <sect id="docs-additional">
<heading>Additional documentation</heading>
<p>
- Any additional documentation that comes with the package may
- be installed at the discretion of the package maintainer.
- Plain text documentation should be installed in the directory
- <file>/usr/share/doc/<var>package</var></file>, where
- <var>package</var> is the name of the package, and
- compressed with <tt>gzip -9</tt> unless it is small.
- </p>
+ Any additional documentation that comes with the package may be
+ installed at the discretion of the package maintainer. It is
+ often a good idea to include text information files
+ (<file>README</file>s, FAQs, and so forth) that come with the
+ source package in the binary package. However, you don't need
+ to install the instructions for building and installing the
+ package, of course!
+ </p>
<p>
- If a package comes with large amounts of documentation which
- many users of the package will not require you should create
- a separate binary package to contain it, so that it does not
- take up disk space on the machines of users who do not need
- or want it installed.</p>
+ Plain text documentation should be compressed with <tt>gzip
+ -9</tt> unless it is small.
+ </p>
<p>
- It is often a good idea to put text information files
- (<file>README</file>s, changelogs, and so forth) that come with
- the source package in <file>/usr/share/doc/<var>package</var></file>
- in the binary package. However, you don't need to install
- the instructions for building and installing the package, of
- course!</p>
+ If a package comes with large amounts of documentation that many
+ users of the package will not require, you should create a
+ separate binary package to contain it so that it does not take
+ up disk space on the machines of users who do not need or want
+ it installed. As a special case of this rule, shared library
+ documentation of any appreciable size should always be packaged
+ with the library development package (<ref id="sharedlibs-dev">)
+ or in a separate documentation package, since shared libraries
+ are frequently installed as dependencies of other packages by
+ users who have little interest in documentation of the library
+ itself. The documentation package for the
+ package <var>package</var> is conventionally
+ named <var>package</var>-doc
+ (or <var>package</var>-doc-<var>language-code</var> if there are
+ separate documentation packages for multiple languages).
+ </p>
+
+ <p>
+ Additional documentation included in the package should be
+ installed under <file>/usr/share/doc/<var>package</var></file>.
+ If the documentation is packaged separately,
+ as <var>package</var>-doc for example, it may be installed under
+ either that path or into the documentation directory for the
+ separate documentation package
+ (<file>/usr/share/doc/<var>package</var>-doc</file> in this
+ example). However, installing the documentation into the
+ documentation directory of the main package is preferred since
+ it is independent of the packaging method and will be easier for
+ users to find.
+ </p>
+
+ <p>
+ Any separate package providing documentation must still install
+ standard documentation files in its
+ own <file>/usr/share/doc</file> directory as specified in the
+ rest of this policy. See, for example, <ref id="copyrightfile">
+ and <ref id="changelogs">.
+ </p>
<p>
Packages must not require the existence of any files in
<file>/usr/share/doc/</file> in order to function
<footnote>
- The system administrator should be able to
- delete files in <file>/usr/share/doc/</file> without causing
- any programs to break.
- </footnote>.
- Any files that are referenced by programs but are also
- useful as stand alone documentation should be installed under
- <file>/usr/share/<var>package</var>/</file> with symbolic links from
- <file>/usr/share/doc/<var>package</var></file>.
+ The system administrator should be able to delete files
+ in <file>/usr/share/doc/</file> without causing any programs
+ to break.
+ </footnote>. Any files that are used or read by programs but
+ are also useful as stand alone documentation should be installed
+ elsewhere, such as
+ under <file>/usr/share/<var>package</var>/</file>, and then
+ included via symbolic links
+ in <file>/usr/share/doc/<var>package</var></file>.
</p>
<p>
</p>
</footnote>
</p>
-
- <p>
- Former Debian releases placed all additional documentation
- in <file>/usr/doc/<var>package</var></file>. This has been
- changed to <file>/usr/share/doc/<var>package</var></file>,
- and packages must not put documentation in the directory
- <file>/usr/doc/<var>package</var></file>. <footnote>
- At this phase of the transition, we no longer require a
- symbolic link in <file>/usr/doc/</file>. At a later point,
- policy shall change to make the symbolic links a bug.
- </footnote>
- </p>
</sect>
<sect>
via HTML.</p>
<p>
- If your package comes with extensive documentation in a
+ If the package comes with extensive documentation in a
markup format that can be converted to various other formats
you should if possible ship HTML versions in a binary
- package, in the directory
- <file>/usr/share/doc/<var>appropriate-package</var></file> or
- its subdirectories.<footnote>
- The rationale: The important thing here is that HTML
- docs should be available in <em>some</em> package, not
- necessarily in the main binary package.
+ package.<footnote>
+ Rationale: The important thing here is that HTML
+ documentation should be available from <em>some</em>
+ binary package.
</footnote>
+ The documentation must be installed as specified in
+ <ref id="docs-additional">.
</p>
<p>
projects / debian / debian-policy.git / blobdiff