<p>
Field names are not case-sensitive, but it is usual to
capitalize the field names using mixed case as shown below.
+ Field values are case-sensitive unless the description of the
+ field says otherwise.
</p>
<p>
</p>
<p>
- Package names must consist only of lower case letters
- (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
- and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
- They must be at least two characters long and must start
- with an alphanumeric character.
+ Package names (both source and binary,
+ see <ref id="f-Package">) must consist only of lower case
+ letters (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus
+ (<tt>+</tt>) and minus (<tt>-</tt>) signs, and periods
+ (<tt>.</tt>). They must be at least two characters long and
+ must start with an alphanumeric character.
</p>
</sect1>
</p>
<p>
- Package names must consist only of lower case letters
- (<tt>a-z</tt>), digits (<tt>0-9</tt>), plus (<tt>+</tt>)
- and minus (<tt>-</tt>) signs, and periods (<tt>.</tt>).
- They must be at least two characters long and must start
- with an alphanumeric character.
+ Binary package names must follow the same syntax and
+ restrictions as source package names. See <ref id="f-Source">
+ for the details.
</p>
</sect1>
</p>
<p>
- In a <file>.changes</file> file, the <tt>Description</tt> field
- contains a summary of the descriptions for the packages being
- uploaded.
+ In a <file>.changes</file> file, the <tt>Description</tt>
+ field contains a summary of the descriptions for the packages
+ being uploaded. For this case, the first line of the field
+ value (the part on the same line as <tt>Description:</tt>) is
+ always empty. The content of the field is expressed as
+ continuation lines, one line per package. Each line is
+ indented by one space and contains the name of a binary
+ package, a space, a hyphen (<tt>-</tt>), a space, and the
+ short description line from that package.
</p>
-
- <p>
- The part of the field before the first newline is empty;
- thereafter each line has the name of a binary package and
- the summary description line from that binary package.
- Each line is indented by one space.
- </p>
-
</sect1>
<sect1 id="f-Distribution">
</p>
<p>
- There should be nothing in this field before the first
- newline; all the subsequent lines must be indented by at
- least one space; blank lines must be represented by a line
- consisting only of a space and a full stop.
+ The first line of the field value (the part on the same line
+ as <tt>Changes:</tt>) is always empty. The content of the
+ field is expressed as continuation lines, with each line
+ indented by at least one space. Blank lines must be
+ represented by a line consisting only of a space and a full
+ stop (<tt>.</tt>).
</p>
<p>
<heading><tt>Binary</tt></heading>
<p>
- This field is a list of binary packages.
- </p>
-
- <p>
- When it appears in the <file>.dsc</file> file it is the list
- of binary packages which a source package can produce. It
- does not necessarily produce all of these binary packages
- for every architecture. The source control file doesn't
- contain details of which architectures are appropriate for
- which of the binary packages.
+ This field is a list of binary packages. Its syntax and
+ meaning varies depending on the control file in which it
+ appears.
</p>
<p>
- When it appears in a <file>.changes</file> file it lists the
- names of the binary packages actually being uploaded.
+ When it appears in the <file>.dsc</file> file, it lists binary
+ packages which a source package can produce, separated by
+ commas<footnote>
+ A space after each comma is conventional.
+ </footnote>. It may span multiple lines. The source package
+ does not necessarily produce all of these binary packages for
+ every architecture. The source control file doesn't contain
+ details of which architectures are appropriate for which of
+ the binary packages.
</p>
<p>
- The syntax is a list of binary packages separated by
- commas<footnote>
- A space after each comma is conventional.
- </footnote>. Currently the packages must be separated using
- only spaces in the <file>.changes</file> file.
+ When it appears in a <file>.changes</file> file, it lists the
+ names of the binary packages being uploaded, separated by
+ whitespace (not commas). It may span multiple lines.
</p>
</sect1>
<p>
This field appears in the control files of binary packages,
- and in the <file>Packages</file> files. It gives an
- estimation the total amount of disk space required to install
- the named package. Actual installed size may vary based on
- block size, file system properties, or actions taken by
- package maintainer scripts.
+ and in the <file>Packages</file> files. It gives an estimate
+ of the total amount of disk space required to install the
+ named package. Actual installed size may vary based on block
+ size, file system properties, or actions taken by package
+ maintainer scripts.
</p>
<p>
<p>
This field contains a list of files with information about
each one. The exact information and syntax varies with
- the context. In all cases the part of the field
- contents on the same line as the field name is empty. The
- remainder of the field is one line per file, each line
- being indented by one space and containing a number of
- sub-fields separated by spaces.
+ the context.
+ </p>
+
+ <p>
+ In all cases, Files is a multiline field. The first line of
+ the field value (the part on the same line as <tt>Files:</tt>)
+ is always empty. The content of the field is expressed as
+ continuation lines, one line per file. Each line must be
+ indented by one space and contain a number of sub-fields,
+ separated by spaces, as described below.
</p>
<p>
In the <file>.dsc</file> file, each line contains the MD5
- checksum, size and filename of the tar file and (if applicable)
- diff file which make up the remainder of the source
- package<footnote>
- That is, the parts which are not the <tt>.dsc</tt>.
- </footnote>.
+ checksum, size and filename of the tar file and (if
+ applicable) diff file which make up the remainder of the
+ source package<footnote>
+ That is, the parts which are not the <tt>.dsc</tt>.
+ </footnote>. For example:
+ <example>
+Files:
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
+ </example>
The exact forms of the filenames are described
in <ref id="pkg-sourcearchives">.
</p>
<p>
In the <file>.changes</file> file this contains one line per
file being uploaded. Each line contains the MD5 checksum,
- size, section and priority and the filename.
+ size, section and priority and the filename. For example:
+ <example>
+Files:
+ 4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc
+ c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz
+ 938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz
+ 7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
+ </example>
The <qref id="f-Section">section</qref>
- and <qref id="f-Priority">priority</qref>
- are the values of the corresponding fields in
- the main source control file. If no section or priority is
- specified then <tt>-</tt> should be used, though section
- and priority values must be specified for new packages to
- be installed properly.
+ and <qref id="f-Priority">priority</qref> are the values of
+ the corresponding fields in the main source control file. If
+ no section or priority is specified then <tt>-</tt> should be
+ used, though section and priority values must be specified for
+ new packages to be installed properly.
</p>
<p>
</p>
<p>
- Note that the same symbol (<tt>"</tt>) is used for the left
- and right quotation marks. A grave accent (<tt>`</tt>) is
- not a quote character; neither is an apostrophe
- (<tt>'</tt>).
+ Note that the same symbol (<tt>"</tt>) <!-- " --> is used
+ for the left and right quotation marks. A grave accent
+ (<tt>`</tt>) is not a quote character; neither is an
+ apostrophe (<tt>'</tt>).
</p>
</item>
fi
done
</example>
- The corresponding <tt>dpkg-statoverride --remove</tt>
- calls can then be made unconditionally when the package is
- purged.
+ The corresponding code to remove the override when the package
+ is purged would be:
+ <example>
+for i in /usr/bin/foo /usr/sbin/bar
+do
+ if dpkg-statoverride --list $i >/dev/null 2>&1
+ then
+ dpkg-statoverride --remove $i
+ fi
+done
+ </example>
</p>
</sect1>
</sect>
use <file>/usr/bin/sensible-editor</file> and
<file>/usr/bin/sensible-pager</file> as the editor or pager
program respectively. These are two scripts provided in the
- Debian base system that check the EDITOR and PAGER variables
- and launch the appropriate program, and fall back to
- <file>/usr/bin/editor</file> and <file>/usr/bin/pager</file> if the
- variable is not set.
+ <package>sensible-utils</package> package that check the EDITOR
+ and PAGER variables and launch the appropriate program, and fall
+ back to <file>/usr/bin/editor</file>
+ and <file>/usr/bin/pager</file> if the variable is not set.
</p>
<p>
</p>
</sect1>
- <sect1>
+ <sect1 id="appdefaults">
<heading>Application defaults files</heading>
<p>
<heading>Installation directory issues</heading>
<p>
- Packages using the X Window System should not be
- configured to install files under the
- <file>/usr/X11R6/</file> directory. The
- <file>/usr/X11R6/</file> directory hierarchy should be
+ Historically, packages using the X Window System used a
+ separate set of installation directories from other packages.
+ This practice has been discontinued and packages using the X
+ Window System should now generally be installed in the same
+ directories as any other package. Specifically, packages must
+ not install files under the <file>/usr/X11R6/</file> directory
+ and the <file>/usr/X11R6/</file> directory hierarchy should be
regarded as obsolete.
</p>
<p>
- Programs that use GNU <prgn>autoconf</prgn> and
- <prgn>automake</prgn> are usually easily configured at
- compile time to use <file>/usr/</file> instead of
- <file>/usr/X11R6/</file>, and this should be done whenever
- possible. Configuration files for window managers and
- display managers should be placed in a subdirectory of
- <file>/etc/X11/</file> corresponding to the package name due
- to these programs' tight integration with the mechanisms
- of the X Window System. Application-level programs should
- use the <file>/etc/</file> directory unless otherwise mandated
- by policy.
+ Include files previously installed under
+ <file>/usr/X11R6/include/X11/</file> should be installed into
+ <file>/usr/include/X11/</file>. For files previously
+ installed into subdirectories of
+ <file>/usr/X11R6/lib/X11/</file>, package maintainers should
+ determine if subdirectories of <file>/usr/lib/</file> and
+ <file>/usr/share/</file> can be used. If not, a subdirectory
+ of <file>/usr/lib/X11/</file> should be used.
</p>
<p>
- The installation of files into subdirectories
- of <file>/usr/X11R6/include/X11/</file> and
- <file>/usr/X11R6/lib/X11/</file> is now prohibited;
- package maintainers should determine if subdirectories of
- <file>/usr/lib/</file> and <file>/usr/share/</file> can be used
- instead.
- </p>
-
- <p>
- Packages should install any relevant files into the
- directories <file>/usr/include/X11/</file> and
- <file>/usr/lib/X11/</file>, but if they do so, they must
- pre-depend on <tt>x11-common (>=
- 1:7.0.0)</tt><footnote>
- <p>
- These libraries used to be all symbolic
- links. However, with <tt>X11R7</tt>,
- <tt>/usr/include/X11</tt> and <tt>/usr/lib/X11</tt>
- are now real directories, and packages
- <strong>should</strong> ship their files here instead
- of in <tt>/usr/X11R6/{include,lib}/X11</tt>.
- <tt>x11-common (>= 1:7.0.0) </tt> is the package
- responsible for converting these symlinks into
- directories.
- </p>
- </footnote>
+ Configuration files for window, display, or session managers
+ or other applications that are tightly integrated with the X
+ Window System may be placed in a subdirectory
+ of <file>/etc/X11/</file> corresponding to the package name.
+ Other X Window System applications should use
+ the <file>/etc/</file> directory unless otherwise mandated by
+ policy (such as for <ref id="appdefaults">).
</p>
</sect1>
</footnote>
</p>
- <p>
- Due to limitations in current implementations, all characters
- in the manual page source should be representable in the usual
- legacy encoding for that language, even if the file is
- actually encoded in UTF-8. Safe alternative ways to write many
- characters outside that range may be found in
- <manref name="groff_char" section="7">.
- </p>
-
<p>
If a localized version of a manual page is provided, it should
either be up-to-date or it should be obvious to the reader that
</p>
<p>
- Your package should call <prgn>install-info</prgn> to update
- the Info <file>dir</file> file in its <prgn>postinst</prgn>
- script when called with a <tt>configure</tt> argument, for
- example:
- <example compact="compact">
-install-info --quiet --section Development Development \
- /usr/share/info/foobar.info
- </example></p>
-
- <p>
- It is a good idea to specify a section for the location of
- your program; this is done with the <tt>--section</tt>
- switch. To determine which section to use, you should look
- at <file>/usr/share/info/dir</file> on your system and choose the most
- relevant (or create a new section if none of the current
- sections are relevant). Note that the <tt>--section</tt>
- flag takes two arguments; the first is a regular expression
- to match (case-insensitively) against an existing section,
- the second is used when creating a new one.</p>
-
- <p>
- You should remove the entries in the <prgn>prerm</prgn>
- script when called with a <tt>remove</tt> argument:
- <example compact="compact">
-install-info --quiet --remove /usr/share/info/foobar.info
- </example></p>
-
- <p>
- If <prgn>install-info</prgn> cannot find a description entry
- in the Info file you must supply one. See <manref
- name="install-info" section="8"> for details.</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.
+ </p>
+
+ <p>
+ Info documents should contain section and directory entry
+ information in the document for the use
+ of <prgn>install-info</prgn>. The section should be specified
+ via a line starting with <tt>INFO-DIR-SECTION</tt> followed by a
+ space and the section of this info page. The directory entry or
+ entries should be included between
+ a <tt>START-INFO-DIR-ENTRY</tt> line and
+ an <tt>END-INFO-DIR-ENTRY</tt> line. For example:
+ <example>
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* example: (example). An example info directory entry.
+END-INFO-DIR-ENTRY
+ </example>
+ To determine which section to use, you should look
+ at <file>/usr/share/info/dir</file> on your system and choose
+ the most relevant (or create a new section if none of the
+ current sections are relevant).<footnote>
+ Normally, info documents are generated from Texinfo source.
+ To include this information in the generated info document, if
+ it is absent, add commands like:
+ <example>
+@dircategory Individual utilities
+@direntry
+* example: (example). An example info directory entry.
+@end direntry
+ </example>
+ to the Texinfo source of the document and ensure that the info
+ documents are rebuilt from source during the package build.
+ </footnote>
+ </p>
</sect>
<sect>
projects / debian / debian-policy.git / blobdiff