<item><ref id="fhs"></item>
<item><ref id="virtual_pkg"></item>
<item><ref id="menus"></item>
- <item><ref id="mime"></item>
<item><ref id="perl"></item>
<item><ref id="maintscriptprompt"></item>
<item><ref id="emacs"></item>
In addition, the packages in <em>main</em>
<list compact="compact">
<item>
- must not require a package outside of <em>main</em>
- for compilation or execution (thus, the package must
- not declare a "Depends", "Recommends", or
- "Build-Depends" relationship on a non-<em>main</em>
- package),
+ must not require or recommend a package outside
+ of <em>main</em> for compilation or execution (thus, the
+ package must not declare a "Pre-Depends", "Depends",
+ "Recommends", "Build-Depends", or "Build-Depends-Indep"
+ relationship on a non-<em>main</em> package),
</item>
<item>
must not be so buggy that we refuse to support them,
list of sections. At present, they are:
<em>admin</em>, <em>cli-mono</em>, <em>comm</em>, <em>database</em>,
<em>devel</em>, <em>debug</em>, <em>doc</em>, <em>editors</em>,
- <em>electronics</em>, <em>embedded</em>, <em>fonts</em>,
- <em>games</em>, <em>gnome</em>, <em>graphics</em>, <em>gnu-r</em>,
- <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
- <em>httpd</em>, <em>interpreters</em>, <em>java</em>, <em>kde</em>,
- <em>kernel</em>, <em>libs</em>, <em>libdevel</em>, <em>lisp</em>,
- <em>localization</em>, <em>mail</em>, <em>math</em>, <em>misc</em>,
+ <em>education</em>, <em>electronics</em>, <em>embedded</em>,
+ <em>fonts</em>, <em>games</em>, <em>gnome</em>, <em>graphics</em>,
+ <em>gnu-r</em>, <em>gnustep</em>, <em>hamradio</em>, <em>haskell</em>,
+ <em>httpd</em>, <em>interpreters</em>, <em>introspection</em>,
+ <em>java</em>, <em>kde</em>, <em>kernel</em>, <em>libs</em>,
+ <em>libdevel</em>, <em>lisp</em>, <em>localization</em>,
+ <em>mail</em>, <em>math</em>, <em>metapackages</em>, <em>misc</em>,
<em>net</em>, <em>news</em>, <em>ocaml</em>, <em>oldlibs</em>,
<em>otherosfs</em>, <em>perl</em>, <em>php</em>, <em>python</em>,
<em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
lines. The first line of the value, the part on the same line as
the field name, often has special significance or may have to be
empty. Other lines are added following the same syntax as the
- continuation lines the folded fields. Whitespace, including newlines,
+ continuation lines of the folded fields. Whitespace, including newlines,
is significant in the values of multiline fields.
</item>
</taglist>
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 contain at least one non-whitespace character.
</item>
<item>
will be allowed to trail off to the right. None, one or two
initial spaces may be deleted, but the number of spaces
deleted from each line will be the same (so that you can have
- indenting work correctly, for example).
+ indenting work correctly, for example). The line must
+ contain at least one non-whitespace character.
</item>
<item>
Relationships may be restricted to a certain set of
architectures. This is indicated in brackets after each
individual package name and the optional version specification.
- The brackets enclose a list of Debian architecture names
+ The brackets enclose a non-empty list of Debian architecture names
+ in the format described in <ref id="arch-spec">,
separated by whitespace. Exclamation marks may be prepended to
each of the names. (It is not permitted for some names to be
prepended with exclamation marks while others aren't.)
<p>
Relationships may also be restricted to a certain set of
- architectures using architecture wildcards. The syntax for
+ architectures using architecture wildcards in the format
+ described in <ref id="arch-wildcard-spec">. The syntax for
declaring such restrictions is the same as declaring
restrictions using a certain set of architectures without
architecture wildcards. For example:
symlinked there, is relaxed to a recommendation.
</p>
</item>
+ <item>
+ <p>
+ The additional directory <file>/run</file> in the root
+ file system is allowed. <file>/run</file>
+ replaces <file>/var/run</file>, and the
+ subdirectory <file>/run/lock</file>
+ replaces <file>/var/lock</file>, with
+ the <file>/var</file> directories replaced by symlinks
+ for backwards compatibility. <file>/run</file>
+ and <file>/run/lock</file> must follow all of the
+ requirements in the FHS for <file>/var/run</file>
+ and <file>/var/lock</file>, respectively, such as file
+ naming conventions, file format requirements, or the
+ requirement that files be cleared during the boot
+ process. Files and directories residing
+ in <file>/run</file> should be stored on a temporary
+ file system.
+ </p>
+ </item>
<item>
<p>
The following directories in the root filesystem are
For example, the <tt>emacsen-common</tt> package could
contain something like
<example compact="compact">
-if [ ! -e /usr/local/share/emacs ]
-then
- if mkdir /usr/local/share/emacs 2>/dev/null
- then
- chown root:staff /usr/local/share/emacs
- chmod 2775 /usr/local/share/emacs
+if [ ! -e /usr/local/share/emacs ]; then
+ if mkdir /usr/local/share/emacs 2>/dev/null; then
+ if chown root:staff /usr/local/share/emacs; then
+ chmod 2775 /usr/local/share/emacs || true
+ fi
fi
fi
</example>
though the spool may still be physically located there.
</p>
</sect1>
+
+ <sect1 id="fhs-run">
+ <heading><file>/run</file> and <file>/run/lock</file></heading>
+
+ <p>
+ The directory <file>/run</file> is cleared at boot, normally
+ by being a mount point for a temporary file system. Packages
+ therefore must not assume that any files or directories
+ under <file>/run</file> other than <file>/run/lock</file>
+ exist unless the package has arranged to create those files or
+ directories since the last reboot. Normally, this is done by
+ the package via an init script. See <ref id="writing-init">
+ for more information.
+ </p>
+
+ <p>
+ Packages must not include files or directories
+ under <file>/run</file>, or under the
+ older <file>/var/run</file> and <file>/var/lock</file> paths.
+ The latter paths will normally be symlinks or other
+ redirections to <file>/run</file> for backwards compatibility.
+ </p>
+ </sect1>
</sect>
<sect>
</p>
<p>
- <file>/var/run</file> and <file>/var/lock</file> may be mounted
- as temporary filesystems<footnote>
- For example, using the <tt>RAMRUN</tt> and <tt>RAMLOCK</tt>
- options in <file>/etc/default/rcS</file>.
- </footnote>, so the <file>init.d</file> scripts must handle this
- correctly. This will typically amount to creating any required
- subdirectories dynamically when the <file>init.d</file> script
- is run, rather than including them in the package and relying on
- <prgn>dpkg</prgn> to create them.
+ Files and directories under <file>/run</file>, including ones
+ referred to via the compatibility paths <file>/var/run</file>
+ and <file>/var/lock</file>, are normally stored on a temporary
+ filesystem and are normally not persistent across a reboot.
+ The <file>init.d</file> scripts must handle this correctly.
+ This will typically mean creating any required subdirectories
+ dynamically when the <file>init.d</file> script is run.
+ See <ref id="fhs-run"> for more information.
</p>
</sect1>
</p>
</sect>
- <sect>
+ <sect id="cron-jobs">
<heading>Cron jobs</heading>
<p>
Packages must not modify the configuration file
<file>/etc/crontab</file>, and they must not modify the files in
- <file>/var/spool/cron/crontabs</file>.</p>
+ <file>/var/spool/cron/crontabs</file>.
+ </p>
<p>
- If a package wants to install a job that has to be executed
- via cron, it should place a file with the name of the
- package in one or more of the following directories:
+ If a package wants to install a job that has to be executed via
+ cron, it should place a file named as specified
+ in <ref id="cron-files"> into one or more of the following
+ directories:
<example compact="compact">
/etc/cron.hourly
/etc/cron.daily
As these directory names imply, the files within them are
executed on an hourly, daily, weekly, or monthly basis,
respectively. The exact times are listed in
- <file>/etc/crontab</file>.</p>
+ <file>/etc/crontab</file>.
+ </p>
<p>
All files installed in any of these directories must be
<p>
If a certain job has to be executed at some other frequency or
- at a specific time, the package should install a file
- <file>/etc/cron.d/<var>package</var></file>. This file uses the
- same syntax as <file>/etc/crontab</file> and is processed by
- <prgn>cron</prgn> automatically. The file must also be
+ at a specific time, the package should install a file in
+ <file>/etc/cron.d</file> with a name as specified
+ in <ref id="cron-files">. This file uses the same syntax
+ as <file>/etc/crontab</file> and is processed
+ by <prgn>cron</prgn> automatically. The file must also be
treated as a configuration file. (Note that entries in the
<file>/etc/cron.d</file> directory are not handled by
<prgn>anacron</prgn>. Thus, you should only use this
directory for jobs which may be skipped if the system is not
- running.)</p>
+ running.)
+ </p>
+
<p>
Unlike <file>crontab</file> files described in the IEEE Std
1003.1-2008 (POSIX.1) available from
execute scripts in
<file>/etc/cron.{hourly,daily,weekly,monthly}</file>.
</p>
+
+ <sect1 id="cron-files">
+ <heading>Cron job file names</heading>
+
+ <p>
+ The file name of a cron job file should normally match the
+ name of the package from which it comes.
+ </p>
+
+ <p>
+ If a package supplies multiple cron job files files in the
+ same directory, the file names should all start with the name
+ of the package (possibly modified as described below) followed
+ by a hyphen (<tt>-</tt>) and a suitable suffix.
+ </p>
+
+ <p>
+ A cron job file name must not include any period or plus
+ characters (<tt>.</tt> or <tt>+</tt>) characters as this will
+ cause cron to ignore the file. Underscores (<tt>_</tt>)
+ should be used instead of <tt>.</tt> and <tt>+</tt>
+ characters.
+ </p>
+ </sect1>
</sect>
<sect id="menus">
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,
+ type (e.g. audio or video) and format (e.g. PNG, HTML,
MP3).
</p>
</p>
<p>
- The MIME support policy can be found in the <tt>mime-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/mime-policy/"
- id="http://www.debian.org/doc/packaging-manuals/mime-policy/"></tt>.
+ The <package>mime-support</package> package provides the
+ <prgn>update-mime</prgn> program which allows packages to
+ register programs that can show, compose, edit or print
+ MIME types.
+ </p>
+
+ <p>
+ Packages containing such programs must register them
+ with <prgn>update-mime</prgn> as documented in <manref
+ name="update-mime" section="8">. They should <em>not</em> depend
+ on, recommend, or suggest <prgn>mime-support</prgn>. Instead,
+ they should just put something like the following in the
+ <tt>postinst</tt> and <tt>postrm</tt> scripts:
+
+ <example>
+ if [ -x /usr/sbin/update-mime ]; then
+ update-mime
+ fi
+ </example>
</p>
</sect>
package that provides online documentation (other than just
manual pages) to register these documents with
<package>doc-base</package> by installing a
- <package>doc-base</package> control file via the
- <prgn/install-docs/ script at installation time and
- de-register the manuals again when the package is removed.
+ <package>doc-base</package> control file in
+ <file>/usr/share/doc-base/</file>.
</p>
<p>
Please refer to the documentation that comes with the
<heading>Symbolic links</heading>
<p>
- In general, symbolic links within a top-level directory
- should be relative, and symbolic links pointing from one
- top-level directory into another should be absolute. (A
- top-level directory is a sub-directory of the root
- directory <file>/</file>.)
+ In general, symbolic links within a top-level directory should
+ be relative, and symbolic links pointing from one top-level
+ directory to or into another should be absolute. (A top-level
+ directory is a sub-directory of the root
+ directory <file>/</file>.) For example, a symbolic link
+ from <file>/usr/lib/foo</file> to <file>/usr/share/bar</file>
+ should be relative (<file>../share/bar</file>), but a symbolic
+ link from <file>/var/run</file> to <file>/run</file> should be
+ absolute.<footnote>
+ This is necessary to allow top-level directories to be
+ symlinks. If linking <file>/var/run</file>
+ to <file>/run</file> were done with the relative symbolic
+ link <file>../run</file>, but <file>/var</file> were a
+ symbolic link to <file>/srv/disk1</file>, the symbolic link
+ would point to <file>/srv/run</file> rather than the intended
+ target.
+ </footnote>
</p>
<p>
<sect1>
<heading>Sharing configuration files</heading>
- <p>
- Packages which specify the same file as a
- <tt>conffile</tt> must be tagged as <em>conflicting</em>
- with each other. (This is an instance of the general rule
- about not sharing files. Note that neither alternatives
- nor diversions are likely to be appropriate in this case;
- in particular, <prgn>dpkg</prgn> does not handle diverted
- <tt>conffile</tt>s well.)
- </p>
-
- <p>
- The maintainer scripts must not alter a <tt>conffile</tt>
- of <em>any</em> package, including the one the scripts
- belong to.
- </p>
-
<p>
If two or more packages use the same configuration file
and it is reasonable for both to be installed at the same
and which manages the shared configuration files. (The
<tt>sgml-base</tt> package is a good example.)
</p>
+
+ <p>
+ If the configuration file cannot be shared as described above,
+ the packages must be marked as conflicting with each other.
+ Two packages that specify the same file as
+ a <tt>conffile</tt> must conflict. This is an instance of the
+ general rule about not sharing files. Neither alternatives
+ nor diversions are likely to be appropriate in this case; in
+ particular, <prgn>dpkg</prgn> does not handle diverted
+ <tt>conffile</tt>s well.
+ </p>
+
+ <p>
+ When two packages both declare the same <tt>conffile</tt>, they
+ may see left-over configuration files from each other even
+ though they conflict with each other. If a user removes
+ (without purging) one of the packages and installs the other,
+ the new package will take over the <tt>conffile</tt> from the
+ old package. If the file was modified by the user, it will be
+ treated the same as any other locally
+ modified <tt>conffile</tt> during an upgrade.
+ </p>
+
+ <p>
+ The maintainer scripts must not alter a <tt>conffile</tt>
+ of <em>any</em> package, including the one the scripts
+ belong to.
+ </p>
</sect1>
<sect1>
<p>
In addition, the copyright file must say where the upstream
- sources (if any) were obtained. It should name the original
- authors of the package and the Debian maintainer(s) who were
- involved with its creation.
+ sources (if any) were obtained, and should name the original
+ authors.
</p>
<p>
<file>/usr/share/doc/<var>package</var></file> may be a symbolic
link to another directory in <file>/usr/share/doc</file> only if
the two packages both come from the same source and the
- first package Depends on the second. These rules are
- important because copyrights must be extractable by
+ first package Depends on the second. These rules are important
+ because <file>copyright</file> files must be extractable by
mechanical means.
</p>
dpkg-divert --package smailwrapper --remove --rename \
--divert /usr/sbin/smail.real /usr/sbin/smail
fi
- </example> where <tt>1.02-2</tt> is the version at which the
+ </example> where <tt>1.0-2</tt> is the version at which the
diversion was first added to the package. The postrm should not
remove the diversion on upgrades both because there's no reason to
remove the diversion only to immediately re-add it and since the
projects / debian / debian-policy.git / blobdiff