Your message dated Fri, 11 Aug 2017 08:20:06 -0700 with message-id <87fucyxhax.fsf@iris.silentflame.com> and subject line Fixed in an older release has caused the Debian Bug report #598645, regarding cleanup: move text out of appendices to be marked as done. This means that you claim that the problem has been dealt with. If this is not the case it is now your responsibility to reopen the Bug report if necessary, and/or fix the problem forthwith. (NB: If you are a system administrator and have no idea what this message is talking about, this may indicate a serious mail system misconfiguration somewhere. Please contact owner@bugs.debian.org immediately.) -- 598645: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=598645 Debian Bug Tracking System Contact owner@bugs.debian.org with problems
--- Begin Message ---
- To: Debian Bug Tracking System <submit@bugs.debian.org>
- Subject: cleanup: dike non-policy
- From: Brian Ryans <brian.l.ryans@gmail.com>
- Date: Thu, 30 Sep 2010 13:07:50 -0500
- Message-id: <20100930180750.GA17046@esterhazy>
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. -- blrFrom 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.5Attachment: signature.asc
Description: Digital signature
--- End Message ---
--- Begin Message ---
- To: 598645-done@bugs.debian.org
- Subject: Fixed in an older release
- From: Sean Whitton <spwhitton@spwhitton.name>
- Date: Fri, 11 Aug 2017 08:20:06 -0700
- Message-id: <87fucyxhax.fsf@iris.silentflame.com>
Version: 3.9.5.0 Fixed in an older release -- thanks. -- Sean WhittonAttachment: signature.asc
Description: PGP signature
--- End Message ---