Package: debian-policy Version: 3.8.0.1 Severity: wishlist Owner: BrianLRyans@gmail.com 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: BrianLRyans@gmail.com ..: 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 <BrianLRyans@gmail.com> 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
Attachment:
signature.asc
Description: Digital signature