--- Begin Message ---
Package: debian-policy
Version: 3.8.0.1
Severity: wishlist
Owner: [email protected]
Tags: patch
As stated in my thread on debian-policy [1], I intend to clean up the
policy documents.
I'd been looking into this for quite a bit, and I'm at an impasse: I
can't seem to determine what appendices should go.
I'm proposing that the appendices <appendix id=pkg-*> be removed from
policy.sgml for now [2], and look at it as "what from this should remain
in policy or be funnelled elsewhere" instead of "what to remove from
policy.sgml".
[1] Thread beginning with Message-id: <20100904225747.GA27724@esterhazy>
[2] And possibly saved to a separate file somewhere until the info gets
to where it needs to go?
-- System Information:
Debian Release: 5.0.6
APT prefers stable
APT policy: (750, 'stable'), (500, 'stable')
Architecture: i386 (i686)
Kernel: Linux 2.6.26-2-686 (SMP w/1 CPU core)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
debian-policy depends on no packages.
debian-policy recommends no packages.
Versions of packages debian-policy suggests:
pn doc-base <none> (no description available)
-- no debconf information
--
_ Brian Ryans 8B2A 54C4 E275 8CFD 8A7D 5D0B 0AD0 B014 C112 13D0 .
( ) ICQ 43190205 | Mail/Jabber/Yahoo/MSN: [email protected] ..:
X ASCII Ribbon Campaign Against HTML mail and v-cards: asciiribbon.org
/ \ Modern man has an approximately 140-character attention span. -- blr
From 25b4839e000bc696827519518a4c7d27ae76dcb9 Mon Sep 17 00:00:00 2001
From: Brian Ryans <[email protected]>
Date: Thu, 30 Sep 2010 12:46:54 -0500
Subject: [PATCH] policy cleanup: remove entire pkgman and refs
* Remove the Packaging Manual
* Remove references to the above
* Reformat paragraphs altered by reference removal
---
policy.sgml | 1450 +---------------------------------------------------------
1 files changed, 25 insertions(+), 1425 deletions(-)
diff --git a/policy.sgml b/policy.sgml
index 642f672..bfb79cd 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -117,11 +117,6 @@
</p>
<p>
- The appendices to this manual are not necessarily normative,
- either. Please see <ref id="pkg-scope"> for more information.
- </p>
-
- <p>
In the normative part of this manual,
the words <em>must</em>, <em>should</em> and
<em>may</em>, and the adjectives <em>required</em>,
@@ -2117,7 +2112,7 @@
<p>
The architectures we build on and build for are determined
by <prgn>make</prgn> variables using the
- utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
+ utility <prgn>dpkg-architecture</prgn>.
You can determine the Debian architecture and the GNU style
architecture specification string for the build architecture as
well as for the host architecture. The build architecture is
@@ -5641,12 +5636,11 @@ Replaces: mail-transport-agent
<p>
When a package is built which contains any shared libraries, it
- must provide a <file>shlibs</file> file for other packages to
- use. When a package is built which contains any shared
- libraries or compiled binaries, it must run
- <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
- on these to determine the libraries used and hence the
- dependencies needed by this package.<footnote>
+ must provide a <file>shlibs</file> file for other packages to use.
+ When a package is built which contains any shared libraries or
+ compiled binaries, it must run <prgn>dpkg-shlibdeps</prgn> on
+ these to determine the libraries used and hence the dependencies
+ needed by this package.<footnote>
<p>
<prgn>dpkg-shlibdeps</prgn> will use a program
like <prgn>objdump</prgn> or <prgn>readelf</prgn> to find
@@ -5699,11 +5693,10 @@ Replaces: mail-transport-agent
<heading>The <tt>shlibs</tt> files present on the system</heading>
<p>
- There are several places where <tt>shlibs</tt> files are
- found. The following list gives them in the order in which
- they are read by
- <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>.
- (The first one which gives the required information is used.)
+ There are several places where <tt>shlibs</tt> files are found.
+ The following list gives them in the order in which they are read
+ by <prgn>dpkg-shlibdeps</prgn>. (The first one which gives the
+ required information is used.)
</p>
<p>
@@ -5743,27 +5736,26 @@ Replaces: mail-transport-agent
files give details of any shared libraries included in the
same package.<footnote>
An example may help here. Let us say that the source
- package <tt>foo</tt> generates two binary
- packages, <tt>libfoo2</tt> and <tt>foo-runtime</tt>.
- When building the binary packages, the two packages are
- created in the directories <file>debian/libfoo2</file>
- and <file>debian/foo-runtime</file> respectively.
+ package <tt>foo</tt> generates two binary packages,
+ <tt>libfoo2</tt> and <tt>foo-runtime</tt>. When building
+ the binary packages, the two packages are created in the
+ directories <file>debian/libfoo2</file> and
+ <file>debian/foo-runtime</file> respectively.
(<file>debian/tmp</file> could be used instead of one of
these.) Since <tt>libfoo2</tt> provides the
<tt>libfoo</tt> shared library, it will require a
<tt>shlibs</tt> file, which will be installed in
<file>debian/libfoo2/DEBIAN/shlibs</file>, eventually to
become <file>/var/lib/dpkg/info/libfoo2.shlibs</file>.
- When <prgn>dpkg-shlibdeps</prgn> is run on the
- executable <file>debian/foo-runtime/usr/bin/foo-prog</file>,
- it will examine
- the <file>debian/libfoo2/DEBIAN/shlibs</file> file to
- determine whether <tt>foo-prog</tt>'s library
+ When <prgn>dpkg-shlibdeps</prgn> is run on the executable
+ <file>debian/foo-runtime/usr/bin/foo-prog</file>, it will
+ examine the <file>debian/libfoo2/DEBIAN/shlibs</file> file
+ to determine whether <tt>foo-prog</tt>'s library
dependencies are satisfied by any of the libraries
provided by <tt>libfoo2</tt>. For this reason,
<prgn>dpkg-shlibdeps</prgn> must only be run once all of
- the individual binary packages' <tt>shlibs</tt> files
- have been installed into the build directory.
+ the individual binary packages' <tt>shlibs</tt> files have
+ been installed into the build directory.
</footnote>
</p>
</item>
@@ -5798,11 +5790,10 @@ Replaces: mail-transport-agent
<file>shlibs</file> files</heading>
<p>
- Put a call to
- <qref id="pkg-dpkg-shlibdeps"><prgn>dpkg-shlibdeps</prgn></qref>
- into your <file>debian/rules</file> file. If your package
- contains only compiled binaries and libraries (but no scripts),
- you can use a command such as:
+ Put a call to <prgn>dpkg-shlibdeps</prgn> into your
+ <file>debian/rules</file> file. If your package contains only
+ compiled binaries and libraries (but no scripts), you can use a
+ command such as:
<example compact="compact">
dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
debian/tmp/usr/lib/*
@@ -9751,1397 +9742,6 @@ END-INFO-DIR-ENTRY
</sect>
</chapt>
- <appendix id="pkg-scope">
- <heading>Introduction and scope of these appendices</heading>
-
- <p>
- These appendices are taken essentially verbatim from the
- now-deprecated Packaging Manual, version 3.2.1.0. They are
- the chapters which are likely to be of use to package
- maintainers and which have not already been included in the
- policy document itself. Most of these sections are very likely
- not relevant to policy; they should be treated as
- documentation for the packaging system. Please note that these
- appendices are included for convenience, and for historical
- reasons: they used to be part of policy package, and they have
- not yet been incorporated into dpkg documentation. However,
- they still have value, and hence they are presented here.
- </p>
-
- <p>
- They have not yet been checked to ensure that they are
- compatible with the contents of policy, and if there are any
- contradictions, the version in the main policy document takes
- precedence. The remaining chapters of the old Packaging
- Manual have also not been read in detail to ensure that there
- are not parts which have been left out. Both of these will be
- done in due course.
- </p>
-
- <p>
- Certain parts of the Packaging manual were integrated into the
- Policy Manual proper, and removed from the appendices. Links
- have been placed from the old locations to the new ones.
- </p>
-
- <p>
- <prgn>dpkg</prgn> is a suite of programs for creating binary
- package files and installing and removing them on Unix
- systems.<footnote>
- <prgn>dpkg</prgn> is targeted primarily at Debian, but may
- work on or be ported to other systems.
- </footnote>
- </p>
-
- <p>
- The binary packages are designed for the management of
- installed executable programs (usually compiled binaries) and
- their associated data, though source code examples and
- documentation are provided as part of some packages.</p>
-
- <p>
- This manual describes the technical aspects of creating Debian
- binary packages (<file>.deb</file> files). It documents the
- behavior of the package management programs
- <prgn>dpkg</prgn>, <prgn>dselect</prgn> et al. and the way
- they interact with packages.</p>
-
- <p>
- It also documents the interaction between
- <prgn>dselect</prgn>'s core and the access method scripts it
- uses to actually install the selected packages, and describes
- how to create a new access method.</p>
-
- <p>
- This manual does not go into detail about the options and
- usage of the package building and installation tools. It
- should therefore be read in conjunction with those programs'
- man pages.
- </p>
-
- <p>
- The utility programs which are provided with <prgn>dpkg</prgn>
- for managing various system configuration and similar issues,
- such as <prgn>update-rc.d</prgn> and
- <prgn>install-info</prgn>, are not described in detail here -
- please see their man pages.
- </p>
-
- <p>
- It is assumed that the reader is reasonably familiar with the
- <prgn>dpkg</prgn> System Administrators' manual.
- Unfortunately this manual does not yet exist.
- </p>
-
- <p>
- The Debian version of the FSF's GNU hello program is provided as
- an example for people wishing to create Debian packages. However,
- while the examples are helpful, they do not replace the need to
- read and follow the Policy and Programmer's Manual.</p>
- </appendix>
-
- <appendix id="pkg-binarypkg">
- <heading>Binary packages (from old Packaging Manual)</heading>
-
- <p>
- The binary package has two main sections. The first part
- consists of various control information files and scripts used
- by <prgn>dpkg</prgn> when installing and removing. See <ref
- id="pkg-controlarea">.
- </p>
-
- <p>
- The second part is an archive containing the files and
- directories to be installed.
- </p>
-
- <p>
- In the future binary packages may also contain other
- components, such as checksums and digital signatures. The
- format for the archive is described in full in the
- <file>deb(5)</file> man page.
- </p>
-
-
- <sect id="pkg-bincreating"><heading>Creating package files -
- <prgn>dpkg-deb</prgn>
- </heading>
-
- <p>
- All manipulation of binary package files is done by
- <prgn>dpkg-deb</prgn>; it's the only program that has
- knowledge of the format. (<prgn>dpkg-deb</prgn> may be
- invoked by calling <prgn>dpkg</prgn>, as <prgn>dpkg</prgn>
- will spot that the options requested are appropriate to
- <prgn>dpkg-deb</prgn> and invoke that instead with the same
- arguments.)
- </p>
-
- <p>
- In order to create a binary package you must make a
- directory tree which contains all the files and directories
- you want to have in the file system data part of the package.
- In Debian-format source packages this directory is usually
- <file>debian/tmp</file>, relative to the top of the package's
- source tree.
- </p>
-
- <p>
- They should have the locations (relative to the root of the
- directory tree you're constructing) ownerships and
- permissions which you want them to have on the system when
- they are installed.
- </p>
-
- <p>
- With current versions of <prgn>dpkg</prgn> the uid/username
- and gid/groupname mappings for the users and groups being
- used should be the same on the system where the package is
- built and the one where it is installed.
- </p>
-
- <p>
- You need to add one special directory to the root of the
- miniature file system tree you're creating:
- <prgn>DEBIAN</prgn>. It should contain the control
- information files, notably the binary package control file
- (see <ref id="pkg-controlfile">).
- </p>
-
- <p>
- The <prgn>DEBIAN</prgn> directory will not appear in the
- file system archive of the package, and so won't be installed
- by <prgn>dpkg</prgn> when the package is installed.
- </p>
-
- <p>
- When you've prepared the package, you should invoke:
- <example>
- dpkg --build <var>directory</var>
- </example>
- </p>
-
- <p>
- This will build the package in
- <file><var>directory</var>.deb</file>. (<prgn>dpkg</prgn> knows
- that <tt>--build</tt> is a <prgn>dpkg-deb</prgn> option, so
- it invokes <prgn>dpkg-deb</prgn> with the same arguments to
- build the package.)
- </p>
-
- <p>
- See the man page <manref name="dpkg-deb" section="8"> for details of how
- to examine the contents of this newly-created file. You may find the
- output of following commands enlightening:
- <example>
- dpkg-deb --info <var>filename</var>.deb
- dpkg-deb --contents <var>filename</var>.deb
- dpkg --contents <var>filename</var>.deb
- </example>
- To view the copyright file for a package you could use this command:
- <example>
- dpkg --fsys-tarfile <var>filename</var>.deb | tar xOf - --wildcards \*/copyright | pager
- </example>
- </p>
- </sect>
-
- <sect id="pkg-controlarea">
- <heading>Package control information files</heading>
-
- <p>
- The control information portion of a binary package is a
- collection of files with names known to <prgn>dpkg</prgn>.
- It will treat the contents of these files specially - some
- of them contain information used by <prgn>dpkg</prgn> when
- installing or removing the package; others are scripts which
- the package maintainer wants <prgn>dpkg</prgn> to run.
- </p>
-
- <p>
- It is possible to put other files in the package control
- information file area, but this is not generally a good idea
- (though they will largely be ignored).
- </p>
-
- <p>
- Here is a brief list of the control information files supported
- by <prgn>dpkg</prgn> and a summary of what they're used for.
- </p>
-
- <p>
- <taglist>
- <tag><tt>control</tt>
- <item>
- <p>
- This is the key description file used by
- <prgn>dpkg</prgn>. It specifies the package's name
- and version, gives its description for the user,
- states its relationships with other packages, and so
- forth. See <ref id="sourcecontrolfiles"> and
- <ref id="binarycontrolfiles">.
- </p>
-
- <p>
- It is usually generated automatically from information
- in the source package by the
- <prgn>dpkg-gencontrol</prgn> program, and with
- assistance from <prgn>dpkg-shlibdeps</prgn>.
- See <ref id="pkg-sourcetools">.
- </p>
- </item>
-
- <tag><tt>postinst</tt>, <tt>preinst</tt>, <tt>postrm</tt>,
- <tt>prerm</tt>
- </tag>
- <item>
- <p>
- These are executable files (usually scripts) which
- <prgn>dpkg</prgn> runs during installation, upgrade
- and removal of packages. They allow the package to
- deal with matters which are particular to that package
- or require more complicated processing than that
- provided by <prgn>dpkg</prgn>. Details of when and
- how they are called are in <ref id="maintainerscripts">.
- </p>
-
- <p>
- It is very important to make these scripts idempotent.
- See <ref id="idempotency">.
- </p>
-
- <p>
- 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>
-
- <tag><tt>conffiles</tt>
- </tag>
- <item>
- This file contains a list of configuration files which
- are to be handled automatically by <prgn>dpkg</prgn>
- (see <ref id="pkg-conffiles">). Note that not necessarily
- every configuration file should be listed here.
- </item>
-
- <tag><tt>shlibs</tt>
- </tag>
- <item>
- This file contains a list of the shared libraries
- supplied by the package, with dependency details for
- each. This is used by <prgn>dpkg-shlibdeps</prgn>
- when it determines what dependencies are required in a
- package control file. The <tt>shlibs</tt> file format
- is described on <ref id="shlibs">.
- </item>
- </taglist>
- </p>
-
- <sect id="pkg-controlfile">
- <heading>The main control information file: <tt>control</tt></heading>
-
- <p>
- The most important control information file used by
- <prgn>dpkg</prgn> when it installs a package is
- <tt>control</tt>. It contains all the package's "vital
- statistics".
- </p>
-
- <p>
- The binary package control files of packages built from
- Debian sources are made by a special tool,
- <prgn>dpkg-gencontrol</prgn>, which reads
- <file>debian/control</file> and <file>debian/changelog</file> to
- find the information it needs. See <ref id="pkg-sourcepkg"> for
- more details.
- </p>
-
- <p>
- The fields in binary package control files are listed in
- <ref id="binarycontrolfiles">.
- </p>
-
- <p>
- A description of the syntax of control files and the purpose
- of the fields is available in <ref id="controlfields">.
- </p>
- </sect>
-
- <sect>
- <heading>Time Stamps</heading>
-
- <p>
- See <ref id="timestamps">.
- </p>
- </sect>
- </appendix>
-
- <appendix id="pkg-sourcepkg">
- <heading>Source packages (from old Packaging Manual) </heading>
-
- <p>
- The Debian binary packages in the distribution are generated
- from Debian sources, which are in a special format to assist
- the easy and automatic building of binaries.
- </p>
-
- <sect id="pkg-sourcetools">
- <heading>Tools for processing source packages</heading>
-
- <p>
- Various tools are provided for manipulating source packages;
- they pack and unpack sources and help build of binary
- packages and help manage the distribution of new versions.
- </p>
-
- <p>
- They are introduced and typical uses described here; see
- <manref name="dpkg-source" section="1"> for full
- documentation about their arguments and operation.
- </p>
-
- <p>
- For examples of how to construct a Debian source package,
- and how to use those utilities that are used by Debian
- source packages, please see the <prgn>hello</prgn> example
- package.
- </p>
-
- <sect1 id="pkg-dpkg-source">
- <heading>
- <prgn>dpkg-source</prgn> - packs and unpacks Debian source
- packages
- </heading>
-
- <p>
- This program is frequently used by hand, and is also
- called from package-independent automated building scripts
- such as <prgn>dpkg-buildpackage</prgn>.
- </p>
-
- <p>
- To unpack a package it is typically invoked with
- <example>
- dpkg-source -x <var>.../path/to/filename</var>.dsc
- </example>
- </p>
-
- <p>
- with the <file><var>filename</var>.tar.gz</file> and
- <file><var>filename</var>.diff.gz</file> (if applicable) in
- the same directory. It unpacks into
- <file><var>package</var>-<var>version</var></file>, and if
- applicable
- <file><var>package</var>-<var>version</var>.orig</file>, in
- the current directory.
- </p>
-
- <p>
- To create a packed source archive it is typically invoked:
- <example>
- dpkg-source -b <var>package</var>-<var>version</var>
- </example>
- </p>
-
- <p>
- This will create the <file>.dsc</file>, <file>.tar.gz</file> and
- <file>.diff.gz</file> (if appropriate) in the current
- directory. <prgn>dpkg-source</prgn> does not clean the
- source tree first - this must be done separately if it is
- required.
- </p>
-
- <p>
- See also <ref id="pkg-sourcearchives">.</p>
- </sect1>
-
-
- <sect1 id="pkg-dpkg-buildpackage">
- <heading>
- <prgn>dpkg-buildpackage</prgn> - overall package-building
- control script
- </heading>
-
- <p>
- <prgn>dpkg-buildpackage</prgn> is a script which invokes
- <prgn>dpkg-source</prgn>, the <file>debian/rules</file>
- targets <tt>clean</tt>, <tt>build</tt> and
- <tt>binary</tt>, <prgn>dpkg-genchanges</prgn> and
- <prgn>gpg</prgn> (or <prgn>pgp</prgn>) to build a signed
- source and binary package upload.
- </p>
-
- <p>
- It is usually invoked by hand from the top level of the
- built or unbuilt source directory. It may be invoked with
- no arguments; useful arguments include:
- <taglist compact="compact">
- <tag><tt>-uc</tt>, <tt>-us</tt></tag>
- <item>
- <p>
- Do not sign the <tt>.changes</tt> file or the
- source package <tt>.dsc</tt> file, respectively.</p>
- </item>
- <tag><tt>-p<var>sign-command</var></tt></tag>
- <item>
- <p>
- Invoke <var>sign-command</var> instead of finding
- <tt>gpg</tt> or <tt>pgp</tt> on the <prgn>PATH</prgn>.
- <var>sign-command</var> must behave just like
- <prgn>gpg</prgn> or <tt>pgp</tt>.</p>
- </item>
- <tag><tt>-r<var>root-command</var></tt></tag>
- <item>
- <p>
- When root privilege is required, invoke the command
- <var>root-command</var>. <var>root-command</var>
- should invoke its first argument as a command, from
- the <prgn>PATH</prgn> if necessary, and pass its
- second and subsequent arguments to the command it
- calls. If no <var>root-command</var> is supplied
- then <var>dpkg-buildpackage</var> will take no
- special action to gain root privilege, so that for
- most packages it will have to be invoked as root to
- start with.</p>
- </item>
- <tag><tt>-b</tt>, <tt>-B</tt></tag>
- <item>
- <p>
- Two types of binary-only build and upload - see
- <manref name="dpkg-source" section="1">.
- </p>
- </item>
- </taglist>
- </p>
- </sect1>
-
- <sect1 id="pkg-dpkg-gencontrol">
- <heading>
- <prgn>dpkg-gencontrol</prgn> - generates binary package
- control files
- </heading>
-
- <p>
- This program is usually called from <file>debian/rules</file>
- (see <ref id="pkg-sourcetree">) in the top level of the source
- tree.
- </p>
-
- <p>
- This is usually done just before the files and directories in the
- temporary directory tree where the package is being built have their
- permissions and ownerships set and the package is constructed using
- <prgn>dpkg-deb/</prgn>
- <footnote>
- This is so that the control file which is produced has
- the right permissions
- </footnote>.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> must be called after all the
- files which are to go into the package have been placed in
- the temporary build directory, so that its calculation of
- the installed size of a package is correct.
- </p>
-
- <p>
- It is also necessary for <prgn>dpkg-gencontrol</prgn> to
- be run after <prgn>dpkg-shlibdeps</prgn> so that the
- variable substitutions created by
- <prgn>dpkg-shlibdeps</prgn> in <file>debian/substvars</file>
- are available.
- </p>
-
- <p>
- For a package which generates only one binary package, and
- which builds it in <file>debian/tmp</file> relative to the top
- of the source package, it is usually sufficient to call
- <prgn>dpkg-gencontrol</prgn>.
- </p>
-
- <p>
- Sources which build several binaries will typically need
- something like:
- <example>
- dpkg-gencontrol -Pdebian/tmp-<var>pkg</var> -p<var>package</var>
- </example> The <tt>-P</tt> tells
- <prgn>dpkg-gencontrol</prgn> that the package is being
- built in a non-default directory, and the <tt>-p</tt>
- tells it which package's control file should be generated.
- </p>
-
- <p>
- <prgn>dpkg-gencontrol</prgn> also adds information to the
- list of files in <file>debian/files</file>, for the benefit of
- (for example) a future invocation of
- <prgn>dpkg-genchanges</prgn>.</p>
- </sect1>
-
- <sect1 id="pkg-dpkg-shlibdeps">
- <heading>
- <prgn>dpkg-shlibdeps</prgn> - calculates shared library
- dependencies
- </heading>
-
- <p>
- This program is usually called from <file>debian/rules</file>
- just before <prgn>dpkg-gencontrol</prgn> (see <ref
- id="pkg-sourcetree">), in the top level of the source tree.
- </p>
-
- <p>
- Its arguments are executables and shared libraries
- <footnote>
- <p>
- They may be specified either in the locations in the
- source tree where they are created or in the locations
- in the temporary build tree where they are installed
- prior to binary package creation.
- </p>
- </footnote> for which shared library dependencies should
- be included in the binary package's control file.
- </p>
-
- <p>
- If some of the found shared libraries should only
- warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
- some warrant a <tt>Pre-Depends</tt>, this can be achieved
- by using the <tt>-d<var>dependency-field</var></tt> option
- before those executable(s). (Each <tt>-d</tt> option
- takes effect until the next <tt>-d</tt>.)
- </p>
-
- <p>
- <prgn>dpkg-shlibdeps</prgn> does not directly cause the
- output control file to be modified. Instead by default it
- adds to the <file>debian/substvars</file> file variable
- settings like <tt>shlibs:Depends</tt>. These variable
- settings must be referenced in dependency fields in the
- appropriate per-binary-package sections of the source
- control file.
- </p>
-
- <p>
- For example, a package that generates an essential part
- which requires dependencies, and optional parts that
- which only require a recommendation, would separate those
- two sets of dependencies into two different fields.<footnote>
- At the time of writing, an example for this was the
- <package/xmms/ package, with Depends used for the xmms
- executable, Recommends for the plug-ins and Suggests for
- even more optional features provided by unzip.
- </footnote>
- It can say in its <file>debian/rules</file>:
- <example>
- dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
- -dRecommends <var>optionalpart anotheroptionalpart</var>
- </example>
- and then in its main control file <file>debian/control</file>:
- <example>
- <var>...</var>
- Depends: ${shlibs:Depends}
- Recommends: ${shlibs:Recommends}
- <var>...</var>
- </example>
- </p>
-
- <p>
- Sources which produce several binary packages with
- different shared library dependency requirements can use
- the <tt>-p<var>varnameprefix</var></tt> option to override
- the default <tt>shlibs:</tt> prefix (one invocation of
- <prgn>dpkg-shlibdeps</prgn> per setting of this option).
- They can thus produce several sets of dependency
- variables, each of the form
- <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
- which can be referred to in the appropriate parts of the
- binary package control files.
- </p>
- </sect1>
-
-
- <sect1 id="pkg-dpkg-distaddfile">
- <heading>
- <prgn>dpkg-distaddfile</prgn> - adds a file to
- <file>debian/files</file>
- </heading>
-
- <p>
- Some packages' uploads need to include files other than
- the source and binary package files.
- </p>
-
- <p>
- <prgn>dpkg-distaddfile</prgn> adds a file to the
- <file>debian/files</file> file so that it will be included in
- the <file>.changes</file> file when
- <prgn>dpkg-genchanges</prgn> is run.
- </p>
-
- <p>
- It is usually invoked from the <tt>binary</tt> target of
- <file>debian/rules</file>:
- <example>
- dpkg-distaddfile <var>filename</var> <var>section</var> <var>priority</var>
- </example>
- The <var>filename</var> is relative to the directory where
- <prgn>dpkg-genchanges</prgn> will expect to find it - this
- is usually the directory above the top level of the source
- tree. The <file>debian/rules</file> target should put the
- file there just before or just after calling
- <prgn>dpkg-distaddfile</prgn>.
- </p>
-
- <p>
- The <var>section</var> and <var>priority</var> are passed
- unchanged into the resulting <file>.changes</file> file.
- </p>
- </sect1>
-
-
- <sect1 id="pkg-dpkg-genchanges">
- <heading>
- <prgn>dpkg-genchanges</prgn> - generates a <file>.changes</file>
- upload control file
- </heading>
-
- <p>
- This program is usually called by package-independent
- automatic building scripts such as
- <prgn>dpkg-buildpackage</prgn>, but it may also be called
- by hand.
- </p>
-
- <p>
- It is usually called in the top level of a built source
- tree, and when invoked with no arguments will print out a
- straightforward <file>.changes</file> file based on the
- information in the source package's changelog and control
- file and the binary and source packages which should have
- been built.
- </p>
- </sect1>
-
-
- <sect1 id="pkg-dpkg-parsechangelog">
- <heading>
- <prgn>dpkg-parsechangelog</prgn> - produces parsed
- representation of a changelog
- </heading>
-
- <p>
- This program is used internally by
- <prgn>dpkg-source</prgn> et al. It may also occasionally
- be useful in <file>debian/rules</file> and elsewhere. It
- parses a changelog, <file>debian/changelog</file> by default,
- and prints a control-file format representation of the
- information in it to standard output.
- </p>
- </sect1>
-
- <sect1 id="pkg-dpkg-architecture">
- <heading>
- <prgn>dpkg-architecture</prgn> - information about the build and
- host system
- </heading>
-
- <p>
- This program can be used manually, but is also invoked by
- <tt>dpkg-buildpackage</tt> or <file>debian/rules</file> to set
- environment or make variables which specify the build and host
- architecture for the package building process.
- </p>
- </sect1>
- </sect>
-
- <sect id="pkg-sourcetree">
- <heading>The Debian package source tree</heading>
-
- <p>
- The source archive scheme described later is intended to
- allow a Debian package source tree with some associated
- control information to be reproduced and transported easily.
- The Debian package source tree is a version of the original
- program with certain files added for the benefit of the
- packaging process, and with any other changes required
- made to the rest of the source code and installation
- scripts.
- </p>
-
- <p>
- The extra files created for Debian are in the subdirectory
- <file>debian</file> of the top level of the Debian package
- source tree. They are described below.
- </p>
-
- <sect1 id="pkg-debianrules">
- <heading><file>debian/rules</file> - the main building script</heading>
-
- <p>
- See <ref id="debianrules">.
- </p>
- </sect1>
-
- <sect1 id="pkg-srcsubstvars">
- <heading><file>debian/substvars</file> and variable substitutions</heading>
-
- <p>
- See <ref id="substvars">.
- </p>
-
- </sect1>
-
- <sect1>
- <heading><file>debian/files</file></heading>
-
- <p>
- See <ref id="debianfiles">.
- </p>
- </sect1>
-
- <sect1><heading><file>debian/tmp</file>
- </heading>
-
- <p>
- This is the canonical temporary location for the
- construction of binary packages by the <tt>binary</tt>
- target. The directory <file>tmp</file> serves as the root of
- the file system tree as it is being constructed (for
- example, by using the package's upstream makefiles install
- targets and redirecting the output there), and it also
- contains the <tt>DEBIAN</tt> subdirectory. See <ref
- id="pkg-bincreating">.
- </p>
-
- <p>
- If several binary packages are generated from the same
- source tree it is usual to use several
- <file>debian/tmp<var>something</var></file> directories, for
- example <file>tmp-a</file> or <file>tmp-doc</file>.
- </p>
-
- <p>
- Whatever <file>tmp</file> directories are created and used by
- <tt>binary</tt> must of course be removed by the
- <tt>clean</tt> target.</p></sect1>
- </sect>
-
-
- <sect id="pkg-sourcearchives"><heading>Source packages as archives
- </heading>
-
- <p>
- As it exists on the FTP site, a Debian source package
- consists of three related files. You must have the right
- versions of all three to be able to use them.
- </p>
-
- <p>
- <taglist>
- <tag>Debian source control file - <tt>.dsc</tt></tag>
- <item>
- This file is a control file used by <prgn>dpkg-source</prgn>
- to extract a source package.
- See <ref id="debiansourcecontrolfiles">.
- </item>
-
- <tag>
- Original source archive -
- <file>
- <var>package</var>_<var>upstream-version</var>.orig.tar.gz
- </file>
- </tag>
-
- <item>
- <p>
- This is a compressed (with <tt>gzip -9</tt>)
- <prgn>tar</prgn> file containing the source code from
- the upstream authors of the program.
- </p>
- </item>
-
- <tag>
- Debian package diff -
- <file>
- <var>package</var>_<var>upstream_version-revision</var>.diff.gz
- </file>
- </tag>
- <item>
-
- <p>
- This is a unified context diff (<tt>diff -u</tt>)
- giving the changes which are required to turn the
- original source into the Debian source. These changes
- may only include editing and creating plain files.
- The permissions of files, the targets of symbolic
- links and the characteristics of special files or
- pipes may not be changed and no files may be removed
- or renamed.
- </p>
-
- <p>
- All the directories in the diff must exist, except the
- <file>debian</file> subdirectory of the top of the source
- tree, which will be created by
- <prgn>dpkg-source</prgn> if necessary when unpacking.
- </p>
-
- <p>
- The <prgn>dpkg-source</prgn> program will
- automatically make the <file>debian/rules</file> file
- executable (see below).</p></item>
- </taglist>
- </p>
-
- <p>
- If there is no original source code - for example, if the
- package is specially prepared for Debian or the Debian
- maintainer is the same as the upstream maintainer - the
- format is slightly different: then there is no diff, and the
- tarfile is named
- <file><var>package</var>_<var>version</var>.tar.gz</file>,
- and preferably contains a directory named
- <file><var>package</var>-<var>version</var></file>.
- </p>
- </sect>
-
- <sect>
- <heading>Unpacking a Debian source package without <prgn>dpkg-source</prgn></heading>
-
- <p>
- <tt>dpkg-source -x</tt> is the recommended way to unpack a
- Debian source package. However, if it is not available it
- is possible to unpack a Debian source archive as follows:
- <enumlist compact="compact">
- <item>
- <p>
- Untar the tarfile, which will create a <file>.orig</file>
- directory.</p>
- </item>
- <item>
- <p>Rename the <file>.orig</file> directory to
- <file><var>package</var>-<var>version</var></file>.</p>
- </item>
- <item>
- <p>
- Create the subdirectory <file>debian</file> at the top of
- the source tree.</p>
- </item>
- <item><p>Apply the diff using <tt>patch -p0</tt>.</p>
- </item>
- <item><p>Untar the tarfile again if you want a copy of the original
- source code alongside the Debian version.</p>
- </item>
- </enumlist>
-
- <p>
- It is not possible to generate a valid Debian source archive
- without using <prgn>dpkg-source</prgn>. In particular,
- attempting to use <prgn>diff</prgn> directly to generate the
- <file>.diff.gz</file> file will not work.
- </p>
-
- <sect1>
- <heading>Restrictions on objects in source packages</heading>
-
- <p>
- The source package may not contain any hard links
- <footnote>
- This is not currently detected when building source
- packages, but only when extracting
- them.
- </footnote>
- <footnote>
- Hard links may be permitted at some point in the
- future, but would require a fair amount of
- work.
- </footnote>, device special files, sockets or setuid or
- setgid files.
- <footnote>
- Setgid directories are allowed.
- </footnote>
- </p>
-
- <p>
- The source packaging tools manage the changes between the
- original and Debian source using <prgn>diff</prgn> and
- <prgn>patch</prgn>. Turning the original source tree as
- included in the <file>.orig.tar.gz</file> into the Debian
- package source must not involve any changes which cannot be
- handled by these tools. Problematic changes which cause
- <prgn>dpkg-source</prgn> to halt with an error when
- building the source package are:
- <list compact="compact">
- <item><p>Adding or removing symbolic links, sockets or pipes.</p>
- </item>
- <item><p>Changing the targets of symbolic links.</p>
- </item>
- <item><p>Creating directories, other than <file>debian</file>.</p>
- </item>
- <item><p>Changes to the contents of binary files.</p></item>
- </list> Changes which cause <prgn>dpkg-source</prgn> to
- print a warning but continue anyway are:
- <list compact="compact">
- <item>
- <p>
- Removing files, directories or symlinks.
- <footnote>
- Renaming a file is not treated specially - it is
- seen as the removal of the old file (which
- generates a warning, but is otherwise ignored),
- and the creation of the new one.
- </footnote>
- </p>
- </item>
- <item>
- <p>
- Changed text files which are missing the usual final
- newline (either in the original or the modified
- source tree).
- </p>
- </item>
- </list>
- Changes which are not represented, but which are not detected by
- <prgn>dpkg-source</prgn>, are:
- <list compact="compact">
- <item><p>Changing the permissions of files (other than
- <file>debian/rules</file>) and directories.</p></item>
- </list>
- </p>
-
- <p>
- The <file>debian</file> directory and <file>debian/rules</file>
- are handled specially by <prgn>dpkg-source</prgn> - before
- applying the changes it will create the <file>debian</file>
- directory, and afterwards it will make
- <file>debian/rules</file> world-executable.
- </p>
- </sect1>
- </sect>
- </appendix>
-
- <appendix id="pkg-controlfields">
- <heading>Control files and their fields (from old Packaging Manual)</heading>
-
- <p>
- Many of the tools in the <prgn>dpkg</prgn> suite manipulate
- data in a common format, known as control files. Binary and
- source packages have control data as do the <file>.changes</file>
- files which control the installation of uploaded files, and
- <prgn>dpkg</prgn>'s internal databases are in a similar
- format.
- </p>
-
- <sect>
- <heading>Syntax of control files</heading>
-
- <p>
- See <ref id="controlsyntax">.
- </p>
-
- <p>
- It is important to note that there are several fields which
- are optional as far as <prgn>dpkg</prgn> and the related
- tools are concerned, but which must appear in every Debian
- package, or whose omission may cause problems.
- </p>
- </sect>
-
- <sect>
- <heading>List of fields</heading>
-
- <p>
- See <ref id="controlfieldslist">.
- </p>
-
- <p>
- This section now contains only the fields that didn't belong
- to the Policy manual.
- </p>
-
- <sect1 id="pkg-f-Filename">
- <heading><tt>Filename</tt> and <tt>MSDOS-Filename</tt></heading>
-
- <p>
- These fields in <tt>Packages</tt> files give the
- filename(s) of (the parts of) a package in the
- distribution directories, relative to the root of the
- Debian hierarchy. If the package has been split into
- several parts the parts are all listed in order, separated
- by spaces.
- </p>
- </sect1>
-
- <sect1 id="pkg-f-Size">
- <heading><tt>Size</tt> and <tt>MD5sum</tt></heading>
-
- <p>
- These fields in <file>Packages</file> files give the size (in
- bytes, expressed in decimal) and MD5 checksum of the
- file(s) which make(s) up a binary package in the
- distribution. If the package is split into several parts
- the values for the parts are listed in order, separated by
- spaces.
- </p>
- </sect1>
-
- <sect1 id="pkg-f-Status">
- <heading><tt>Status</tt></heading>
-
- <p>
- This field in <prgn>dpkg</prgn>'s status file records
- whether the user wants a package installed, removed or
- left alone, whether it is broken (requiring
- re-installation) or not and what its current state on the
- system is. Each of these pieces of information is a
- single word.
- </p>
- </sect1>
-
- <sect1 id="pkg-f-Config-Version">
- <heading><tt>Config-Version</tt></heading>
-
- <p>
- If a package is not installed or not configured, this
- field in <prgn>dpkg</prgn>'s status file records the last
- version of the package which was successfully
- configured.
- </p>
- </sect1>
-
- <sect1 id="pkg-f-Conffiles">
- <heading><tt>Conffiles</tt></heading>
-
- <p>
- This field in <prgn>dpkg</prgn>'s status file contains
- information about the automatically-managed configuration
- files held by a package. This field should <em>not</em>
- appear anywhere in a package!
- </p>
- </sect1>
-
- <sect1>
- <heading>Obsolete fields</heading>
-
- <p>
- These are still recognized by <prgn>dpkg</prgn> but should
- not appear anywhere any more.
-
- <taglist compact="compact">
-
- <tag><tt>Revision</tt></tag>
- <tag><tt>Package-Revision</tt></tag>
- <tag><tt>Package_Revision</tt></tag>
- <item>
- The Debian revision part of the package version was
- at one point in a separate control field. This
- field went through several names.
- </item>
-
- <tag><tt>Recommended</tt></tag>
- <item>Old name for <tt>Recommends</tt>.</item>
-
- <tag><tt>Optional</tt></tag>
- <item>Old name for <tt>Suggests</tt>.</item>
-
- <tag><tt>Class</tt></tag>
- <item>Old name for <tt>Priority</tt>.</item>
-
- </taglist>
- </p>
- </sect1>
- </sect>
-
- </appendix>
-
- <appendix id="pkg-conffiles">
- <heading>Configuration file handling (from old Packaging Manual)</heading>
-
- <p>
- <prgn>dpkg</prgn> can do a certain amount of automatic
- handling of package configuration files.
- </p>
-
- <p>
- Whether this mechanism is appropriate depends on a number of
- factors, but basically there are two approaches to any
- particular configuration file.
- </p>
-
- <p>
- The easy method is to ship a best-effort configuration in the
- package, and use <prgn>dpkg</prgn>'s conffile mechanism to
- handle updates. If the user is unlikely to want to edit the
- file, but you need them to be able to without losing their
- changes, and a new package with a changed version of the file
- is only released infrequently, this is a good approach.
- </p>
-
- <p>
- The hard method is to build the configuration file from
- scratch in the <prgn>postinst</prgn> script, and to take the
- responsibility for fixing any mistakes made in earlier
- versions of the package automatically. This will be
- appropriate if the file is likely to need to be different on
- each system.
- </p>
-
- <sect><heading>Automatic handling of configuration files by
- <prgn>dpkg</prgn>
- </heading>
-
- <p>
- A package may contain a control information file called
- <tt>conffiles</tt>. This file should be a list of filenames
- of configuration files needing automatic handling, separated
- by newlines. The filenames should be absolute pathnames,
- and the files referred to should actually exist in the
- package.
- </p>
-
- <p>
- When a package is upgraded <prgn>dpkg</prgn> will process
- the configuration files during the configuration stage,
- shortly before it runs the package's <prgn>postinst</prgn>
- script,
- </p>
-
- <p>
- For each file it checks to see whether the version of the
- file included in the package is the same as the one that was
- included in the last version of the package (the one that is
- being upgraded from); it also compares the version currently
- installed on the system with the one shipped with the last
- version.
- </p>
-
- <p>
- If neither the user nor the package maintainer has changed
- the file, it is left alone. If one or the other has changed
- their version, then the changed version is preferred - i.e.,
- if the user edits their file, but the package maintainer
- doesn't ship a different version, the user's changes will
- stay, silently, but if the maintainer ships a new version
- and the user hasn't edited it the new version will be
- installed (with an informative message). If both have
- changed their version the user is prompted about the problem
- and must resolve the differences themselves.
- </p>
-
- <p>
- The comparisons are done by calculating the MD5 message
- digests of the files, and storing the MD5 of the file as it
- was included in the most recent version of the package.
- </p>
-
- <p>
- When a package is installed for the first time
- <prgn>dpkg</prgn> will install the file that comes with it,
- unless that would mean overwriting a file already on the
- file system.
- </p>
-
- <p>
- However, note that <prgn>dpkg</prgn> will <em>not</em>
- replace a conffile that was removed by the user (or by a
- script). This is necessary because with some programs a
- missing file produces an effect hard or impossible to
- achieve in another way, so that a missing file needs to be
- kept that way if the user did it.
- </p>
-
- <p>
- Note that a package should <em>not</em> modify a
- <prgn>dpkg</prgn>-handled conffile in its maintainer
- scripts. Doing this will lead to <prgn>dpkg</prgn> giving
- the user confusing and possibly dangerous options for
- conffile update when the package is upgraded.</p>
- </sect>
-
- <sect><heading>Fully-featured maintainer script configuration
- handling
- </heading>
-
- <p>
- For files which contain site-specific information such as
- the hostname and networking details and so forth, it is
- better to create the file in the package's
- <prgn>postinst</prgn> script.
- </p>
-
- <p>
- This will typically involve examining the state of the rest
- of the system to determine values and other information, and
- may involve prompting the user for some information which
- can't be obtained some other way.
- </p>
-
- <p>
- When using this method there are a couple of important
- issues which should be considered:
- </p>
-
- <p>
- If you discover a bug in the program which generates the
- configuration file, or if the format of the file changes
- from one version to the next, you will have to arrange for
- the postinst script to do something sensible - usually this
- will mean editing the installed configuration file to remove
- the problem or change the syntax. You will have to do this
- very carefully, since the user may have changed the file,
- perhaps to fix the very problem that your script is trying
- to deal with - you will have to detect these situations and
- deal with them correctly.
- </p>
-
- <p>
- If you do go down this route it's probably a good idea to
- make the program that generates the configuration file(s) a
- separate program in <file>/usr/sbin</file>, by convention called
- <file><var>package</var>config</file> and then run that if
- appropriate from the post-installation script. The
- <tt><var>package</var>config</tt> program should not
- unquestioningly overwrite an existing configuration - if its
- mode of operation is geared towards setting up a package for
- the first time (rather than any arbitrary reconfiguration
- later) you should have it check whether the configuration
- already exists, and require a <tt>--force</tt> flag to
- overwrite it.</p></sect>
- </appendix>
-
- <appendix id="pkg-alternatives"><heading>Alternative versions of
- an interface - <prgn>update-alternatives</prgn> (from old
- Packaging Manual)
- </heading>
-
- <p>
- When several packages all provide different versions of the
- same program or file it is useful to have the system select a
- default, but to allow the system administrator to change it
- and have their decisions respected.
- </p>
-
- <p>
- For example, there are several versions of the <prgn>vi</prgn>
- editor, and there is no reason to prevent all of them from
- being installed at once, each under their own name
- (<prgn>nvi</prgn>, <prgn>vim</prgn> or whatever).
- Nevertheless it is desirable to have the name <tt>vi</tt>
- refer to something, at least by default.
- </p>
-
- <p>
- If all the packages involved cooperate, this can be done with
- <prgn>update-alternatives</prgn>.
- </p>
-
- <p>
- Each package provides its own version under its own name, and
- calls <prgn>update-alternatives</prgn> in its postinst to
- register its version (and again in its prerm to deregister
- it).
- </p>
-
- <p>
- See the man page <manref name="update-alternatives"
- section="8"> for details.
- </p>
-
- <p>
- If <prgn>update-alternatives</prgn> does not seem appropriate
- you may wish to consider using diversions instead.</p>
- </appendix>
-
- <appendix id="pkg-diversions"><heading>Diversions - overriding a
- package's version of a file (from old Packaging Manual)
- </heading>
-
- <p>
- It is possible to have <prgn>dpkg</prgn> not overwrite a file
- when it reinstalls the package it belongs to, and to have it
- put the file from the package somewhere else instead.
- </p>
-
- <p>
- This can be used locally to override a package's version of a
- file, or by one package to override another's version (or
- provide a wrapper for it).
- </p>
-
- <p>
- Before deciding to use a diversion, read <ref
- id="pkg-alternatives"> to see if you really want a diversion
- rather than several alternative versions of a program.
- </p>
-
- <p>
- There is a diversion list, which is read by <prgn>dpkg</prgn>,
- and updated by a special program <prgn>dpkg-divert</prgn>.
- Please see <manref name="dpkg-divert" section="8"> for full
- details of its operation.
- </p>
-
- <p>
- When a package wishes to divert a file from another, it should
- call <prgn>dpkg-divert</prgn> in its preinst to add the
- diversion and rename the existing file. For example,
- supposing that a <prgn>smailwrapper</prgn> package wishes to
- install a wrapper around <file>/usr/sbin/smail</file>:
- <example>
- dpkg-divert --package smailwrapper --add --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- </example> The <tt>--package smailwrapper</tt> ensures that
- <prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
- can bypass the diversion and get installed as the true version.
- It's safe to add the diversion unconditionally on upgrades since
- it will be left unchanged if it already exists, but
- <prgn>dpkg-divert</prgn> will display a message. To suppress that
- message, make the command conditional on the version from which
- the package is being upgraded:
- <example>
- if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
- dpkg-divert --package smailwrapper --add --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
- </example> where <tt>1.0-2</tt> is the version at which the
- diversion was first added to the package. Running the command
- during abort-upgrade is pointless but harmless.
- </p>
-
- <p>
- The postrm has to do the reverse:
- <example>
- if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
- dpkg-divert --package smailwrapper --remove --rename \
- --divert /usr/sbin/smail.real /usr/sbin/smail
- fi
- </example> If the diversion was added at a particular version, the
- postrm should also handle the failure case of upgrading from an
- older version (unless the older version is so old that direct
- upgrades are no longer supported):
- <example>
- if [ abort-upgrade = "$1" ] && dpkg --compare-versions "$2" lt 1.0-2; then
- 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
- 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
- postrm of the old package is run after unpacking so the removal of
- the diversion will fail.
- </p>
-
- <p>
- Do not attempt to divert a file which is vitally important for
- the system's operation - when using <prgn>dpkg-divert</prgn>
- 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>
- </appendix>
-
</book>
</debiandoc>
<!-- Local variables: -->
--
1.5.6.5
signature.asc
Description: Digital signature
--- End Message ---
