<em>ruby</em>, <em>science</em>, <em>shells</em>, <em>sound</em>,
<em>tex</em>, <em>text</em>, <em>utils</em>, <em>vcs</em>,
<em>video</em>, <em>web</em>, <em>x11</em>, <em>xfce</em>,
- <em>zope</em>.
+ <em>zope</em>. The additional section <em>debian-installer</em>
+ contains special packages used by the installer and is not used
+ for normal Debian packages.
+ </p>
+
+ <p>
+ For more information about the sections and their definitions,
+ see the <url id="http://packages.debian.org/unstable/"
+ name="list of sections in unstable">.
</p>
</sect>
</p>
<p>
- The <var>date</var> must be in RFC822 format<footnote>
- This is generated by <tt>date -R</tt>.
- </footnote>; it must include the time zone specified
- numerically, with the time zone name or abbreviation
- optionally present as a comment in parentheses.
+ The <var>date</var> has the following format<footnote>
+ This is the same as the format generated by <tt>date
+ -R</tt>.
+ </footnote> (compatible and with the same semantics of
+ RFC 2822 and RFC 5322):
+ <example>day-of-week, dd month yyyy hh:mm:ss +zzzz</example>
+ where:
+ <list compact="compact">
+ <item>
+ day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun
+ </item>
+ <item>
+ dd is a one- or two-digit day of the month (01-31)
+ </item>
+ <item>
+ month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug,
+ Sep, Oct, Nov, Dec
+ </item>
+ <item>yyyy is the four-digit year (e.g. 2010)</item>
+ <item>hh is the two-digit hour (00-23)</item>
+ <item>mm is the two-digit minutes (00-59)</item>
+ <item>ss is the two-digit seconds (00-60)</item>
+ <item>
+ +zzzz or -zzzz is the the time zone offset from Coordinated
+ Universal Time (UTC). "+" indicates that the time is ahead
+ of (i.e., east of) UTC and "-" indicates that the time is
+ behind (i.e., west of) UTC. The first two digits indicate
+ the hour difference from UTC and the last two digits
+ indicate the number of additional minutes difference from
+ UTC. The last two digits must be in the range 00-59.
+ </item>
+ </list>
</p>
<p>
A package may also provide both of the targets
<tt>build-arch</tt> and <tt>build-indep</tt>.
The <tt>build-arch</tt> target, if provided, should
- perform all the configuration and compilation required
- for producing all architecture-dependant binary packages
- (those packages for which the body of the
- <tt>Architecture</tt> field in <tt>debian/control</tt>
- is not <tt>all</tt>).
- Similarly, the <tt>build-indep</tt> target, if
- provided, should perform all the configuration and
- compilation required for producing all
- architecture-independent binary packages
+ perform all the configuration and compilation required for
+ producing all architecture-dependant binary packages
(those packages for which the body of the
- <tt>Architecture</tt> field in <tt>debian/control</tt>
- is <tt>all</tt>).
+ <tt>Architecture</tt> field in <tt>debian/control</tt> is
+ not <tt>all</tt>). Similarly, the <tt>build-indep</tt>
+ target, if provided, should perform all the configuration
+ and compilation required for producing all
+ architecture-independent binary packages (those packages
+ for which the body of the <tt>Architecture</tt> field
+ in <tt>debian/control</tt> is <tt>all</tt>).
The <tt>build</tt> target should depend on those of the
targets <tt>build-arch</tt> and <tt>build-indep</tt> that
- are provided in the rules file.
+ are provided in the rules file.<footnote>
+ The intent of this split is so that binary-only builds
+ need not install the dependencies required for
+ the <tt>build-indep</tt> target. However, this is not
+ yet used in practice since <tt>dpkg-buildpackage
+ -B</tt>, and therefore the autobuilders,
+ invoke <tt>build</tt> rather than <tt>build-arch</tt>
+ due to the difficulties in determining whether the
+ optional <tt>build-arch</tt> target exists.
+ </footnote>
</p>
<p>
The syntax and semantics of the fields are described below.
</p>
-<!-- stuff -->
-
<p>
These fields are used by <prgn>dpkg-gencontrol</prgn> to
generate control files for binary packages (see below), by
<list compact="compact">
<item><qref id="f-Format"><tt>Format</tt></qref> (mandatory)</item>
<item><qref id="f-Source"><tt>Source</tt></qref> (mandatory)</item>
+ <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
+ <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
<item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
<item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
<item><qref id="f-Uploaders"><tt>Uploaders</tt></qref></item>
- <item><qref id="f-Binary"><tt>Binary</tt></qref></item>
- <item><qref id="f-Architecture"><tt>Architecture</tt></qref></item>
- <item><qref id="sourcebinarydeps"><tt>Build-Depends</tt> et al</qref></item>
+ <item><qref id="f-Homepage"><tt>Homepage</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-Checksums"><tt>Checksums-Sha1</tt>
+ and <tt>Checksums-Sha256</tt> (recommended)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
- <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
</list>
</p>
<item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
<item><qref id="f-Closes"><tt>Closes</tt></qref></item>
<item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
+ <item><qref id="f-Checksums"><tt>Checksums-Sha1</tt>
+ and <tt>Checksums-Sha256</tt> (recommended)</item>
<item><qref id="f-Files"><tt>Files</tt></qref> (mandatory)</item>
</list>
</p>
<item>
An architecture wildcard identifying a set of Debian
machine architectures, see <ref id="arch-wildcard-spec">.
+ <tt>any</tt> matches all Debian machine architectures
+ and is the most frequently used.
</item>
<item>
<tt>all</tt>, which indicates an
<p>
In the main <file>debian/control</file> file in the source
- package, this field may contain the special value <tt>all</tt>
- or a list of specific and wildcard architectures separated by
- spaces. If <tt>all</tt> appears, that value must be the
- entire contents of the field. Most packages will use
- either <tt>any</tt> or <tt>all</tt>. Specifying a specific
- list of architectures is for the minority of cases where a
+ package, this field may contain the special
+ value <tt>all</tt>, the special architecture
+ wildcard <tt>any</tt>, or a list of specific and wildcard
+ architectures separated by spaces. If <tt>all</tt>
+ or <tt>any</tt> appears, that value must be the entire
+ contents of the field. Most packages will use
+ either <tt>all</tt> or <tt>any</tt>.
+ </p>
+
+ <p>
+ Specifying a specific list of architectures indicates that the
+ source will build an architecture-dependent package only on
+ architectures included in the list. Specifying a list of
+ architecture wildcards indicates that the source will build an
+ architecture-dependent package on only those architectures
+ that match any of the specified architecture wildcards.
+ Specifying a list of architectures or architecture wildcards
+ other than <tt>any</tt> is for the minority of cases where a
program is not portable or is not useful on some
- architectures, and where possible the program should be made
+ architectures. Where possible, the program should be made
portable instead.
</p>
- <p>
- Specifying a list of architecture wildcards indicates that
- the source will build an architecture-dependent package on
- the union of the lists of architectures from the expansion
- of each specified architecture wildcard, and will only
- work correctly on the architectures in the union of the
- lists.<footnote>
- Use of architecture wildcards other than <tt>all</tt> is for
- a minority of cases where the program is not portable and
- should not be used for most packages. Wildcards are not
- expanded into a list of known architectures before comparing
- to the build architecutre. Instead, the build architecture
- is matched against any wildcards and this package is built
- if any wildcard matches.
- </footnote>
- </p>
-
<p>
In the source package control file <file>.dsc</file>, this
- field may contain either the special value <tt>any</tt> or a
- list of architectures separated by spaces. If a list is given,
- it may include (or consist solely of) the special value
- <tt>all</tt>. In other words, in <file>.dsc</file> files
- unlike the <file>debian/control</file>, <tt>all</tt> may occur
- in combination with specific architectures. The
- <tt>Architecture</tt> field in the source package control file
- <file>.dsc</file> is generally constructed from the
- <tt>Architecture</tt> fields in the
- <file>debian/control</file> in the source package.
+ field may contain either the architecture
+ wildcard <tt>any</tt> or a list of architectures and
+ architecture wildcards separated by spaces. If a list is
+ given, it may include (or consist solely of) the special
+ value <tt>all</tt>. In other words, in <file>.dsc</file>
+ files unlike the <file>debian/control</file>, <tt>all</tt> may
+ occur in combination with specific architectures.
+ The <tt>Architecture</tt> field in the source package control
+ file <file>.dsc</file> is generally constructed from
+ the <tt>Architecture</tt> fields in
+ the <file>debian/control</file> in the source package.
</p>
<p>
package is also being uploaded, the special
entry <tt>source</tt> is also present. <tt>all</tt> will be
present if any architecture-independent packages are being
- uploaded. Architecture wildcards such as <tt>any</tt> may
+ uploaded. Architecture wildcards such as <tt>any</tt> must
never occur in the <tt>Architecture</tt> field in
the <file>.changes</file> file.
</p>
<em>not</em> intended to cope with version numbers containing
strings of letters which the package management system cannot
interpret (such as <tt>ALPHA</tt> or <tt>pre-</tt>), or with
- silly orderings (the author of this manual has heard of a
- package whose versions went <tt>1.1</tt>, <tt>1.2</tt>,
- <tt>1.3</tt>, <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>,
- <tt>2</tt> and so forth).
+ silly orderings.<footnote>
+ The author of this manual has heard of a package whose
+ versions went <tt>1.1</tt>, <tt>1.2</tt>, <tt>1.3</tt>,
+ <tt>1</tt>, <tt>2.1</tt>, <tt>2.2</tt>, <tt>2</tt> and so
+ forth.
+ </footnote>
</p>
</sect1>
<heading><tt>Date</tt></heading>
<p>
- This field includes the date the package was built or last edited.
+ This field includes the date the package was built or last
+ edited. It must be in the same format as the <var>date</var>
+ in a <file>debian/changelog</file> entry.
</p>
<p>
</p>
</sect1>
+ <sect1 id="f-Checksums">
+ <heading><tt>Checksums-Sha1</tt>
+ and <tt>Checksums-Sha256</tt></heading>
+
+ <p>
+ These fields contain a list of files with a checksum and size
+ for each one. Both <tt>Checksums-Sha1</tt>
+ and <tt>Checksums-Sha256</tt> have the same syntax and differ
+ only in the checksum algorithm used: SHA-1
+ for <tt>Checksums-Sha1</tt> and SHA-256
+ for <tt>Checksums-Sha256</tt>.
+ </p>
+
+ <p>
+ <tt>Checksums-Sha1</tt> and <tt>Checksums-Sha256</tt> are
+ multiline fields. The first line of the field value (the part
+ on the same line as <tt>Checksums-Sha1:</tt>
+ or <tt>Checksums-Sha256:</tt>) is always empty. The content
+ of the field is expressed as continuation lines, one line per
+ file. Each line consists of the checksum, a space, the file
+ size, a space, and the file name. For example (from
+ a <file>.changes</file> file):
+ <example>
+Checksums-Sha1:
+ 1f418afaa01464e63cc1ee8a66a05f0848bd155c 1276 example_1.0-1.dsc
+ a0ed1456fad61116f868b1855530dbe948e20f06 171602 example_1.0.orig.tar.gz
+ 5e86ecf0671e113b63388dac81dd8d00e00ef298 6137 example_1.0-1.debian.tar.gz
+ 71a0ff7da0faaf608481195f9cf30974b142c183 548402 example_1.0-1_i386.deb
+Checksums-Sha256:
+ ac9d57254f7e835bed299926fd51bf6f534597cc3fcc52db01c4bffedae81272 1276 example_1.0-1.dsc
+ 0d123be7f51e61c4bf15e5c492b484054be7e90f3081608a5517007bfb1fd128 171602 example_1.0.orig.tar.gz
+ f54ae966a5f580571ae7d9ef5e1df0bd42d63e27cb505b27957351a495bc6288 6137 example_1.0-1.debian.tar.gz
+ 3bec05c03974fdecd11d020fc2e8250de8404867a8a2ce865160c250eb723664 548402 example_1.0-1_i386.deb
+ </example>
+ </p>
+
+ <p>
+ In the <file>.dsc</file> file, these fields should list all
+ files that make up the source package. In
+ the <file>.changes</file> file, these fields should list all
+ files being uploaded. The list of files in these fields
+ must match the list of files in the <tt>Files</tt> field.
+ </p>
+ </sect1>
+
</sect>
<sect>
<heading>Controlling terminal for maintainer scripts</heading>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- Because these scripts may be executed with standard output
- redirected into a pipe for logging purposes, Perl scripts
- should set unbuffered output by setting <tt>$|=1</tt> so
- that the output is printed immediately rather than being
- buffered.
+ Maintainer scripts are not guaranteed to run with a controlling
+ terminal and may not be able to interact with the user. They
+ must be able to fall back to noninteractive behavior if no
+ controlling terminal is available. Maintainer scripts that
+ prompt via a program conforming to the Debian Configuration
+ Management Specification (see <ref id="maintscriptprompt">) may
+ assume that program will handle falling back to noninteractive
+ behavior.
+ </p>
+
+ <p>
+ For high-priority prompts without a reasonable default answer,
+ maintainer scripts may abort if there is no controlling
+ terminal. However, this situation should be avoided if at all
+ possible, since it prevents automated or unattended installs.
+ In most cases, users will consider this to be a bug in the
+ package.
</p>
</sect>
+
<sect id="exitstatus">
<heading>Exit status</heading>
will no longer be listed as "owned" by the old package.
</p>
+ <p>
+ For example, if a package <package>foo</package> is split
+ into <package>foo</package> and <package>foo-data</package>
+ starting at version 1.2-3, <package>foo-data</package> should
+ have the field
+ <example compact="compact">
+Replaces: foo (<< 1.2-3)
+ </example>
+ in its control file. The package <package>foo</package>
+ doesn't need any special control fields in this example,
+ although would generally depend on or
+ recommend <package>foo-data</package>.
+ </p>
+
<p>
If a package is completely replaced in this way, so that
<prgn>dpkg</prgn> does not know of any files it still
The dependencies and conflicts they define must be satisfied
(as defined earlier for binary packages) in order to invoke
the targets in <tt>debian/rules</tt>, as follows:<footnote>
- <p>
- If you make "build-arch" or "binary-arch", you need
- Build-Depends. If you make "build-indep" or
- "binary-indep", you need Build-Depends and
- Build-Depends-Indep. If you make "build" or "binary",
- you need both.
- </p>
<p>
There is no Build-Depends-Arch; this role is essentially
- met with Build-Depends. Anyone building the
- <tt>build-indep</tt> and binary-indep<tt></tt> targets
- is basically assumed to be building the whole package
- anyway and so installs all build dependencies. The
- autobuilders use <tt>dpkg-buildpackage -B</tt>, which
- calls <tt>build</tt> (not <tt>build-arch</tt>, since it
- does not yet know how to check for its existence) and
- <tt>binary-arch</tt>.
+ met with Build-Depends. Anyone building the
+ <tt>build-indep</tt> and binary-indep<tt></tt> targets is
+ assumed to be building the whole package, and therefore
+ installation of all build dependencies is required.
</p>
<p>
- The purpose of the original split, I recall, was so that
- the autobuilders wouldn't need to install extra packages
- needed only for the binary-indep targets. But without a
- build-arch/build-indep split, this didn't work, since
- most of the work is done in the build target, not in the
- binary target.
+ The autobuilders use <tt>dpkg-buildpackage -B</tt>, which
+ calls <tt>build</tt>, not <tt>build-arch</tt> since it does
+ not yet know how to check for its existence, and
+ <tt>binary-arch</tt>. The purpose of the original split
+ between <tt>Build-Depends</tt> and
+ <tt>Build-Depends-Indep</tt> was so that the autobuilders
+ wouldn't need to install extra packages needed only for the
+ binary-indep targets. But without a build-arch/build-indep
+ split, this didn't work, since most of the work is done in
+ the build target, not in the binary target.
</p>
</footnote>
-
<taglist>
- <tag><tt>Build-Depends</tt>, <tt>Build-Conflicts</tt></tag>
+ <tag><tt>clean</tt>, <tt>build-arch</tt>, and
+ <tt>binary-arch</tt></tag>
<item>
- The <tt>Build-Depends</tt> and
- <tt>Build-Conflicts</tt> fields must be satisfied when
- any of the following targets is invoked:
- <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
- <tt>binary-arch</tt>, <tt>build-arch</tt>,
- <tt>build-indep</tt> and <tt>binary-indep</tt>.
+ Only the <tt>Build-Depends</tt> and <tt>Build-Conflicts</tt>
+ fields must be satisfied when these targets are invoked.
</item>
- <tag><tt>Build-Depends-Indep</tt>,
- <tt>Build-Conflicts-Indep</tt></tag>
+ <tag><tt>build</tt>, <tt>build-indep</tt>, <tt>binary</tt>,
+ and <tt>binary-indep</tt></tag>
<item>
- The <tt>Build-Depends-Indep</tt> and
- <tt>Build-Conflicts-Indep</tt> fields must be
- satisfied when any of the following targets is
- invoked: <tt>build</tt>, <tt>build-indep</tt>,
- <tt>binary</tt> and <tt>binary-indep</tt>.
+ The <tt>Build-Depends</tt>, <tt>Build-Conflicts</tt>,
+ <tt>Build-Depends-Indep</tt>, and
+ <tt>Build-Conflicts-Indep</tt> fields must be satisfied when
+ these targets are invoked.
</item>
</taglist>
</p>
-
</sect>
-
</chapt>
</p>
</item>
- <tag>1000-29999:</tag>
+ <tag>1000-59999:</tag>
<item>
<p>
Dynamically allocated user accounts. By default
</p>
</item>
- <tag>30000-59999:</tag>
- <item>
- <p>Reserved.</p>
- </item>
-
<tag>60000-64999:</tag>
<item>
<p>
</p>
</sect1>
- <sect1>
+ <sect1 id="writing-init">
<heading>Writing the scripts</heading>
<p>
option.
</p>
+ <p>
+ Be careful of using <tt>set -e</tt> in <file>init.d</file>
+ scripts. Writing correct <file>init.d</file> scripts requires
+ accepting various error exit statuses when daemons are already
+ running or already stopped without aborting
+ the <file>init.d</file> script, and common <file>init.d</file>
+ function libraries are not safe to call with <tt>set -e</tt>
+ in effect<footnote>
+ <tt>/lib/lsb/init-functions</tt>, which assists in writing
+ LSB-compliant init scripts, may fail if <tt>set -e</tt> is
+ in effect and echoing status messages to the console fails,
+ for example.
+ </footnote>. For <tt>init.d</tt> scripts, it's often easier
+ to not use <tt>set -e</tt> and instead check the result of
+ each command separately.
+ </p>
+
<p>
If a service reloads its configuration automatically (as
in the case of <prgn>cron</prgn>, for example), the
language currently used to implement it.
</p>
<p>
- Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>)
- should almost certainly start with <tt>set -e</tt> so that
- errors are detected. Every script should use
- <tt>set -e</tt> or check the exit status of <em>every</em>
- command.
+ Shell scripts (<prgn>sh</prgn> and <prgn>bash</prgn>) other than
+ <file>init.d</file> scripts should almost certainly start
+ with <tt>set -e</tt> so that errors are detected.
+ <file>init.d</file> scripts are something of a special case, due
+ to how frequently they need to call commands that are allowed to
+ fail, and it may instead be easier to check the exit status of
+ commands directly. See <ref id="writing-init"> for more
+ information about writing <file>init.d</file> scripts.
+ </p>
+ <p>
+ Every script should use <tt>set -e</tt> or check the exit status
+ of <em>every</em> command.
</p>
-
<p>
Scripts may assume that <file>/bin/sh</file> implements the
SUSv3 Shell Command Language<footnote>
package is purged.
</item>
</list>
+ Obsolete configuration files without local changes may be
+ removed by the package during upgrade.
</p>
<p>
security policy by changing the permissions on a binary:
they can do this by using <prgn>dpkg-statoverride</prgn>, as
described below.<footnote>
- Ordinary files installed by <prgn>dpkg</prgn> (as
- opposed to <tt>conffile</tt>s and other similar objects)
- normally have their permissions reset to the distributed
- permissions when the package is reinstalled. However,
- the use of <prgn>dpkg-statoverride</prgn> overrides this
- default behavior. If you use this method, you should
- remember to describe <prgn>dpkg-statoverride</prgn> in
- the package documentation; being a relatively new
- addition to Debian, it is probably not yet well-known.
+ Ordinary files installed by <prgn>dpkg</prgn> (as
+ opposed to <tt>conffile</tt>s and other similar objects)
+ normally have their permissions reset to the distributed
+ permissions when the package is reinstalled. However,
+ the use of <prgn>dpkg-statoverride</prgn> overrides this
+ default behavior.
</footnote>
Another method you should consider is to create a group for
people allowed to use the program(s) and make any setuid
<p>
If a program needs to specify an <em>architecture specification
- string</em> in some place, it should select one of the
- strings provided by <tt>dpkg-architecture -L</tt>. The
- strings are in the format
- <tt><var>os</var>-<var>arch</var></tt>, though the OS part
- is sometimes elided, as when the OS is Linux.<footnote>
- <p>Currently, the strings are:
- i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips
- mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb
- sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64
- darwin-armeb darwin-arm darwin-hppa darwin-m32r
- darwin-m68k darwin-mips darwin-mipsel darwin-powerpc
- darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3
- darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc
- freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64
- freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r
- freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc
- freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3
- freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc
- kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha
- kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa
- kfreebsd-m32r kfreebsd-m68k kfreebsd-mips
- kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64
- kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb
- kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386
- knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb
- knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k
- knetbsd-mips knetbsd-mipsel knetbsd-powerpc
- knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3
- knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc
- netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64
- netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r
- netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc
- netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3
- netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc
- openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64
- openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r
- openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc
- openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3
- openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc
- hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb
- hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips
- hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x
- hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc
- </p>
- </footnote>
+ string</em> in some place, it should select one of the strings
+ provided by <tt>dpkg-architecture -L</tt>. The strings are in
+ the format <tt><var>os</var>-<var>arch</var></tt>, though the OS
+ part is sometimes elided, as when the OS is Linux.
</p>
<p>
<tt><var>arch</var>-unknown-linux</tt>, since the
<tt>unknown</tt> does not look very good.
</p>
- </sect>
- <sect id="arch-wildcard-spec">
- <heading>Architecture Wildcards</heading>
+ <sect1 id="arch-wildcard-spec">
+ <heading>Architecture wildcards</heading>
- <p>
- A package may specify an architecture wildcard. Architecture
- wildcards are in the format <tt>any</tt> (which matches every
- architecture), <tt><var>os</var></tt>-any, or
- any-<tt><var>cpu</var></tt>. <footnote>
- Internally, the package system normalizes the GNU triplets and
- the Debian arches into Debian arch triplets (which are kind of
- inverted GNU triplets), with the first component of the
- triplet representing the libc and ABI in use. When matching
- two Debian arch triplets, whenever an <var>any</var> is found
- it matches with anything on the other side, like in:
- <example>
- gnu-linux-i386 is matched by gnu-linux-any
- gnu-kfreebsd-amd64 is matched by any-any-amd64
- </example>
- And, for example, <var>any</var> is normalized to
- <var>any-any-any</var>.
- </footnote>
- </p>
+ <p>
+ A package may specify an architecture wildcard. Architecture
+ wildcards are in the format <tt>any</tt> (which matches every
+ architecture), <tt><var>os</var></tt>-any, or
+ any-<tt><var>cpu</var></tt>. <footnote>
+ Internally, the package system normalizes the GNU triplets
+ and the Debian arches into Debian arch triplets (which are
+ kind of inverted GNU triplets), with the first component of
+ the triplet representing the libc and ABI in use, and then
+ does matching against those triplets. However, such
+ triplets are an internal implementation detail that should
+ not be used by packages directly. The libc and ABI portion
+ is handled internally by the package system based on
+ the <var>os</var> and <var>cpu</var>.
+ </footnote>
+ </p>
+ </sect1>
</sect>
<sect>
name="Man-Page-HOWTO">,
<manref name="man" section="7">, the examples
created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
- the helper program
s <prgn>help2man</prgn>, or the
+ the helper program <prgn>help2man</prgn>, or the
directory <file>/usr/share/doc/man-db/examples</file>.
</footnote>
</p>
</p>
<p>
- Packages distributed under the UCB BSD license, the Apache
- license (version 2.0), the Artistic license, the GNU GPL
- (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and the
- GNU FDL (versions 1.2 or 1.3) should refer to the corresponding
- files under <file>/usr/share/common-licenses</file>,<footnote>
+ Packages distributed under the Apache license (version 2.0), the
+ Artistic license, the GNU GPL (version 2 or 3), the GNU LGPL
+ (versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or 1.3)
+ should refer to the corresponding files
+ under <file>/usr/share/common-licenses</file>,<footnote>
<p>
In particular,
- <file>/usr/share/common-licenses/BSD</file>,
<file>/usr/share/common-licenses/Apache-2.0</file>,
<file>/usr/share/common-licenses/Artistic</file>,
<file>/usr/share/common-licenses/GPL-2</file>,
<file>/usr/share/common-licenses/LGPL-3</file>,
<file>/usr/share/common-licenses/GFDL-1.2</file>, and
<file>/usr/share/common-licenses/GFDL-1.3</file>
- respectively.
+ respectively. The University of California BSD license is
+ also included in <package>base-files</package> as
+ <file>/usr/share/common-licenses/BSD</file>, but given the
+ brevity of this license, its specificity to code whose
+ copyright is held by the Regents of the University of
+ California, and the frequency of minor wording changes, its
+ text should be included in the copyright file rather than
+ referencing this file.
</p>
</footnote> rather than quoting them in the copyright
file.
</p>
<p>
- The maintainer scripts are guaranteed to run with a
- controlling terminal and can interact with the user.
- See <ref id="controllingterminal">.
+ The maintainer scripts are not guaranteed to run with a
+ controlling terminal and may not be able to interact with
+ the user. See <ref id="controllingterminal">.
</p>
</item>
</p>
</sect1>
-
- <sect1 id="pkg-dpkgchangelog">
- <heading><file>debian/changelog</file></heading>
-
- <p>
- See <ref id="dpkgchangelog">.
- </p>
-
- <sect2><heading>Defining alternative changelog formats
- </heading>
-
- <p>
- It is possible to use a different format to the standard
- one, by providing a parser for the format you wish to
- use.
- </p>
-
- <p>
- In order to have <tt>dpkg-parsechangelog</tt> run your
- parser, you must include a line within the last 40 lines
- of your file matching the Perl regular expression:
- <tt>\schangelog-format:\s+([0-9a-z]+)\W</tt> The part in
- parentheses should be the name of the format. For
- example, you might say:
- <example>
- @@@ changelog-format: joebloggs @@@
- </example>
- Changelog format names are non-empty strings of alphanumerics.
- </p>
-
- <p>
- If such a line exists then <tt>dpkg-parsechangelog</tt>
- will look for the parser as
- <file>/usr/lib/dpkg/parsechangelog/<var>format-name</var></file>
- or
- <file>/usr/local/lib/dpkg/parsechangelog/<var>format-name</var></file>;
- it is an error for it not to find it, or for it not to
- be an executable program. The default changelog format
- is <tt>dpkg</tt>, and a parser for it is provided with
- the <tt>dpkg</tt> package.
- </p>
-
- <p>
- The parser will be invoked with the changelog open on
- standard input at the start of the file. It should read
- the file (it may seek if it wishes) to determine the
- information required and return the parsed information
- to standard output in the form of a series of control
- fields in the standard format. By default it should
- return information about only the most recent version in
- the changelog; it should accept a
- <tt>-v<var>version</var></tt> option to return changes
- information from all versions present <em>strictly
- after</em> <var>version</var>, and it should then be an
- error for <var>version</var> not to be present in the
- changelog.
- </p>
-
- <p>
- The fields are:
- <list compact="compact">
- <item><qref id="f-Source"><tt>Source</tt></qref></item>
- <item><qref id="f-Version"><tt>Version</tt></qref> (mandatory)</item>
- <item><qref id="f-Distribution"><tt>Distribution</tt></qref> (mandatory)</item>
- <item><qref id="f-Urgency"><tt>Urgency</tt></qref> (mandatory)</item>
- <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
- <item><qref id="f-Date"><tt>Date</tt></qref></item>
- <item><qref id="f-Changes"><tt>Changes</tt></qref> (mandatory)</item>
- </list>
- </p>
-
- <p>
- If several versions are being returned (due to the use
- of <tt>-v</tt>), the urgency value should be of the
- highest urgency code listed at the start of any of the
- versions requested followed by the concatenated
- (space-separated) comments from all the versions
- requested; the maintainer, version, distribution and
- date should always be from the most recent version.
- </p>
-
- <p>
- For the format of the <tt>Changes</tt> field see
- <ref id="f-Changes">.
- </p>
-
- <p>
- If the changelog format which is being parsed always or
- almost always leaves a blank line between individual
- change notes these blank lines should be stripped out,
- so as to make the resulting output compact.
- </p>
-
- <p>
- If the changelog format does not contain date or package
- name information this information should be omitted from
- the output. The parser should not attempt to synthesize
- it or find it from other sources.
- </p>
-
- <p>
- If the changelog does not have the expected format the
- parser should exit with a nonzero exit status, rather
- than trying to muddle through and possibly generating
- incorrect output.
- </p>
-
- <p>
- A changelog parser may not interact with the user at
- all.
- </p>
- </sect2>
- </sect1>
-
<sect1 id="pkg-srcsubstvars">
<heading><file>debian/substvars</file> and variable substitutions</heading>
projects / debian / debian-policy.git / blobdiff