--- /dev/null
+This is a collection of Frequently Asked Questions (and answers!)
+about the Linux FSSTND project and document. It was composed by Ian
+McCloghrie <ian@ucsd.edu>. Questions, corrections, clarifications,
+etc. about this FAQ should be directed to him.
+
+Sun Oct 9 22:55:25 PDT 1994
+
+Note: This FAQ is wrtten by me, personally, as an attempt to help out
+the FSSTND project. This FAQ reflects my personal views and, while I
+am a member of the FSSTND project, should not be construed as
+necessarily reflecting the views of everyone on the project.
+
+
+========= General Questions ==========
+
+
+Q) Who wrote the FSSTND, and where can I get in contact with them?
+
+A) The FSSTND is a consensus effort of many Linux activists; the main
+arm of their discussion takes place on the FSSTND mailing list.
+The principal co-ordinator is Daniel Quinlan <Daniel.Quinaln@linux.org>
+Any questions you may have regarding the standard should be directed
+to him or to any of the contributors listed in the FSSTND document or
+this FAQ.
+
+The FSSTND discussion mailing list is "linux-fsstnd@ucsd.edu"; if you
+wish to participate in future expansion of the standard, you can
+subscribe to this list by sending mail to "listserv@ucsd.edu", with the
+body of "add linux-fsstnd".
+
+
+Q) What's the current status of the FSSTND?
+
+A) As of this writing, (Oct 9, 1994), Linux FSSTND 1.2 has been
+released as an interim draft, and is available for anonymous FTP
+from tsx-11.mit.edu in /pub/linux/docs/linux-standards/fsstnd.
+PostScript, dvi, and ascii text versions are available.
+
+Due to the fact that a significant number of Linux developers are
+making use of standard drafts that came after the first version (back
+in February), the decision was made to issue an interim version in
+order to ensure that everyone is working from the same foundation.
+
+
+Q) Why 'FSSTND' anyway? That's a horrible abbreviation.
+
+A) Yes, 'FSSTND' is a horrible abbreviation of "Filesystem Standard".
+Unfortunately, that's the name that was given to the initial channel
+of the niksula.hut.fi mailing list, and it's kinda stuck. Changing it
+would create more confusion than it's really worth.
+
+
+Q) I've got a great new idea for how to organize the filesystem;
+why don't we...
+
+A) If you really think you've got something revolutionary, by all
+means, we'd love to see it. In practice, a lot of "great new" ideas
+have been raised (and dropped, for one reason or another) on the
+mailing list already. As such, we suggest you send mail to one of the
+contributors privately first, and get his/her reaction to it, before
+making a general proposal.
+
+
+Q) Why did you do it *THIS* way? Why not do what Sun did and...
+
+A) The FSSTND draws ideas from POSIX, 4.4BSD, SVR4, SunOS 4, MCC,
+Slackware, SLS, (in no particular order) and many other systems. We
+have not followed any one operating system layout in entirety.
+Instead we have tried to take the best of each filesystem layout and
+combine them into a homogenous whole, well suited to the needs of
+Linux users everywhere. In some cases, we may not have been
+completely successful; however, we think we've done a fairly decent
+job.
+
+
+Q) You *&^% idiots, don't you know that foo goes in /bin, not in /usr/bin?
+
+A) Think about it. Does foo *really* need to go on the root
+partition? Constructive suggestions are welcomed. Flames are not.
+
+We have tried to decide upon a set of binaries that is an effective
+compromised between functionality and space restrictions. The root
+partition needs to contain enough functionality to boot the system,
+mount the /usr partition, and to enable a systems administrator to
+repair things on /usr if something goes wrong. If you have a local
+boot-time system that absolutely requires other binaries to be used
+in the mounting of /usr, the suggested solution is to move them to
+/bin and to make a symbolic link from /usr/bin/foo to /bin/foo.
+
+
+Q) Does the fact that Daniel Quinlan now works for Yggdrasil affect
+his coordination of the FSSTND?
+
+A) In short, no. In a bit more length, no, except for the fact that
+he's now even more intimately familiar with the problems involved
+in creating a distribution. (well, and that he's earning money and
+can afford to buy food to eat, so has energy to spare worrying about
+things like which directory cpio belongs in)
+
+FSSTND is not distribution-specific, the fact that the coordinator is
+employed by one distribution-provider does not affect this fact. Yggdrasil
+does not have any special connection to FSSTND, and vice versa.
+To simplify things, Dan would appreciate it if you could direct FSSTND-
+related email to <Daniel.Quinlan@linux.org>.
+
+
+========== Specific Questions ==========
+
+
+Q) The distinction between the root partition and /usr is that the
+root is used for files that are 'essential'. What constitutes
+'essential'?
+
+A) essential to clean, create, prepare, check, find and mount other
+filesystems (possibly on remote machines). There are other definitions,
+but this is a general definition that most people will at least
+incorporate into their own.
+
+
+Q) I like to have a small root partition (possibly with multiple
+copies, so I can get the system back up when one of them crashes),
+and I like to stuff everything else into one big partition (especially
+since I only have one free). So, can /var be a symlink to /usr?
+
+A) Making the /var hierarchy a part of a /usr filesystem is
+preferable to making /var a part of the root filesystem when /var
+cannot be made a separate partition.
+
+This is preferable because it is easier to separate /var and /usr
+at some point in the future, if you buy a second disk. The usual way
+of doing this to make /var a symblink link to /usr/var.
+
+
+Q) Why is networking spread out across the filesystem in 4 separate
+directories instead of all being nicely put in /usr/inet?
+
+A) It is the opinion of the FSSTND project (and, in fact, of much of
+the UNIX community in general) that networking is not an "optional
+package" in the traditional sense, but rather an integrated part oF
+the operating system. Binaries such as telnet, ftp, and ping have
+more similiarity to standard unix utilities such as grep, sed, and vi
+than to applications like emacs or WordStar. As such, they are
+spread across /bin, /sbin, /usr/bin, and /usr/sbin, depending upon
+their use.
+
+
+Q) I'm running a HUGE network with 10 different platforms and 20
+different OS's. I *need* to share things. Why isn't there a
+/usr/share?
+
+A) At the moment, Linux is only really available for the
+PC-architecture 80386 machines. (although this may change soon with
+Amiga systems). There is no single existing "cross-platform" standard
+for /usr/share; those that do exist have usually been come up with by
+a single vendor wanting to share certain files between their OS
+running on multiple hardware platforms. There are many problems
+involved in the sharing of files, maybe obvious sharable files that
+are, upon closer examination, not sharable at all. (For example,
+/usr/man could be thought completely sharable, yet some pages (such as
+fsck.1) are completely different from any other UNIX-like operating
+system).
+
+/usr/share would be nice, yes, and we plan to include something like
+this in a future version of the FSSTND. However, until such a time
+as an implementation can actually be tested, no specifications will be
+released. Anything in /usr/share will be "pointed to" by the use of
+symlinks from other areas in the filesystem, such as /usr/man,
+/usr/lib/<something>, etc. Applications should use these locations
+when they reference files, not the /usr/share location, as this may
+change. Things like OSI have shown the problems with standards
+specified without a real clue as to how they'd be implemented.
+
+
+Q) Why are there so many/so few symbolic links in the filesytem?
+Couldn't we make it easier to understand/more orthogonal by
+removing/adding some links?
+
+A) In general, we've tried to minimize the number of symbolic links
+present in the FSSTND. The symlinks that are present in the document
+are the ones we considered essential to maintaining a properly
+orthogonal, and yet still somewhat compatible, filesystem layout.
+/lib/cpp and /usr/lib/sendmail are symbolic links kept for
+compatiblity reasons.
+
+
+Q) What about statically linked binaries? Shouldn't we have a
+statically linked copy of mount, unmount, sh, cp, mv, vi, emacs, gcc,
+X11R5, and WABI in /sbin?
+
+A) Statically linked binaries are a local issue. Most users, those
+with home systems with small amounts of memory and disk and a single
+user on console, do not have any need for any statically linked
+binaries (with the possible exception of ln, sync, and/or ldconfig, to
+fix shared library problems). Some larger sites, with more disk to
+spare, may wish to install backup, statically-linked versions of some
+applications. If you have the need and space to do this, go right
+ahead, we're not stopping you. But we don't require any, because
+(we feel) that most people don't need them. Dynamically linked
+versions should still be available, for regular usage, however.
+
+
+Q) Why does X11 get its own directory tree when there aren't any
+other such "packages" in the FSSTND? Why not spread it out over
+/usr/bin/X11, /usr/lib/X11, etc.
+
+A) X11 is just about the largest 'package' in common use on Linux
+systems. It resides in /usr/X386 as this is the directory name choice
+of the XFree86 developers, to protect against namespace conflicts with
+other X11 packages on any of the dozen or so PC-unix platforms they
+support. The symbolic links in /usr/bin/X11, /usr/lib/X11 and
+/usr/include/X11 are for user's convenience, these are the closest
+things that exist to "standard" locations for the X11 files.
+
+
+Q) Why isn't there a package format laid out in the FSSTND?
+
+A) Many proposals have been discussed for package layouts on the
+fsstnd mailing list. As yet, no consensus has been reached about
+which (if any) of these proposals is best. Work continues, and there
+will probably be mention of 'packages' in version 1.1.
+
+
+Q) What about /usr/local/bin/X11? Should I use this for local X11
+programs? Or is /usr/local/X11/bin better?
+
+A) The standard doesn't specify; we feel that the contents of /usr/local
+are exactly that, local, and so we try to specify as little as
+possible about it. Put them wherever you want. Personally, I use
+/usr/local/bin/X11. However, since xmkmf doesn't seem to like placing
+files into anywhere other than where the existing X files are
+(ie, /usr/X386/*), my libs for local apps usually end up being in
+/usr/X386. Ugly, yes, but not worth (to me) the effort of trying to
+move them. Your mileage may vary.
+
+
+Q) Why doesn't the standard specify the system-level users/groups and
+proper ownerships/permissions/setuid bits for everything?
+
+A) We feel that this is, primarily, a local issue. Many sites
+have their own local user-id/group-id setup, and linux boxes will
+have to be integrated with those. What's more, there is very little
+gain from standardizing these across all linux machines, as it
+typically is not essential to allow binary distributions.
+
+
+Q) Why not just symlink /bin to /usr/bin the way Sun, SVR4, and a few
+others do?
+
+A) This has several technical problems, aside from the fact that many
+consider it ugly. First, it requires placing all the utilites necessary
+to mount /usr into /sbin, and either making copies of them in /usr/bin
+or having every user put /sbin into their $PATH. Second, if /lib is
+symlinked to /usr/lib in the same way, it requires statically linking
+all the binaries in /sbin. This results in /sbin taking up more space
+on the root partition, for a great reduction in functionality, thus
+increasing the number of cases in which one has to go dig out a
+boot/root floppy instead of just booting the hard disk in single-user
+mode.
+
--- /dev/null
+Document: debian-policy
+Title: Debian Policy Manual
+Author: Ian Jackson and Christian Schwarz
+Abstract: This manual describes the policy requirements for the Debian
+ GNU/Linux distribution. This includes the structure and contents of
+ the Debian archive, several design issues of the operating system, as
+ well as technical requirements that each package must satisfy to be
+ included in the distribution.
+Section: Apps/Programming
+
+Format: debiandoc-sgml
+Files: /usr/doc/debian-policy/policy.sgml.gz
+
+Format: text
+Files: /usr/doc/debian-policy/policy.text.gz
+
+Format: HTML
+Index: /usr/doc/debian-policy/policy.html/index.html
+Files: /usr/doc/debian-policy/policy.html/*.html
--- /dev/null
+debian-policy (2.4.1.4) unstable; urgency=low
+
+ * New Maintainer <debian-policy@lists.debian.org>
+
+ -- Philip Hands <phil@hands.com> Sat, 5 Sep 1998 02:41:35 +0100
+
+debian-policy (2.4.1.3) unstable; urgency=low
+
+ * New maintainer (with changes from Adam P. Harris' proposed NMU)
+ * policy.sgml: some awkward phrasings fixed (closes Bug#22006)
+ * policy.sgml: s/depreciated/deprecated (closes Bug#21831)
+ * debian/control: added conflict doc-base (<< 0.6), which I still am not
+ sure why we need this but hey (closes Bug#21554)
+ * policy.sgml: use new <url> tag where appropriate
+ * policy.sgml, debian/control: always dynamically self reference the
+ current version of policy, that is, do not hard code policy revision
+ or date anywhere
+ * debian/rules: use dpkg-gencontrol -isp
+ * bugs fixed in some unknown previous version (closes Bug#23177)
+
+ -- Philip Hands <phil@hands.com> Tue, 11 Aug 1998 09:54:17 +0100
+
+debian-policy (2.4.1.2) frozen unstable; urgency=low
+
+ * non-maintainer release
+ * rebuild package to fix truncated Chapter 3 (Bug#23408, not marked as
+ important but should be, since a gaping hole in policy is very
+ annoying.)
+ * bumped version of policy, within the document, to this version number,
+ but not the date, indicating nothing really changed since then
+ * no content changes
+ * debian/rules: clean is a little cleaner
+
+ -- Adam P. Harris <aph@debian.org> Tue, 16 Jun 1998 03:15:22 -0400
+
+debian-policy (2.4.1.1) frozen unstable; urgency=low
+
+ * Orphaned package
+
+ -- Christian Schwarz <schwarz@debian.org> Thu, 14 May 1998 21:54:50 +0200
+
+debian-policy (2.4.1.0) frozen unstable; urgency=low
+
+ * Changes to the Debian Policy Manual:
+
+ - Updated section 3.1.2 Site-specific programs
+ and section 3.8 Keyboard configuration:
+ + improved wording (fixes:bug#20129)
+
+ - Updated section 2.1.7 Subsections:
+ + fixed typos (fixes:bug#18145)
+
+ - Updated section 3.3.5 Symbolic links:
+ + symbolic links within a toplevel directory should be relative,
+ symbolic links between toplevel directories should be absolute
+ (cf., Policy Weekly Issue#6, topic 2)
+
+ - Updated section 3.4 System run levels:
+ + Intro: mention /etc/rcS.d (links to boot time scripts)
+ + Notes: include rationale why /etc/init.d scripts have to be tagged
+ as conffiles (fixes:bug#16199)
+ + Example: changed example init.d script to handle force-reload
+ and restart options and to comply with the console message
+ standard (fixes:bug#19216)
+
+ - Updated section 4.8 Emacs lisp programs:
+ + Replaced old section about lisp programs with a reference to
+ the file debian-emacs-policy.gz, installed by the emacsen-common
+ package.
+
+ - Updated section 4.9 Games:
+ + manpages for games should be installed in /usr/man/man6
+ (cf., Policy Weekly Issue#6, topic 3)
+
+ - Removed one example reference to the current standards version
+ - Include manual's date as plain text in the .sgml source so that
+ a recompiled manual uses the same release date
+
+ * Changes to the authoritative list of virtual package names:
+ - Removed obsolete virtual package `emacs'
+
+ * New version numbering scheme:
+
+ - The version numbers are independent of dpkg now, but all policy
+ manuals (the Debian Policy Manual, the Debian Packaging Manual, and
+ the Debian Developer's Reference) share the same version numbering
+ scheme.
+
+ - The first three digits of the version number specify the
+ `Standards-Version.' This number is incremented with each policy
+ change. The fourth digit represents the `patch-level,' which may
+ differ between the manuals.
+
+ If only the patch-level digit is incremented, no changes in policy
+ have been made, except bug fixes and clarifications. Packages only
+ have to specify the first three digits of the version number in the
+ `Standards-Version' field of their source packages.
+
+ * Packaging changes:
+
+ - Uploaded to frozen and unstable. This is a documentation-only
+ package and the changes to the manual are relevant for hamm.
+
+ - Fixed FSF's address in copyright file (detected by Lintian)
+
+ -- Christian Schwarz <schwarz@debian.org> Tue, 14 Apr 1998 10:08:09 +0200
+
+debian-policy (2.4.0.0) unstable; urgency=low
+
+ * Changes to the Debian Policy Manual:
+
+ - Updated section 3.3.4 Scripts:
+ + /bin/sh may be any POSIX compatible shell
+ + scripts including bashisms have to specify /bin/bash as
+ interpreter
+ + scripts which create files in world-writable directories
+ (e.g., in /tmp) should use tempfile or mktemp for creating
+ the directory
+
+ - Updated section 3.3.5 Symbolic Links:
+ + symbolic links referencing compressed files must have the same
+ file extension as the referenced file
+
+ - Updated section 3.3.6 Device files:
+ + /dev/tty* serial devices should be used instead of /dev/cu*
+
+ - Updated section 3.4.2 Writing the scripts [in /etc/init.d]:
+ + all /etc/init.d scripts have to provide the following options:
+ start, stop, restart, force-reload
+ + the reload option is optional and must never stop and restart
+ the service
+
+ - Updated section 3.5 Cron jobs:
+ + cron jobs that need to be executed more often than daily should
+ be installed into /etc/cron.d
+
+ - Updated section 3.7 Menus:
+ + removed section about how to register HTML docs to `menu'
+ (the corresponding section in 4.4, Web servers and applications,
+ has been removed in policy 2.2.0.0 already, so this one was
+ obsolete)
+
+ - New section 3.8 Keyboard configuration:
+ + details about how the backspace and delete keys should be
+ handled
+
+ - New section 3.9 Environment variables:
+ + no program must depend on environment variables to get a
+ reasonable default configuration
+
+ - New section 4.6 News system configuration:
+ + /etc/news/organization and /etc/news/server should be supported
+ by all news servers and clients
+
+ - Updated section 4.7 Programs for the X Windows system:
+ + programs requiring a non-free Motif library should be provided
+ as foo-smotif and foo-dmotif package
+ + if lesstif works reliably for such program, it should be linked
+ against lesstif and not against a non-free Motif library
+
+ - Updated section 4.9 Games:
+ + games for X Windows have to be installed in /usr/games, just as
+ non-X games
+
+ - Lots of typos fixed (thanks to Ray Dassen for the patch!)
+
+ * Changes to the authoritative list of virtual package names:
+ - added `libc-dev' and `emacsen'
+
+ * Merged `/usr/doc/debian-policy/changelog-policy.gz' into this
+ changelog file
+
+ * Included `Policy checklist for upgrading your packages' from the
+ Policy Home Page as /usr/doc/debian-policy/upgrading-checklist.text.gz
+
+ * Added support for doc-base to register the Policy Manual to the
+ online documentation systems dwww and dhelp (fixes:#15710)
+
+ * Upgraded to standards version 2.4.0.0 (no changes)
+
+ -- Christian Schwarz <schwarz@debian.org> Fri, 30 Jan 1998 21:58:25 +0100
+
+debian-policy (2.3.0.1) unstable; urgency=low
+
+ * Changes in the Debian Policy Manual:
+ - X library package is now called xlib6g
+ * Changes in the authoritative list of virtual package names:
+ - Added emacs, c-compiler, fortran77-compiler, lambdamoo-core,
+ lambdamoo-server
+ * Conflict with old dpkg-dev version that included policy manual
+ (fixes #13790)
+ * Removed `tentative-opt-draft' from package since people considered
+ the draft official policy (which is not the case)
+ * Don't use debstd anymore
+
+ -- Christian Schwarz <schwarz@debian.org> Tue, 21 Oct 1997 23:03:52 +0200
+
+debian-policy (2.3.0.0) unstable; urgency=low
+
+ * Changes in the Debian Policy Manual:
+ - reworked chapter `The Debian Archive' to cover new
+ contrib/non-free policy
+ - call "contrib" and "non-free" a `section' (not `distribution')
+ - refer to license files (GPL, LGPL, etc.) as uncompressed files
+ - changed `/etc/news/server' into `/etc/nntpserver' in example of
+ maintainer scripts (fixes #11517)
+ - new section about `Daemons'
+ - updated section about `Configuration files'
+ - MUAs and MTAs have to use liblockfile
+ - fixed typos and grammatical errors
+ * Changes in the authoritative list of virtual package names:
+ - renamed tcl/tk virtual package names to `tclsh' and `wish'
+ * Paper about libc6 migration:
+ - fixed typos (fixes #11641), thanks to James Troup for the patch!
+ * SGML source code included in package
+ * don't use `2-up' style for PostScript version (fixes #11095)
+
+ -- Christian Schwarz <schwarz@debian.org> Mon, 2 Sep 1997 00:54:31 +0200
+
+debian-policy (2.2.0.0) unstable; urgency=low
+
+ * Changes in the Debian Policy Manual:
+ - completely reworked structure
+ - moved sections about new maintainers, upload procedure, interim
+ releases, and mailing lists into the Developers Reference Manual
+ - moved a few (small) sections into the Debian Packaging Manual
+ - removed all those ugly footnotes
+ - new example for "reload" in section about console messages
+ - mention Artistic License (fixes #9793)
+ - don't mention dpkg's version number in Policy Manual
+ - rewrote abstract and section introductions
+ - mention "orphaned packages"
+ - maintainer is responsible for a package license to comply with the
+ distributions' policy
+ - putting a package into base section requires discussion on debian-devel
+ - rewrote sections about "pre-depends", "essential" and, "base" packages
+ - added note that non-us' maintainers have to live outside the US
+ - added crypto-hook statement (fixes #7257)
+ - added section about arch spec strings
+ - rewrote section about "Site specific programs" (/usr/local)
+ - included Ian's suggestions for user IDs
+ - added section about "menus"
+ - removed section about "web menus" since this will be superseded with
+ the new documentation policy soon
+ - incorporated "Debian Free Software Guidelines" (fixes #9024)
+ - removed note that linking with -g produces large a.out binary (fixes
+ #11008)
+ - added section about editors and pagers
+ - added note about Package priorities and dependencies
+ - added section about cron jobs (fixes #8814)
+ - added section about device files
+ - don't install shared libraries as executable (fixes #7129)
+ - app-defaults files may not be conffiles (cf. #2717)
+ - lots of minor changes not worth mentioning here (typos, formulations,
+ etc.)
+ * Changes in the authoritative list of virtual package names
+ - Removed obsolete virtual packages: xR6shlib, xlibraries,
+ compress, emacs, sgmls, inews, gs_x, gs_svga, gs_both, xpmR6
+ - Added new section about obsolete names
+ * Added Helmut Geyer's paper about libc5-libc6 migration
+ * Fixed package's description
+
+ -- Christian Schwarz <schwarz@debian.org> Sun, 13 Jul 1997 13:25:51 +0200
+
+debian-policy (2.1.3.3) frozen unstable; urgency=low
+
+ * Mention Artistic License in section 2.5 (bug #9755)
+
+ -- Christian Schwarz <schwarz@debian.org> Wed, 14 May 1997 16:53:15 +0200
+
+debian-policy (2.1.3.2) frozen unstable; urgency=low
+
+ * Fixed an email address, an URL, and several typos in chapter 6 (#9358)
+ * Added new virtual package "wordlist" to list (requested by Joey Hess)
+ * Changed wording in section about "non-free" packages as suggested
+ by Kai Henningsen (#7076)
+
+ -- Christian Schwarz <schwarz@debian.org> Mon, 5 May 1997 20:05:39 +0200
+
+debian-policy (2.1.3.1) frozen unstable; urgency=low
+
+ * Fixed bug in chapter 7: `-ur' should read `-us' (#8874)
+ * Fixed bug in chapter 7: `-rwhatever' also needed for rebuild (#8874)
+ * Create a PS and HTML version of the Policy Manual and upload it
+ "byhand".
+ * Install virtual-package-names-list.text in /usr/doc/debian-policy
+ and upload it "byhand" too.
+
+ -- Christian Schwarz <schwarz@debian.org> Tue, 29 Apr 1997 18:02:14 +0200
+
+debian-policy (2.1.3.0) unstable; urgency=low
+
+ * Initial Release.
+ * New Policy Manager: Christian Schwarz <schwarz@debian.org>
+ * Added section 2.4 about the "non-us" distribution.
+ * Added section 3.1.1 about the "Package" field in the control file.
+ * Added section 3.2.1 about "Binaries": two programs with different
+ functionality must not have the same name.
+ * Changed headline of section 3.2.6 into "Debian changelog and upstream
+ changelog" as suggested by Santiago Vila Doncel <sanvila@unex.es>.
+ * Added log-rotating example to section 3.2.9 that tests with `-sf',
+ as suggested by Boris D. Beletsky <borik@isracom.co.il>.
+ * Added section 3.13: "Webstandard 3.0" by Christoph Lameter.
+ * Added section 3.14: "Standard for Console Messages" by Christian Schwarz.
+ * Split section 4.1 into 4.1.1 (Options for binaries) and 4.1.2 (Options
+ for libraries)
+ * Added note to 4.1.2: Libraries should be compiled with `-D_REENTRANT'
+ to make them compatible with LinuxThreads, by Rob Browning
+ <osiris@cs.utexas.edu>.
+ * Added note to 4.1.2: Libraries should be stripped with
+ "strip --strip-unneeded", by Guy Maor <maor@ece.utexas.edu>.
+ * Section 5.2: Policy changelog is now
+ "/usr/doc/debian-policy/changelog-policy.gz". This fixes bug #6130.
+ * Section 6.2 renamed to "Uploading your first Debian package". This
+ fixes bug #6130.
+
+ -- Christian Schwarz <schwarz@debian.org> Sat, 15 Mar 1997 18:08:56 +0100
+
+debian-manuals (2.1.2.2) frozen unstable;
+
+ * Fixed even more typographical and grammatical errors in Policy and
+ Programmer's manual
+ * Corrected the contact email addresses again.
+ * Added a paragraph to Policy 6.3 on taking over an old package (Guy Maor)
+ * Added a paragraph to Programmer 4.2.14 on listing distributions to load
+ a package into. (Guy Maor)
+ * Further clarification of use of absolute pathnames in scripts in
+ Programmer 6.1.
+
+ -- David Morris <bweaver@worf.netins.net> Tue, 3 Dec 1996 23:28:04 -0600
+
+debian-manuals (2.1.2.1) frozen unstable;
+
+ * Many editorial and formatting revisions with suggestions from Ian Jackson,
+ Guy Maor and others
+ * correction of chiark address in Policy 6.2
+ * footnote in Programmers chapter 2 pointing to deb(5) manpage for
+ description of deb file format.
+ * addition of more dpkg examples in Programmer chapter 2
+ * Replace paragraph in Policy 4.1 outlining compiling parameters for
+ shared libraries.
+ * Added paragraph in Programmer 6.1 on paths in maintainer scripts
+ (Bug #2481)
+ * Cleaned up language and formatting of Programmer's 12.2, shlibs
+ * Corrected contact addresses for listmaster and override-change
+
+ -- David Morris <bweaver@worf.netins.net> Wed, 27 Nov 1996 08:17:16 -0600
+
+debian-manuals (2.1.2.0) frozen unstable;
+
+ * Mostly editorial changes in Policy Manual.
+ * Added summary of distribution criteria to Introduction
+ * Added section headings for copyright criteria
+ * Fixed typos (Bugs #4485, #4622)
+ * Added paragraph in Compilation Options related to use of shared and
+ static libraries. (Bug #5299)
+ * Paragraph added about where to find PGP and other export restricted
+ packages in section on Procedure
+ * Change in List administrator and in the contact address for becoming
+ a package maintainer
+ * A paragraph added related to who to contact for package maintainer changes.
+ * Changed where to send upload announcements: uploads destined for unstable,
+ frozen, or experimental go to debian-devel-changes.
+
+ * Made some mostly editorial changes to Programmers Manual.
+ * Added a recommendation to debmake in Introduction.
+ * A further interpretation of the various Distributions is added with
+ the intent of helping people decide which one to choose. (section 4.2.14)
+ * Section 12 on Shared Libraries expanded with further technical information
+ on various shlib files
+ * Section in 2.2 on format of shlib file moved to new subsection within 12.
+ * Paragraph on adding a symlink without version number added to Shared
+ Library Section (Guy Maor, Bug #5299)
+
+ -- David Morris <bweaver@worf.netins.net> Fri, 22 Nov 1996 23:41:39 -0600
+
+debian-manuals (2.1.1.0) unstable;
+
+ * Hard links are forbidden in source packages (they didn't work anyway,
+ and can't easily be made to work reliably).
+ * Do not use dpkg-divert or update-alternatives without consultation.
+
+ * Do not need to declare dependencies on Essential packages.
+ * Restrictions on Pre-Depends stated in policy manual.
+ * debian/substvars file is now almost always auto-generated.
+ * Shared libraries must be installed stripped.
+ * Essential and Pre-Depends put together in policy manual.
+
+ * Explained component-wise (file-wise) vs. package-wise dependencies.
+
+ -- Ian Jackson <ian@chiark.greenend.org.uk> Thu, 12 Sep 1996 01:00:41 +0100
+
+debian-manuals (2.1.0.0) unstable;
+
+ * Upstream changelog must be installed too (was just recommended).
+
+ * Modification to use dpkg-shlibdeps added to conversion instructions.
+ * Packages which are buggy and orphaned but which are preserved for
+ compatibility go in contrib.
+
+ * Programmers' manual source package section refers to conversion
+ instructions in policy manual.
+ * Make it clear that recommending a non-free or contrib package puts a
+ package in contrib.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Sun, 1 Sep 1996 17:47:18 +0100
+
+debian-manuals (2.0.1.0) unstable;
+
+ * varargs.h and libtermcap are obsolete - use stdarg.h and ncurses.
+ * Shared library link/library ordering corrected (aargh).
+ * When to byte-compile Elisp files.
+ * Missing final newlines not represented by dpkg-source.
+
+ * Must post upload announcements to debian-changes.
+ * Moved some sections into new `configuring and building' chapter.
+ * Typo fixes.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Sat, 31 Aug 1996 20:07:22 +0100
+
+debian-manuals (2.0.0.0) unstable;
+
+ * Footnote added OK'ing copyrights which require name changes.
+ * More detail about changelog format names.
+
+ * Problematic licence restrictions are formatted as lists.
+ * Mentioned 822-date utility as way to generate RFC822 format dates.
+ * Typos corrected.
+ * Released.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Mon, 26 Aug 1996 14:27:34 +0100
+
+debian-manuals (0.2.1.1) unstable;
+
+ * Can't overwrite directories in one package with files in another.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Sat, 24 Aug 1996 18:44:54 +0100
+
+debian-manuals (0.2.1.0) unstable;
+
+ * Policy says when and how to include original source in upload.
+
+ * Need -sa on dpkg-genchanges/dpkg-buildpackage when converting.
+
+ * Use minor patchlevel for meaning changes which don't affect packages.
+ * More verbosity about netiquette.
+ * Reorganised participation and upload policy: merged with mailing lists.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Fri, 23 Aug 1996 12:48:09 +0100
+
+debian-manuals (0.2.0.1) experimental;
+
+ * Said that system administrators' manual does not exist.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Fri, 23 Aug 1996 04:05:36 +0100
+
+debian-manuals (0.2.0.0) experimental;
+
+ * Draft releases.
+
+ -- Ian Jackson <ian@chiark.chu.cam.ac.uk> Wed, 21 Aug 1996 15:07:53 +0100
+
+Local variables:
+mode: debian-changelog
+add-log-mailing-address: "phil@hands.com"
+End:
--- /dev/null
+Source: debian-policy
+Section: doc
+Priority: extra
+Maintainer: Debian Policy List <debian-policy@lists.debian.org>
+Standards-Version: ${debian-policy:Version}
+
+Package: debian-policy
+Architecture: all
+Suggests: doc-base
+Conflicts: dpkg-dev (<< 1.4.0.9), doc-base (<< 0.6)
+Description: Debian Policy Manual and related documents
+ This package contains:
+ - Debian Policy Manual
+ - Linux Filesystem Structure (FSSTND)
+ - Authoritative list of virtual package names
+ - Paper about libc6 migration
+ - Policy checklist for upgrading your packages
--- /dev/null
+
+This is the Debian package of Debian Policy Manual, the Linux
+Filesystem Standard and related documents. It was assembled by
+Christian Schwarz <schwarz@debian.org>.
+
+------------------------------------------------------------------------------
+Copyright of the Debian Policy Manual:
+
+Copyright ©1996 Ian Jackson.
+
+This manual is free software; you may redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+This is distributed in the hope that it will be useful, but without
+any warranty; without even the implied warranty of merchantability or
+fitness for a particular purpose. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License with
+your Debian GNU/Linux system, in /usr/doc/copyright/GPL, or with the
+dpkg source package as the file COPYING. If not, write to the Free
+Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
+02111-1307, USA.
+
+------------------------------------------------------------------------------
+Copyright of the Linux Filesystem Standard (FSSTND).
+
+
+Copyright (C) 1994, 1995 Daniel Quinlan
+
+Permission is granted to copy and distribute verbatim copies of this
+standard provided the copyright and this permission notice are
+preserved on all copies.
+
+Permission is granted for FSSTND contributors and participants to copy
+and distribute modified versions of this standard under the conditions
+for verbatim copying for purposes of filesystem standardization
+activities only, and subject to those restrictions listed below.
+
+The following restrictions apply to reproducing or transmitting the
+document in any form:
+
+ o All copies or portions thereof must identify the document's title
+ and section, and must be accompanied by this entire notice in a
+ prominent location.
+
+ o No portion of this document may be redistributed in any modified or
+ abridged form without the prior approval of the FSSTND coordinator.
+
+Any entities seeking permission to distribute any material derived
+from this document (other than verbatim copies) must contact the
+FSSTND coordinator for the appropriate license.
+
+--------------------------------------------------------------------------
--- /dev/null
+usr/doc/debian-policy/fsstnd
+usr/share/doc-base
--- /dev/null
+#!/bin/sh
+
+set -e
+
+case "$1" in
+ configure)
+ # continue below
+ ;;
+
+ abort-upgrade|abort-remove|abort-deconfigure)
+ exit 0
+ ;;
+
+ *)
+ echo "postinst called with unknown argument \`$1'" >&2
+ exit 0
+ ;;
+esac
+
+if [ -x /usr/sbin/install-docs ]; then
+ /usr/sbin/install-docs -i /usr/share/doc-base/debian-policy
+fi
--- /dev/null
+#!/bin/sh
+
+if [ -x /usr/sbin/install-docs ]; then
+ /usr/sbin/install-docs -r debian-policy
+fi
--- /dev/null
+#!/usr/bin/make -f
+
+DEB_VERSION := $(shell LC_ALL=C dpkg-parsechangelog | grep ^Version: | sed 's/^Version: *//')
+DATE := $(shell date +"%Y-%m-%d")
+
+build:
+ $(checkdir)
+ rm -f version.ent
+ echo "<!entity version \"$(DEB_VERSION)\">" >> version.ent
+ echo "<!entity date \"$(DATE)\">" >> version.ent
+ nsgmls -gues policy.sgml # check SGML syntax
+ debiandoc2html policy.sgml
+ debiandoc2text policy.sgml
+ lynx -dump upgrading-checklist.html > upgrading-checklist.text
+ gzip -9 policy.text
+ touch build
+
+clean:
+ $(checkdir)
+ -rm -f build
+ -rm -rf policy.html policy.text* policy.lout*
+ -rm -rf lout.li
+ -rm -rf upgrading-checklist.text
+ -rm -f `find . -name "*~"`
+ -rm -rf debian/tmp debian/files* core debian/substvars
+ -rm -rf version.ent
+
+binary-indep: checkroot build
+ $(checkdir)
+ -rm -rf debian/tmp
+ install -d debian/tmp
+ cd debian/tmp && install -d `cat ../dirs`
+
+ # create a substvar to reference from debian/control so that
+ # we don't hardcode the policy compliance of the policy
+ # package. I guess some might question this but I take it as
+ # a given that the debian-policy pkg must always comply with
+ # itself...
+ echo "debian-policy:Version=$(DEB_VERSION)" > debian/substvars
+
+ cp -a policy.html debian/tmp/usr/doc/debian-policy/
+ cp policy.text.gz debian/tmp/usr/doc/debian-policy/
+ cat policy.sgml | gzip -9 > debian/tmp/usr/doc/debian-policy/policy.sgml.gz
+ cp FSSTND-FAQ fsstnd* debian/tmp/usr/doc/debian-policy/fsstnd/
+ cp virtual-package-names-list.text debian/tmp/usr/doc/debian-policy/
+ cp upgrading-checklist.text debian/tmp/usr/doc/debian-policy/
+ cp libc6-migration.text debian/tmp/usr/doc/debian-policy/
+ gzip -9 debian/tmp/usr/doc/debian-policy/fsstnd/FSSTND-FAQ
+ cp debian/changelog debian/tmp/usr/doc/debian-policy/
+ gzip -9 debian/tmp/usr/doc/debian-policy/{changelog,libc6-migration.text,virtual-package-names-list.text,upgrading-checklist.text}
+ cp debian-policy.desc debian/tmp/usr/share/doc-base/debian-policy
+ cp debian/copyright debian/tmp/usr/doc/debian-policy/
+ mkdir debian/tmp/DEBIAN
+ cp debian/{postinst,prerm} debian/tmp/DEBIAN/
+ chmod +x debian/tmp/DEBIAN/{postinst,prerm}
+ dpkg-gencontrol -isp
+ chown -R root.root debian/tmp
+ chmod -R go=rX debian/tmp
+ dpkg --build debian/tmp ..
+ debiandoc2ps -pa4 -1 -O policy.sgml | gzip -9v > ../policy.ps.gz
+ dpkg-distaddfile -fdebian/files policy.ps.gz byhand -
+ GZIP=-9v tar zcf ../policy.html.tar.gz policy.html
+ dpkg-distaddfile -fdebian/files policy.html.tar.gz byhand -
+ cp policy.text.gz ..
+ dpkg-distaddfile -fdebian/files policy.text.gz byhand -
+ cp virtual-package-names-list.text ..
+ dpkg-distaddfile -fdebian/files virtual-package-names-list.text byhand -
+ cp libc6-migration.text ..
+ dpkg-distaddfile -fdebian/files libc6-migration.text byhand -
+
+binary-arch: checkroot build
+ $(checkdir)
+# There are no architecture-dependent files to be uploaded
+# generated by this package. If there were any they would be
+# made here.
+
+define checkdir
+ test -f debian/rules
+endef
+
+# Below here is fairly generic really
+
+binary: binary-indep binary-arch
+
+checkroot:
+ $(checkdir)
+ test root = "`whoami`"
+
+.PHONY: binary binary-arch binary-indep clean checkroot
--- /dev/null
+Here is a list of the major specification changes from FSSTND 1.1 to
+FSSTND 1.2. Since this is a simplification, it's a good idea to check
+out the standard document itself if one of these changes concerns you or
+your software.
+
+ * /bin: tcsh may be in /bin/tcsh or /usr/bin/tcsh. (It was
+ previously implied that /bin/tcsh was not compliant.)
+
+ * /dev: the Linux device registrar is now H. Peter Anvin
+ <Peter.Anvin@linux.org>, see the up-to-date device list at
+ ftp.yggdrasil.com in /pub/device-list.
+
+ * /etc: subdirectories of /etc/X11 for each window manager are no
+ longer required.
+
+ * /lib: /lib may contain miscellaneous shared libraries for binaries
+ required in /bin or /sbin. (As was the case before, but it's
+ spelled-out now.)
+
+ * /lib: /lib/modules is included, but not fully specified.
+
+ * /sbin: `ctrlaltdel' is optional.
+
+ * /usr: clarify that /usr/X386 is X11R5 on i386, /usr/X11R6 is X11R6
+ on any Linux system.
+
+ * /usr/include: /usr/include/g++ is now required.
+
+ * /var/adm is obsolete. lastlog is now in /var/log/lastlog. wtmp
+ is now in /var/log/utmp. utmp is now in /var/run/utmp.
+ Transitional symbolic links: /var/adm to /var/log, /var/log/utmp to
+ /var/run/utmp.
+
+ * /var/catman: /usr/man/cat[1-9] is for preformatted (i.e., on a
+ CD-ROM) manual pages. /var/catman remains a writable cache of
+ formatted manual pages.
+
+ * /var/named has been clarified, especially in relationship to
+ /etc/named.boot.
--- /dev/null
+
+ Debian library policy supplement draft for libc5->libc6 migration
+
+ This document is meant to tell what a Debian package providing a
+ library should do to support both libc6 (glibc2) and libc5.
+ Note that these requirements are for Debian 2.0 (codename hamm).
+
+ Contents
+ 1. Run time packages
+ 2. Development packages
+ 3. Source packages
+ 4. Requirements on libraries for Debian 2.0
+ 5. Conflicts and Dependencies
+ 6. Handling bugfix releases for Debian 1.3 (bo)
+ 7. Requirements on compiler packages
+
+ 1. Run time packages
+
+ A package providing a shared library has to support both C library
+ packages, libc5 and libc6 based libraries. This must be done using
+ two Debian packages, each depending on the correct C library
+ package.
+ The package naming convention currently suggests to name these
+ packages as follows. Some packages (mostly from base) may use
+ locations in /lib.
+
+ based on | package name | library location
+ --------------------------------------------
+ libc6 | libfoog [1]| /usr/lib/libfoo.so.<ver>
+ libc5 | libfoo | /usr/lib/libc5-compat/libfoo.so.<ver> [2]
+
+ If a library runtime package contains files that are needed by
+ both versions of the library, a new package should be made for
+ just these files that both other packages depend on.
+
+ This package naming convention does _not_ apply if a package uses
+ different sonames for libc5 and libc6 based packages
+
+ There are two exceptions from this rule. The shared linker
+ ld-linux.so.1 and the C library files libc.so.5 and libm.so.5
+ should still be located in /lib, not in /lib/libc5-compat.
+
+ Packages based on X have to use /usr/X11R6 as prefix, not /usr.
+ Note that the X libraries are designed to work with both C libraries.
+
+ 2. Development packages
+
+ The Debian policy requires that all files needed for compiling/linking
+ other packages with the library are in a separate package, the
+ development package. Up to now this package simply was called
+ libfoo-dev. As packages based on libc5 and libc6 usually cannot
+ use the same development files there has to be a clear statement
+ how to separate these. So for now the following packages are
+ required:
+
+ based on | package name | hierarchy locations
+ ---------------------------------------------------------------
+ libc6 | libfoog-dev | /usr/{lib,include}
+ libc5 | libfoo-altdev | /usr/<a>-linuxlibc1/{lib,include}
+
+ Note that <a> usually is i486, but may not be hardcoded in
+ debian/rules. It should be obtained using
+ dpkg --print-gnu-build-architecture
+
+ Remember that the libfoo-altdev package has to include symlinks
+ /usr/<a>-linuxlibc1/lib/libfoo.so -> /usr/lib/libc5-compat/libfoo.so.<ver>
+ to enable using the shared libraries when compiling.
+
+ All documentation that is not depending on whether the library was
+ compiled for libc5 or for libc6 should be either part of the
+ libfoog-dev package or be put into a separate package if it is
+ large. In particular this includes manpages which _have_ to be part
+ of the libfoog-dev package.
+
+ Note that the choice to base Debian 2.0 on libc6 fixed the fact
+ that the main locations will be used for libc6 packages. The
+ alternate locations are used for libc5 based packages.
+ This decision does not necessarily mean that by default the
+ compiler uses the libc6 packages, please read section 4 for more
+ information. Using a four-way approach for library locations
+ (standard and alternate locations for libc6 and libc5 based
+ packages) will make Debian systems inconsistent with each other,
+ something we should avoid at (nearly) all costs.
+
+
+ 3. Source packages
+
+ The source package name should _not_ be modified for hamm.
+
+ If a bugfix for bo has to be released, use bo's source package to
+ extract the bo source and add for each hamm release a line to
+ debian/changelog stating that this release was a hamm release.
+ Make your bugfix changes, including changes to the control file
+ according to section 6.
+
+ Then unpack the hamm source again, update debian/changelog and
+ debian/control to figure the bo release, and release a new hamm
+ package (including the bugfix, if it affects hamm as well). [3]
+
+ 4. Requirements on libraries for Debian 2.0
+
+ Libraries (regardless of which library they're compiled against) need
+ to have runtime dependencies on one of libc, libdl or libm to enable
+ the shared linker to determine which library to use for a binary.
+ These runtime dependencies are _NOT_ dependencies in the Debian
+ way, but dependencies generated by the linker when generating the
+ shared library. See the binutils manual for more information.
+
+ In general we want libraries compiled for libc6 to be thread-safe.
+ This is, however, not practical or feasible for every library
+ package. Making a library thread-safe involves quite a lot of work,
+ much of it nontrivial.
+ Thread-safe means that the following changes must be made to the
+ library packages:
+
+ - compile the library using -D_REENTRANT or -D_THREAD_SAFE
+ - there may be no permanent data residing in the library memory that
+ can be different for different threads.
+ this means in the first place no static or global variables that
+ are not in some way protected from access by a different threads
+ via mutexes.
+ - all write access to files from a library must be both protected
+ using some file locking mechanism in addition to using mutexes.
+ - at least some library functions must be protected from being
+ used at the same time by two threads sharing the same memory
+ space. This is done using mutexes.
+
+ As these usually are all nontrivial changes to a library if it isn't
+ thread-safe already (in which case just using -D_REENTRANT should
+ be used in addition to whatever the library uses to support threads),
+ I suggest that no-one starts doing this without getting in contact with
+ the upstream maintainer(s).
+
+ If a library has a thread-safe version, the debian package should
+ use this. The performance deficits usually are very small when not
+ linking to libpthreads so only if there are serious reasons, the
+ debian package may include the non-thread-safe version.
+
+ There will be a list available that lists all libraries part of
+ Debian and their current status regarding compliance with these
+ standard requirements. This list will be posted regularly to
+ debian-devel by Helmut Geyer <Helmut.Geyer@iwr.uni-heidelberg.de>.
+
+ 5. Conflicts & Dependencies for hamm packages
+
+ The libfoog package _has_ to conflict with all versions of the
+ libfoo package before it was made to use the libc5-compat
+ directory. Furthermore it should depend on libc6.
+
+ The libfoog-dev package must depend on libc6-dev and the libfoog
+ package of the same release. It has to conflict with the libfoo-dev
+ package.
+
+ The hamm libfoo package has to depend on libc6 and has to conflict
+ with libfoo-dev and libc5-dev.
+
+ The libfoo-altdev package has to depend on the libc5-altdev and
+ libfoo package of the same release.
+
+ 6. Handling bugfixes for Debian 1.3 (bo)
+
+ Using the dependencies from Section 5. there will be problems with
+ making bugfix releases for bo. These have to be handled carefully
+ as otherwise there may be tremendous problems for people using
+ hamm systems.
+ As there is one package name used for both hamm and bo that stays
+ the same (libfoo), we have to very careful.
+ The following steps should be followed:
+
+ i) when making a bo bugfix release, be sure to make a hamm release
+ at the same time, using a higher release number for the hamm
+ release. Update the hamm package's conflicts according to
+ section 5.
+ ii) Any bo package for libfoo _has_ to conflict with libc6,
+ libfoo-altdev and libfoog.
+ iii)The libfoo-dev package has to conflict with libc5-altdev and
+ has to depend on libc5-dev.
+
+
+ 7. Requirements on compiler packages
+
+ The compiler and binutils packages have to provide working
+ development environments for both C libraries. Basically (that is
+ from the compiler standpoint) there is no real difference between
+ the two environments, only some paths and automatic definitions
+ have to be changed. All this can be done (and is in fact done) by
+ supplying a different specs file in a different location.
+
+ The gcc packages do this as follows:
+
+ The gcc package uses libc6 by default and is installed in /usr/bin.
+
+ The alt-gcc package uses libc5 by default and is located in
+ /usr/i486-linuxlibc1/bin. By prepending this to the path this can
+ be made the default.
+
+ These requirements are fulfilled by the current gcc packages.
+
+Remarks:
+
+ [1] the name of a library package often includes the major version
+ number of the library. If so, the 'g' should come before this
+ number, e.g. libgdbmg1 as package name for the libc6 based
+ runtime package for libgdbm.
+
+ [2] The location ../libc5-compat was introduced in the ldso package. As
+ ldso is a package on all linus distributions we'll keep it for
+ compatibility with other distributions even though
+ /usr/i486-linuxlibc1/lib would be more consistent.
+
+ [3] An example for relevant sections of the changelogs for a bugfix
+ release for both bo and hamm (with the last bo release being
+ libfoo 1.7.54-6 released on Mon, 16 Jun 1997 and the last hamm
+ release being libfoo 1.7.54-8 released on Wed, 18 Jun 1997):
+
+-=-=-=-=-=-=-=-=-= bo changelog =-=-=-=-=-=-=-=-=-
+libfoo (1.7.54-9) stable; urgency=low
+
+ * fixed bug #543547884
+
+ -- J.D. Maintainer <jdm@debian.org> Fri, 20 Jun 1997 08:32:03 +0200
+
+libfoo (1.7.54-8) unstable; urgency=low
+
+ * hamm release
+
+ -- J.D. Maintainer <jdm@debian.org> Fri, 20 Jun 1997 08:32:03 +0200
+
+libfoo (1.7.54-7) unstable; urgency=low
+
+ * hamm release
+
+ -- J.D. Maintainer <jdm@debian.org> Fri, 20 Jun 1997 08:32:03 +0200
+
+libfoo (1.7.54-6) stable; urgency=low
+
+ * added handling of bar.
+
+ -- J.D. Maintainer <jdm@debian.org> Mon, 16 Jun 1997 18:45:14 +0200
+-=-=-=-=-=-=-=-=-= hamm changelog =-=-=-=-=-=-=-=-=-
+libfoo (1.7.54-10) unstable; urgency=low
+
+ * fixed bug #543547884
+
+ -- J.D. Maintainer <jdm@debian.org> Fri, 20 Jun 1997 08:52:09 +0200
+
+libfoo (1.7.54-9) stable; urgency=low
+
+ * bo release
+
+ -- J.D. Maintainer <jdm@debian.org> Fri, 20 Jun 1997 08:52:09 +0200
+
+libfoo (1.7.54-8) unstable; urgency=low
+
+ * finally made package compliant with those strange policy for hamm
+ libs.
+
+ -- J.D. Maintainer <jdm@debian.org> Wed, 18 Jun 1997 15:34:12 +0200
+-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+--
+Helmut Geyer Helmut.Geyer@iwr.uni-heidelberg.de
+public PGP key available : finger geyer@saturn.iwr.uni-heidelberg.de
+
--- /dev/null
+Document: packaging-manual
+Title: Debian Packaging Manual
+Author: Ian Jackson
+Abstract: This manual describes the technical aspects of creating Debian binary
+ and source packages. It also documents the interface between
+ dselect and its access method scripts. It does not deal with
+ the Debian Project policy requirements, and it assumes familiarity
+ with dpkg's functions from the system administrator's perspective.
+Section: Apps/Programming
+
+Format: debiandoc-sgml
+Files: /usr/doc/packaging-manual/packaging.sgml.gz
+
+Format: text
+Files: /usr/doc/packaging-manual/packaging.text.gz
+
+Format: HTML
+Index: /usr/doc/packaging-manual/packaging.html/index.html
+Files: /usr/doc/packaging-manual/packaging.html/*.html
--- /dev/null
+<!doctype debiandoc system>
+
+<!--
+ Debian GNU/Linux Packaging Manual.
+ Copyright (C)1996 Ian Jackson; released under the terms of the GNU
+ General Public License, version 2 or (at your option) any later.
+ Revised: David A. Morris (bweaver@debian.org)
+ Maintainer since 1998, Christian Schwarz <schwarz@debian.org>
+ -->
+
+<book>
+
+<title>Debian Packaging Manual
+<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+<author>Revised: David A. Morris <email/bweaver@debian.org/
+<author>Maintainer: Christian Schwarz <email/schwarz@debian.org/
+<version>version 2.4.1.0, 14 April 1998
+
+<abstract>
+This manual describes the technical aspects of creating Debian binary
+and source packages. It also documents the interface between
+<prgn/dselect/ and its access method scripts. It does not deal with
+the Debian Project policy requirements, and it assumes familiarity
+with <prgn/dpkg/'s functions from the system administrator's
+perspective.
+
+<copyright>Copyright ©1996 Ian Jackson.
+<p>
+
+This manual is free software; you may redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+<p>
+
+This is distributed in the hope that it will be useful, but
+<em>without any warranty</em>; without even the implied warranty of
+merchantability or fitness for a particular purpose. See the GNU
+General Public License for more details.
+<p>
+
+A copy of the GNU General Public License is available as
+<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
+distribution or on the World Wide Web at
+<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it
+by writing to the Free Software Foundation, Inc., 59 Temple Place -
+Suite 330, Boston, MA 02111-1307, USA.
+<p>
+
+<toc sect>
+
+<!-- Describes the technical interface between a package and dpkg.
+
+How to safely put shared libraries in a package. Details of dpkg's
+handling of individual files. Sections on when to use which feature
+(eg Replaces vs. Replaces/Conflicts vs. update-alternatives
+vs. diversions) Cross-references to the policy document (see below)
+where appropriate. Description of the interface between dselect and
+its access methods. Hints on where to start with a new package (ie,
+the hello package). What to do about file aliasing.
+
+file aliasing
+
+Manpages are required for: update-rc.d, diversions,
+update-alternatives, install-info in a package.
+
+-->
+
+<chapt id="scope">Introduction and scope of this manual
+<p>
+
+<prgn/dpkg/ is a suite of programs for creating binary package files
+and installing and removing them on Unix systems.<footnote><prgn/dpkg/
+is targetted primarily at Debian GNU/Linux, but may work on or be
+ported to other systems.</footnote>
+<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>
+
+This manual describes the technical aspects of creating Debian binary
+packages (<tt/.deb/ files). It documents the behaviour of the
+package management programs <prgn/dpkg/, <prgn/dselect/ et al. and and the
+way they interact with packages.
+<p>
+
+It also documents the interaction between <prgn/dselect/'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>
+
+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 conjuction with those programs' manpages.
+<p>
+
+The utility programs which are provided with <prgn/dpkg/ for managing
+various system configuration and similar issues, such as
+<prgn/update-rc.d/ and <prgn/install-info/, are not described in
+detail here - please see their manpages.
+<p>
+
+It does <em/not/ describe the policy requirements imposed on Debian
+packages, such as the permissions on files and directories,
+documentation requirements, upload procedure, and so on. You should
+see the Debian packaging policy manual for these details. (Many of
+them will probably turn out to be helpful even if you don't plan to
+upload your package and make it available as part of the
+distribution.)
+<p>
+
+It is assumed that the reader is reasonably familiar with the
+<prgn/dpkg/ System Administrators' manual. Unfortunately this manual
+does not yet exist.
+<p>
+
+The Debian version of the FSF's GNU hello program is provided as an
+example for people wishing to create Debian packages. The Debian
+<prgn/debmake/ package is recommended as a very helpful tool in
+creating and maintaining Debian packages. However, while the tools and
+examples are helpful, they do not replace the need to read and follow
+the Policy and Programmer's Manual.
+
+<chapt id="binarypkg">Binary packages
+<p>
+
+The binary package has two main sections. The first part consists of
+various control information files and scripts used by <prgn/dpkg/ when
+installing and removing. See <ref id="controlarea">.
+<p>
+
+The second part is an archive containing the files and directories to
+be installed.
+<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 <tt>deb(5)</> manpage.
+
+
+<sect id="bincreating">Creating package files - <prgn/dpkg-deb/
+<p>
+
+All manipulation of binary package files is done by <prgn/dpkg-deb/;
+it's the only program that has knowledge of the format.
+(<prgn/dpkg-deb/ may be invoked by calling <prgn/dpkg/, as <prgn/dpkg/ will
+spot that the options requested are appropriate to <prgn/dpkg-deb/ and
+invoke that instead with the same arguments.)
+<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
+filesystem data part of the package. In Debian-format source packages
+this directory is usually <tt>debian/tmp</tt>, relative to the top of
+the package's source tree.
+<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>
+
+With current versions of <prgn/dpkg/ 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>
+
+You need to add one special directory to the root of the miniature
+filesystem tree you're creating: <prgn/DEBIAN/. It should contain the
+control information files, notably the binary package control file
+(see <ref id="controlfile">).
+<p>
+
+The <prgn/DEBIAN/ directory will not appear in the filesystem archive of
+the package, and so won't be installed by <prgn/dpkg/ when the package
+is installed.
+<p>
+
+When you've prepared the package, you should invoke:
+<example>
+dpkg --build <var/directory/
+</example>
+<p>
+
+This will build the package in <tt/<var/directory/.deb/.
+(<prgn/dpkg/ knows that <tt/--build/ is a <prgn/dpkg-deb/ option, so it
+invokes <prgn/dpkg-deb/ with the same arguments to build the package.)
+<p>
+
+See the manpage <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/.deb
+dpkg-deb --contents <var/filename/.deb
+dpkg --contents <var/filename/.deb
+</example>
+To view the copyright file for a package you could use this command:
+<example>
+dpkg --fsys-tarfile <var/filename/.deb | tar xof usr/doc/<var/\*/copyright | less
+</example>
+
+<sect id="controlarea">Package control information files
+<p>
+
+The control information portion of a binary package is a collection of
+files with names known to <prgn/dpkg/. It will treat the contents of
+these files specially - some of them contain information used by
+<prgn/dpkg/ when installing or removing the package; others are scripts
+which the package maintainer wants <prgn/dpkg/ to run.
+<p>
+
+It is possible to put other files in the package control area, but
+this is not generally a good idea (though they will largely be
+ignored).
+<p>
+
+Here is a brief list of the control info files supported by <prgn/dpkg/
+and a summary of what they're used for.
+<p>
+
+<taglist>
+<tag><tt/control/
+<item>
+
+This is the key description file used by <prgn/dpkg/. 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="controlfile">.
+<p>
+
+It is usually generated automatically from information in the source
+package by the <prgn/dpkg-gencontrol/ program, and with assistance
+from <prgn/dpkg-shlibdeps/. See <ref id="sourcetools">.
+
+<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/
+<item>
+
+These are exectuable files (usually scripts) which <prgn/dpkg/ 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/.
+Details of when and how they are called are in
+<ref id="maintainerscripts">.
+<p>
+
+It is very important to make these scripts idempotent.<footnote>That
+means that if it runs successfully or fails and then you call it again
+it doesn't bomb out, but just ensures that everything is the way it
+ought to be.</footnote> This is so that if an error occurs, the user
+interrupts <prgn/dpkg/ or some other unforeseen circumstance happens you
+don't leave the user with a badly-broken package.
+<p>
+
+The maintainer scripts are guaranteed to run with a controlling
+terminal and can interact with the user. If they need to prompt for
+passwords, do full-screen interaction or something similar you should
+do these things to and from <tt>/dev/tty</>, since <prgn/dpkg/ will at
+some point redirect scripts' standard input and output so that it can
+log the installation process. Likewise, because these scripts may be
+executed with standard output redirected into a pipe for logging
+purposes, Perl scripts should set unbuffered output by setting
+<tt/$|=1/ so that the output is printed immediately rather than being
+buffered.
+<p>
+
+Each script should return a zero exit status for success, or a nonzero
+one for failure.
+
+<tag><tt/conffiles/
+<item>
+
+This file contains a list of configuration files which are to be
+handled automatically by <prgn/dpkg/ (see <ref id="conffiles">). Note
+that not necessarily every configuration file should be listed here.
+
+<tag><tt/shlibs/
+<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/ when it determines what dependencies are
+required in a package control file. The <tt/shlibs/ file format is
+described on <ref id="shlibs">.
+<p>
+
+</taglist>
+
+<sect id="controlfile">The main control information file: <tt/control/
+<p>
+
+The most important control information file used by <prgn/dpkg/ when it
+installs a package is <tt/control/. It contains all the package's
+`vital statistics'.
+<p>
+
+The binary package control files of packages built from Debian sources
+are made by a special tool, <prgn/dpkg-gencontrol/, which reads
+<tt>debian/control</> and <tt>debian/changelog</> to find the
+information it needs. See <ref id="sourcepkg"> for more details.
+<p>
+
+The fields in binary package control files are:
+<list compact>
+
+<item><qref id="f-Package"><tt/Package/</> (mandatory)
+<item><qref id="versions"><tt/Version/</> (mandatory)
+
+<item><qref id="f-Architecture"><tt/Architecture/</>
+(mandatory)<footnote>This field should appear in all packages, though
+<prgn/dpkg/ doesn't require it yet so that old packages can still be
+installed.</footnote>
+
+<item><qref id="relationships"><tt/Depends/, <tt/Provides/ et al.</>
+<item><qref id="f-Essential"><tt/Essential/</>
+<item><qref id="f-Maintainer"><tt/Maintainer/</>
+<item><qref id="f-classification"><tt/Section/, <tt/Priority/</>
+<item><qref id="f-Source"><tt/Source/</>
+<item><qref id="descriptions"><tt/Description/</>
+<item><qref id="f-Installed-Size"><tt/Installed-Size/</>
+
+</list>
+<p>
+
+A description of the syntax of control files and the purpose of these
+fields is available in <ref id="controlfields">.
+
+
+<chapt id="sourcepkg">Source packages
+<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>
+
+There was a previous version of the Debian source format, which is now
+being phased out. Instructions for converting an old-style package
+are given in the Debian policy manual.
+
+<sect id="sourcetools">Tools for processing source packages
+<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>
+
+They are introduced and typical uses described here; see <manref
+name=dpkg-source section=1> for full documentation about their
+arguments and operation.
+<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/ example package.
+
+<sect1><prgn/dpkg-source/ - packs and unpacks Debian source packages
+<p>
+
+This program is frequently used by hand, and is also called from
+package-independent automated building scripts such as
+<prgn/dpkg-buildpackage/.
+<p>
+
+To unpack a package it is typically invoked with
+<example>
+dpkg-source -x <var>.../path/to/filename</>.dsc
+</example>
+with the <tt/<var/filename/.tar.gz/ and
+<tt/<var/filename/.diff.gz/ (if applicable) in the same directory. It
+unpacks into <tt/<var/package/-<var/version//, and if applicable
+<tt/<var/package/-<var/version/.orig/, in the current directory.
+<p>
+
+To create a packed source archive it is typically invoked:
+<example>
+dpkg-source -b <var/package/-<var/version/
+</example>
+This will create the <tt/.dsc/, <tt/.tar.gz/ and <tt/.diff.gz/ (if
+appropriate) in the current directory. <prgn/dpkg-source/ does not
+clean the source tree first - this must be done separately if it is
+required.
+<p>
+
+See also <ref id="sourcearchives">.
+
+
+<sect1><prgn/dpkg-buildpackage/ - overall package-building control
+script
+<p>
+
+<prgn/dpkg-buildpackage/ is a script which invokes <prgn/dpkg-source/,
+the <tt>debian/rules</> targets <prgn/clean/, <prgn/build/ and
+<prgn/binary/, <prgn/dpkg-genchanges/ and <prgn/pgp/ to build a signed
+source and binary package upload.
+<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>
+<tag><tt/-uc/, <tt/-us/
+<item>Do not PGP-sign the <tt/.changes/ file or the source package
+<tt/.dsc/ file, respectively.
+
+<tag><tt/-p<var/pgp-command//
+<item>Invoke <var/pgp-command/ instead of finding <tt/pgp/ on the
+<prgn/PATH/. <var/pgp-command/ must behave just like <prgn/pgp/.
+
+<tag><tt/-r<var/root-command//
+<item>When root privilege is required, invoke the command
+<var/root-command/. <var/root-command/ should invoke its first
+argument as a command, from the <prgn/PATH/ if necessary, and pass its
+second and subsequent arguments to the command it calls. If no
+<var/root-command/ is supplied then <var/dpkg-buildpackage/ 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.
+
+<tag><tt/-b/, <tt/-B/
+<item>Two types of binary-only build and upload - see <manref
+name=dpkg-source section=1>.
+</taglist>
+
+
+<sect1><prgn/dpkg-gencontrol/ - generates binary package control files
+<p>
+
+This program is usually called from <tt>debian/rules</> (see <ref
+id="sourcetree">) in the top level of the source tree.
+<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/<footnote>This is so that the control file which is
+produced has the right permissions</footnote>.
+<p>
+
+<prgn/dpkg-gencontrol/ 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>
+
+It is also necessary for <prgn/dpkg-gencontrol/ to be run after
+<prgn/dpkg-shlibdeps/ so that the variable substitutions created by
+<prgn/dpkg-shlibdeps/ in <tt>debian/substvars</> are available.
+<p>
+
+For a package which generates only one binary package, and which
+builds it in <tt>debian/tmp</> relative to the top of the source
+package, it is usually sufficient to call:
+<example>
+dpkg-gencontrol
+</example>
+<p>
+
+Sources which build several binaries will typically need something
+like:
+<example>
+dpkg-gencontrol -Pdebian/tmp-<var/pkg/ -p<var/package/
+</example>
+The <tt/-P/ tells <prgn/dpkg-gencontrol/ that the package is being
+built in a non-default directory, and the <tt/-p/ tells it which
+package's control file should be generated.
+<p>
+
+<prgn/dpkg-gencontrol/ also adds information to the list of files in
+<tt>debian/files</>, for the benefit of (for example) a future
+invocation of <prgn/dpkg-genchanges/.
+
+
+<sect1><prgn/dpkg-shlibdeps/ - calculates shared library dependencies
+<p>
+
+This program is usually called from <tt>debian/rules</> just before
+<prgn/dpkg-gencontrol/ (see <ref id="sourcetree">), in the top level
+of the source tree.
+<p>
+
+Its arguments are executables<footnote>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.</footnote> for which shared library
+dependencies should be included in the binary package's control file.
+<p>
+
+If some of the executable(s) shared libraries should only warrant a
+<tt/Recommends/ or <tt/Suggests/, or if some warrant a
+<tt/Pre-Depends/, this can be achieved by using the
+<tt/-d<var/dependency-field// option before those executable(s).
+(Each <tt/-d/ option takes effect until the next <tt/-d/.)
+<p>
+
+<prgn/dpkg-shlibdeps/ does not directly cause the output control file
+to be modified. Instead by default it adds to the
+<tt>debian/substvars</> file variable settings like
+<tt/shlibs:Depends/. These variable settings must be referenced in
+dependency fields in the appropriate per-binary-package sections of
+the source control file.
+<p>
+
+For example, the <prgn/procps/ package generates two kinds of
+binaries, simple C binaries like <prgn/ps/ which require a
+predependency and full-screen ncurses binaries like <prgn/top/ which
+require only a recommendation. It can say in its <tt>debian/rules</>:
+<example>
+dpkg-shlibdeps -dPre-Depends ps -dRecommends top
+</example>
+and then in its main control file <tt>debian/control</>:
+<example>
+<var/.../
+Package: procps
+Pre-Depends: ${shlibs:Pre-Depends}
+Recommends: ${shlibs:Recommends}
+<var/.../
+</example>
+<p>
+
+Sources which produce several binary packages with different shared
+library dependency requirements can use the <tt/-p<var/varnameprefix//
+option to override the default <tt/shlib:/ prefix (one invocation of
+<prgn/dpkg-shlibdeps/ per setting of this option). They can thus
+produce several sets of dependency variables, each of the form
+<tt/<var/varnameprefix/:<var/dependencyfield//, which can be referred
+to in the appropriate parts of the binary package control files.
+
+
+<sect1><prgn/dpkg-distaddfile/ - adds a file to <tt>debian/files</>
+<p>
+
+Some packages' uploads need to include files other than the source and
+binary package files.
+<p>
+
+<prgn/dpkg-distaddfile/ adds a file to the <tt>debian/files</> file so
+that it will be included in the <tt/.changes/ file when
+<prgn/dpkg-genchanges/ is run.
+<p>
+
+It is usually invoked from the <prgn/binary/ target of
+<tt>debian/rules</>:
+<example>
+dpkg-distaddfile <var/filename/ <var/section/ <var/priority/
+</example>
+The <var/filename/ is relative to the directory where
+<prgn/dpkg-genchanges/ will expect to find it - this is usually the
+directory above the top level of the source tree. The
+<tt>debian/rules</> target should put the file there just before or
+just after calling <prgn/dpkg-distaddfile/.
+<p>
+
+The <var/section/ and <var/priority/ are passed unchanged into the
+resulting <tt/.changes/ file. See <ref id="f-classification">.
+
+
+<sect1><prgn/dpkg-genchanges/ - generates a <tt/.changes/ upload
+control file
+<p>
+
+This program is usually called by package-independent automatic
+building scripts such as <prgn/dpkg-buildpackage/, but it may also be
+called by hand.
+<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
+<tt/.changes/ 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.
+
+
+<sect1><prgn/dpkg-parsechangelog/ - produces parsed representation of
+a changelog
+<p>
+
+This program is used internally by <prgn/dpkg-source/ et al. It may
+also occasionally be useful in <tt>debian/rules</> and elsewhere. It
+parses a changelog, <tt>debian/changelog</> by default, and prints a
+control-file format representation of the information in it to
+standard output.
+
+<sect id="sourcetree">The Debianised source tree
+<p>
+
+The source archive scheme described later is intended to allow a
+Debianised source tree with some associated control information to be
+reproduced and transported easily. The Debianised source tree is a
+version of the original program with certain files added for the
+benefit of the Debianisation process, and with any other changes
+required made to the rest of the source code and installation scripts.
+<p>
+
+The extra files created for Debian are in the subdirectory <tt/debian/
+of the top level of the Debianised source tree. They are described
+below.
+
+<sect1><tt>debian/rules</tt> - the main building script
+<p>
+
+This file is an executable makefile, and contains the package-specific
+recipies for compiling the package and building binary package(s) out
+of the source.
+<p>
+
+It must start with the line <tt>#!/usr/bin/make -f</tt>, so that it
+can be invoked by saying its name rather than invoking <prgn/make/
+explicitly.
+<p>
+
+The targets which are required to be present are:
+
+<taglist>
+<tag/<tt/build//
+<item>
+
+This should perform all non-interactive configuration and compilation
+of the package. If a package has an interactive pre-build
+configuration routine, the Debianised source package should be built
+after this has taken place, so that it can be built without rerunning
+the configuration.
+<p>
+
+For some packages, notably ones where the same source tree is compiled
+in different ways to produce two binary packages, the <prgn/build/
+target does not make much sense. For these packages it is good enough
+to provide two (or more) targets (<tt/build-a/ and <tt/build-b/ or
+whatever) for each of the ways of building the package, and a
+<prgn/build/ target that does nothing. The <prgn/binary/ target will have
+to build the package in each of the possible ways and make the binary
+package out of each.
+<p>
+
+The <prgn/build/ target must not do anything that might require root
+privilege.
+<p>
+
+The <prgn/build/ target may need to run <prgn/clean/ first - see below.
+<p>
+
+When a package has a configuration routine that takes a long time, or
+when the makefiles are poorly designed, or when <prgn/build/ needs to
+run <prgn/clean/ first, it is a good idea to <tt/touch build/ when the
+build process is complete. This will ensure that if <tt>debian/rules
+build</tt> is run again it will not rebuild the whole program.
+
+<tag/<tt/binary/, <tt/binary-arch/, <tt/binary-indep/
+<item>
+
+The <prgn/binary/ target should be all that is necessary for the user
+to build the binary package. It is split into two parts:
+<prgn/binary-arch/ builds the packages' output files which are
+specific to a particular architecture, and <prgn/binary-indep/
+builds those which are not.
+<p>
+
+<prgn/binary/ should usually be a target with no commands which simply
+depends on <prgn/binary-arch/ and <prgn/binary-indep/.
+<p>
+
+Both <prgn/binary-*/ targets should depend on the <prgn/build/ target,
+above, so that the package is built if it has not been already. It
+should then create the relevant binary package(s), using
+<prgn/dpkg-gencontrol/ to make their control files and <prgn/dpkg-deb/
+to build them and place them in the parent of the top level directory.
+<p>
+
+If one of the <prgn/binary-*/ targets has nothing to do (this will be
+always be the case if the source generates only a single binary
+package, whether architecture-dependent or not) it <em/must/ still
+exist, but should always succeed.
+<p>
+
+<ref id="binarypkg"> describes how to construct binary packages.
+<p>
+
+The <prgn/binary/ targets must be invoked as root.
+
+<tag/<tt/clean//
+<item>
+
+This should undo any effects that the <prgn/build/ and <prgn/binary/
+targets may have had, except that it should leave alone any output
+files created in the parent directory by a run of <prgn/binary/.
+<p>
+
+If a <prgn/build/ file is touched at the end of the <prgn/build/ target,
+as suggested above, it must be removed as the first thing that
+<prgn/clean/ does, so that running <prgn/build/ again after an interrupted
+<prgn/clean/ doesn't think that everything is already done.
+<p>
+
+The <prgn/clean/ target must be invoked as root if <prgn/binary/ has
+been invoked since the last <prgn/clean/, or if <prgn/build/ has been
+invoked as root (since <prgn/build/ may create directories, for
+example).
+
+<tag/<tt/get-orig-source/ (optional)/
+<item>
+
+This target fetches the most recent version of the original source
+package from a canonical archive site (via FTP or WWW, for example),
+does any necessary rearrangement to turn it into the original source
+tarfile format described below, and leaves it in the current directory.
+<p>
+
+This target may be invoked in any directory, and should take care to
+clean up any temporary files it may have left.
+<p>
+
+This target is optional, but providing it if possible is a good idea.
+
+</taglist>
+
+The <prgn/build/, <prgn/binary/ and <prgn/clean/ targets must be
+invoked with a current directory of the package's top-level
+directory.
+
+<p>
+
+Additional targets may exist in <tt>debian/rules</tt>, either as
+published or undocumented interfaces or for the package's internal
+use.
+
+
+<sect1><tt>debian/control</tt>
+<p>
+
+This file contains version-independent details about the source
+package and about the binary packages it creates.
+<p>
+
+It is a series of sets of control fields, each syntactically similar
+to a binary package control file. The sets are separated by one or
+more blank lines. The first set is information about the source
+package in general; each subsequent set describes one binary package
+that the source tree builds.
+<p>
+
+The syntax and semantics of the fields are described below in
+<ref id="controlfields">.
+<p>
+
+The general (binary-package-independent) fields are:
+<list compact>
+<item><qref id="f-Source"><tt/Source/</> (mandatory)
+<item><qref id="f-Maintainer"><tt/Maintainer/</>
+<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</>
+(classification, mandatory)
+<item><qref id="f-Standards-Version"><tt/Standards-Version/</>
+</list>
+<p>
+
+The per-binary-package fields are:
+<list compact>
+<item><qref id="f-Package"><tt/Package/</> (mandatory)
+<item><qref id="f-Architecture"><tt/Architecture/</> (mandatory)
+<item><qref id="descriptions"><tt/Description/</>
+<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> (classification)
+<item><qref id="f-Essential"><tt/Essential/</>
+<item><qref id="relationships"><tt/Depends/ et al.</> (package interrelationships)
+</list>
+<p>
+
+These fields are used by <prgn/dpkg-gencontrol/ to generate control
+files for binary packages (see below), by <prgn/dpkg-genchanges/ to
+generate the <tt/.changes/ file to accompany the upload, and by
+<prgn/dpkg-source/ when it creates the <tt/.dsc/ source control file as
+part of a source archive.
+<p>
+
+The fields here may contain variable references - their values will be
+substituted by <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ or
+<prgn/dpkg-source/ when they generate output control files. See <ref
+id="srcsubstvars"> for details.
+<p>
+
+<sect2>User-defined fields
+<p>
+
+Additional user-defined fields may be added to the source package
+control file. Such fields will be ignored, and not copied to (for
+example) binary or source package control files or upload control
+files.
+<p>
+
+If you wish to add additional unsupported fields to these output files
+you should use the mechanism described here.
+<p>
+
+Fields in the main source control information file with names starting
+<tt/X/, followed by one or more of the letters <tt/BCS/ and a hyphen
+<tt/-/, will be copied to the output files. Only the part of the
+field name after the hyphen will be used in the output file. Where
+the letter <tt/B/ is used the field will appear in binary package
+control files, where the letter <tt/S/ is used in source package
+control files and where <tt/C/ is used in upload control
+(<tt/.changes/) files.
+<p>
+
+For example, if the main source information control file contains the
+field
+<example>
+XBS-Comment: I stand between the candle and the star.
+</example>
+then the binary and source package control files will contain the
+field
+<example>
+Comment: I stand between the candle and the star.
+</example>
+
+<sect1 id="dpkgchangelog"><tt>debian/changelog</>
+<p>
+
+This file records the changes to the Debian-specific parts of the
+package<footnote>Though there is nothing stopping an author who is
+also the Debian maintainer from using it for all their changes, it
+will have to be renamed if the Debian and upstream maintainers become
+different people.</footnote>.
+<p>
+
+It has a special format which allows the package building tools to
+discover which version of the package is being built and find out
+other release-specific information.
+<p>
+
+That format is a series of entries like this:
+<p>
+<example>
+<var/package/ (<var/version/) <var/distribution(s)/; urgency=<var/urgency/
+
+ * <var/change details/
+ <var/more change details/
+ * <var/even more change details/
+
+ -- <var/maintainer name and email address/ <var/date/
+</example>
+<p>
+
+<var/package/ and <var/version/ are the source package name and
+version number.
+<p>
+<var/distribution(s)/ lists the distributions where
+this version should be installed when it is uploaded - it is copied to
+the <tt/Distribution/ field in the <tt/.changes/ file. See <ref
+id="f-Distribution">.
+<p>
+
+<var/urgency/ is the value for the <tt/Urgency/ field in the
+<tt/.changes/ file for the upload. See <ref id="f-Urgency">. It is
+not possible to specify an urgency containing commas; commas are used
+to separate <tt/<var/keyword/=<var/value// settings in the <prgn/dpkg/
+changelog format (though there is currently only one useful
+<var/keyword/, <tt/urgency/).
+<p>
+
+The change details may in fact be any series of lines starting with at
+least two spaces, but conventionally each change starts with an
+asterisk and a separating space and continuation lines are indented so
+as to bring them in line with the start of the text above. Blank
+lines may be used here to separate groups of changes, if desired.
+<p>
+
+The maintainer name and email address should <em/not/ necessarily be
+those of the usual package maintainer. They should be the details of
+the person doing <em/this/ version. The information here will be
+copied to the <tt/.changes/ file, and then later used to send an
+acknowledgement when the upload has been installed.
+<p>
+
+The <var/date/ should be in RFC822 format<footnote>This is generated
+by the <prgn/822-date/ program.</footnote>; it should include the
+timezone specified numerically, with the timezone name or abbreviation
+optionally present as a comment.
+<p>
+
+The first `title' line with the package name should start at the left
+hand margin; the `trailer' line with the maintainer and date details
+should be preceded by exactly one space. The maintainer details and
+the date must be separated by exactly two spaces.
+<p>
+
+An Emacs mode for editing this format is available: it is called
+<tt/debian-changelog-mode/. You can have this mode selected
+automatically when you edit a Debian changelog by adding a local
+variables clause to the end of the changelog.
+
+<sect2>Defining alternative changelog formats
+<p>
+
+It is possible to use a different format to the standard one, by
+providing a parser for the format you wish to use.
+<p>
+
+In order to have <tt/dpkg-parsechangelog/ run your parser, you must
+include a line within the last 40 lines of your file matching the Perl
+regular expression:
+<tt>\schangelog-format:\s+([0-9a-z]+)\W</tt>
+The part in parentheses should be the name of the format. For
+example, you might say:
+<example>
+@@@ changelog-format: joebloggs @@@
+</example>
+Changelog format names are non-empty strings of alphanumerics.
+<p>
+
+If such a line exists then <tt/dpkg-parsechangelog/ will look for the
+parser as <tt>/usr/lib/dpkg/parsechangelog/<var/format-name/</> or
+<tt>/usr/local/lib/dpkg/parsechangelog/<var/format-name/</>; it is an
+error for it not to find it, or for it not to be an executable
+program. The default changelog format is <tt/dpkg/, and a parser for
+it is provided with the <tt/dpkg/ package.
+<p>
+
+The parser will be invoked with the changelog open on standard input
+at the start of the file. It should read the file (it may seek if it
+wishes) to determine the information required and return the parsed
+information to standard output in the form of a series of control
+fields in the standard format. By default it should return
+information about only the most recent version in the changelog; it
+should accept a <tt/-v<var/version// option to return changes
+information from all versions present <em/strictly after/
+<var/version/, and it should then be an error for <var/version/ not to
+be present in the changelog.
+<p>
+
+The fields are:
+<list compact>
+<item><qref id="f-Source"><tt/Source/</>
+<item><qref id="versions"><tt/Version/</> (mandatory)
+<item><qref id="f-Distribution"><tt/Distribution/</> (mandatory)
+<item><qref id="f-Urgency"><tt/Urgency/</> (mandatory)
+<item><qref id="f-Maintainer"><tt/Maintainer/</> (mandatory)
+<item><qref id="f-Date"><tt/Date/</>
+<item><qref id="f-Changes"><tt/Changes/</> (mandatory)
+</list>
+<p>
+
+If several versions are being returned (due to the use of <tt/-v/),
+the urgency value should be of the highest urgency code listed at the
+start of any of the versions requested followed by the concatenated
+(space-separated) comments from all the versions requested; the
+maintainer, version, distribution and date should always be from the
+most recent version.
+<p>
+
+For the format of the <tt/Changes/ field see <ref id="f-Changes">.
+<p>
+
+If the changelog format which is being parsed always or almost always
+leaves a blank line between individual change notes these blank lines
+should be stripped out, so as to make the resulting output compact.
+<p>
+
+If the changelog format does not contain date or package name
+information this information should be omitted from the output. The
+parser should not attempt to synthesise it or find it from other
+sources.
+<p>
+
+If the changelog does not have the expected format the parser should
+exit with a nonzero exit status, rather than trying to muddle through
+and possibly generating incorrect output.
+<p>
+
+A changelog parser may not interact with the user at all.
+
+<sect1 id="srcsubstvars"><tt>debian/substvars</> and variable substitutions
+<p>
+
+When <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ and
+<prgn/dpkg-source/ generate control files they do variable
+substitutions on their output just before writing it. Variable
+substitutions have the form <tt/${<var/variable-name/}/. The optional
+file <tt>debian/substvars</> contains variable substitutions to be
+used; variables can also be set directly from <tt>debian/rules</>
+using the <tt/-V/ option to the source packaging commands, and certain
+predefined variables are available.
+<p>
+
+The is usually generated and modified dynamically by
+<tt>debian/rules</> targets; in this case it must be removed by the
+<prgn/clean/ target.
+<p>
+
+
+
+See <manref name=dpkg-source section=1> for full details about source
+variable substitutions, including the format of
+<tt>debian/substvars</>.
+
+<sect1><tt>debian/files</>
+<p>
+
+This file is not a permanent part of the source tree; it is used while
+building packages to record which files are being generated.
+<prgn/dpkg-genchanges/ uses it when it generates a <tt/.changes/ file.
+<p>
+
+It should not exist in a shipped source package, and so it (and any
+backup files or temporary files such as
+<tt/files.new/<footnote><tt/files.new/ is used as a temporary file by
+<prgn/dpkg-gencontrol/ and <prgn/dpkg-distaddfile/ - they write a new
+version of <tt/files/ here before renaming it, to avoid leaving a
+corrupted copy if an error occurs</footnote>) should be removed by the
+<prgn/clean/ target. It may also be wise to ensure a fresh start by
+emptying or removing it at the start of the <prgn/binary/ target.
+<p>
+
+<prgn/dpkg-gencontrol/ adds an entry to this file for the <tt/.deb/
+file that will be created by <prgn/dpkg-deb/ from the control file
+that it generates, so for most packages all that needs to be done with
+this file is to delete it in <prgn/clean/.
+<p>
+
+If a package upload includes files besides the source package and any
+binary packages whose control files were made with
+<prgn/dpkg-gencontrol/ then they should be placed in the parent of the
+package's top-level directory and <prgn/dpkg-distaddfile/ should be
+called to add the file to the list in <tt>debian/files</>.
+
+<sect1><tt>debian/tmp</>
+<p>
+
+This is the canonical temporary location for the construction of
+binary packages by the <prgn/binary/ target. The directory <tt/tmp/
+serves as the root of the filesystem 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/ subdirectory. See <ref id="bincreating">.
+<p>
+
+If several binary packages are generated from the same source tree it
+is usual to use several <tt>debian/tmp<var/something/</> directories,
+for example <tt/tmp-a/ or <tt/tmp-doc/.
+<p>
+
+Whatever <tt>tmp</> directories are created and used by <prgn/binary/
+must of course be removed by the <prgn/clean/ target.
+
+
+<sect id="sourcearchives">Source packages as archives
+<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>
+
+<taglist>
+<tag/Debian source control file - <tt/.dsc//
+<item>
+
+This file contains a series of fields, identified and separated just
+like the fields in the control file of a binary package. The fields
+are listed below; their syntax is described above, in
+<ref id="controlfields">.
+<list compact>
+<item><qref id="f-Source"><tt/Source/</>
+<item><qref id="versions"><tt/Version/</>
+<item><qref id="f-Maintainer"><tt/Maintainer/</>
+<item><qref id="f-Binary"><tt/Binary/</>
+<item><qref id="f-Architecture"><tt/Architecture/</>
+<item><qref id="f-Standards-Version"><tt/Standards-Version/</>
+<item><qref id="f-Files"><tt/Files/</>
+</list>
+<p>
+
+The source package control file is generated by <prgn/dpkg-source/
+when it builds the source archive, from other files in the source
+package, described above. When unpacking it is checked against the
+files and directories in the other parts of the source package, as
+described below.
+
+<tag/Original source archive - <tt/<var/package/_<var/upstream-version/.orig.tar.gz//
+<item>
+
+This is a compressed (with <tt/gzip -9/) <prgn/tar/ file containing
+the source code from the upstream authors of the program. The tarfile
+unpacks into a directory
+<tt/<var/package/-<var/upstream-version/.orig/, and does not contain
+files anywhere other than in there or in its subdirectories.
+
+<tag/Debianisation diff - <tt/<var/package/_<var/upstream_version-revision/.diff.gz//
+<item>
+
+This is a unified context diff (<tt/diff -u/) 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>
+
+All the directories in the diff must exist, except the <tt/debian/
+subdirectory of the top of the source tree, which will be created by
+<prgn/dpkg-source/ if necessary when unpacking.
+<p>
+
+The <prgn/dpkg-source/ program will automatically make the
+<tt>debian/rules</tt> file executable (see below).
+
+</taglist>
+<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
+<tt/<var/package/_<var/version/.tar.gz</> and contains a directory
+<tt/<var/package/-<var/version/</>.
+
+<sect>Unpacking a Debian source package without <prgn/dpkg-source/
+<p>
+
+<tt/dpkg-source -x/ 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>
+<item>Untar the tarfile, which will create a <tt/.orig/ directory.
+<item>Rename the <tt/.orig/ directory to
+<tt/<var/package/-<var/version//.
+<item>Create the subdirectory <tt/debian/ at the top of the source
+tree.
+<item>Apply the diff using <tt/patch -p0/.
+<item>Untar the tarfile again if you want a copy of the original
+source code alongside the Debianised version.
+</enumlist>
+<p>
+
+It is not possible to generate a valid Debian source archive without
+using <prgn/dpkg-source/. In particular, attempting to use
+<prgn/diff/ directly to generate the <tt/.diff.gz/ file will not work.
+
+<sect1>Restrictions on objects in source packages
+<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>
+
+The source packaging tools manage the changes between the original and
+Debianised source using <prgn/diff/ and <prgn/patch/. Turning the
+original source tree as included in the <tt/.orig.tar.gz/ into the
+debianised source must not involve any changes which cannot be handled
+by these tools. Problematic changes which cause <prgn/dpkg-source/ to
+halt with an error when building the source package are:
+<list compact>
+<item>Adding or removing symbolic links, sockets or pipes.
+<item>Changing the targets of symbolic links.
+<item>Creating directories, other than <tt/debian/.
+<item>Changes to the contents of binary files.
+</list>
+Changes which cause <prgn/dpkg-source/ to print a warning but continue
+anyway are:
+<list compact>
+<item>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>
+<item>Changed text files which are missing the usual final newline
+(either in the original or the modified source tree).
+</list>
+Changes which are not represented, but which are not detected by
+<prgn/dpkg-source/, are:
+<list compact>
+<item>Changing the permissions of files (other than
+<tt>debian/rules</>) and directories.
+</list>
+<p>
+
+The <tt/debian/ directory and <tt>debian/rules</> are handled
+specially by <prgn/dpkg-source/ - before applying the changes it will
+create the <tt/debian/ directory, and afterwards it will make
+<tt>debian/rules</> world-exectuable.
+
+<chapt id="controlfields">Control files and their fields
+<p>
+
+Many of the tools in the <prgn/dpkg/ suite manipulate data in a common
+format, known as control files. Binary and source packages have
+control data as do the <tt/.changes/ files which control the
+installation of uploaded files, and <prgn/dpkg/'s internal databases
+are in a similar format.
+
+<sect>Syntax of control files
+<p>
+
+A file consists of one or more paragraphs of fields. The paragraphs
+are separated by blank lines. Some control files only allow one
+paragraph; others allow several, in which case each paragraph often
+refers to a different package.
+<p>
+
+Each paragraph is a series of fields and values; each field consists
+of a name, followed by a colon and the value. It ends at the end of
+the line. Horizontal whitespace (spaces and tabs) may occur before or
+after the value and is ignored there; it is conventional to put a
+single space after the colon.
+<p>
+
+Some fields' values may span several lines; in this case each
+continuation line <em/must/ start with a space or tab. Any trailing
+spaces or tabs at the end of individual lines of a field value are
+ignored.
+<p>
+
+Except where otherwise stated only a single line of data is allowed
+and whitespace is not significant in a field body. Whitespace may
+never appear inside names (of packages, architectures, files or
+anything else), version numbers or in between the characters of
+multi-character version relationships.
+<p>
+
+Field names are not case-sensitive, but it is usual to capitalise the
+fields using mixed case as shown below.
+<p>
+
+Blank lines, or lines consisting only of spaces and tabs, are not
+allowed within field values or between fields - that would mean a new
+paragraph.
+<p>
+
+It is important to note that there are several fields which are
+optional as far as <prgn/dpkg/ and the related tools are concerned,
+but which must appear in every Debian package, or whose omission may
+cause problems. When writing the control files for Debian packages
+you <em/must/ read the Debian policy manual in conjuction with the
+details below and the list of fields for the particular file.
+
+<sect>List of fields
+
+<sect1 id="f-Package"><tt/Package/
+<p>
+
+The name of the binary package. Package names consist of the
+alphanumerics and <tt/+/ <tt/-/ <tt/./ (plus, minus and full
+stop).<footnote>The characters <tt/@/ <tt/:/ <tt/=/ <tt/%/ <tt/_/ (at,
+colon, equals, percent and underscore) used to be legal and are still
+accepted when found in a package file, but may not be used in new
+packages</footnote>
+<p>
+
+They must be at least two characters and must start with an
+alphanumeric. In current versions of dpkg they are sort of
+case-sensitive<footnote>This is a bug.</footnote>; use lowercase
+package names unless the package you're building (or referring to, in
+other fields) is already using uppercase.
+
+<sect1 id="f-Version"><tt/Version/
+<p>
+
+This lists the source or binary package's version number - see <ref
+id="versions">.
+
+<sect1 id="f-Architecture"><tt/Architecture/
+<p>
+
+This is the architecture string; it is a single word for the CPU
+architecture.
+<p>
+
+<prgn/dpkg/ will check the declared architecture of a binary package
+against its own compiled-in value before it installs it.
+<p>
+
+The special value <tt/all/ indicates that the package is
+architecture-independent.
+<p>
+
+In the main <tt>debian/control</> file in the source package, or in
+the source package control file <tt/.dsc/, a list of architectures
+(separated by spaces) is also allowed, as is the special value
+<tt/any/. A list indicates that the source will build an
+architecture-dependent package, and will only work correctly on the
+listed architectures. <tt/any/ indicates that though the source
+package isn't dependent on any particular architecture and should
+compile fine on any one, the binary package(s) produced are not
+architecture-independent but will instead be specific to whatever the
+current build architecture is.
+<p>
+
+In a <tt/.changes/ file the <tt/Architecture/ field lists the
+architecture(s) of the package(s) currently being uploaded. This will
+be a list; if the source for the package is being uploaded too the
+special entry <tt/source/ is also present.
+<p>
+
+The current build architecture can be determined using <tt/dpkg
+--print-architecture/.<footnote>This actually invokes
+<example>
+gcc --print-libgcc-file-name
+</example>
+and parses and decomposes the output and looks the CPU type from the
+GCC configuration in a table in <prgn/dpkg/. This is so that it will
+work if you're cross-compiling.
+</footnote>
+This value is automatically used by <prgn/dpkg-gencontrol/ when
+building the control file for a binary package for which the source
+control information doesn't specify architecture <tt/all/.
+<p>
+
+There is a separate option, <tt/--print-installation-architecture/,
+for finding out what architecture <prgn/dpkg/ is willing to install.
+This information is also in the output of <tt/dpkg --version/.
+
+<sect1 id="f-Maintainer"><tt/Maintainer/
+<p>
+
+The package maintainer's name and email address. The name should come
+first, then the email address inside angle brackets <tt/<>/ (in
+RFC822 format).
+<p>
+
+If the maintainer's name contains a full stop then the whole field
+will not work directly as an email address due to a misfeature in the
+syntax specified in RFC822; a program using this field as an address
+must check for this and correct the problem if necessary (for example
+by putting the name in round brackets and moving it to the end, and
+bringing the email address forward).
+<p>
+
+In a <tt/.changes/ file or parsed changelog data this contains the
+name and email address of the person responsible for the particular
+version in question - this may not be the package's usual maintainer.
+<p>
+
+This field is usually optional in as far as the <prgn/dpkg/ are
+concerned, but its absence when building packages usually generates a
+warning.
+
+<sect1 id="f-Source"><tt/Source/
+<p>
+
+This field identifies the source package name.
+<p>
+
+In a main source control information or a <tt/.changes/ or <tt/.dsc/
+file or parsed changelog data this may contain only the name of the
+source package.
+<p>
+
+In the control file of a binary package (or in a <tt/Packages/ file)
+it may be followed by a version number in parentheses.<footnote>It is
+usual to leave a space after the package name if a version number is
+specified.</footnote> This version number may be omitted (and is, by
+<prgn/dpkg-gencontrol/) if it has the same value as the <tt/Version/
+field of the binary package in question. The field itself may be
+omitted from a binary package control file when the source package has
+the same name and version as the binary package.
+
+<sect1>Package interrelationship fields:
+<tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/
+<tt/Suggests/, <tt/Conflicts/, <tt/Provides/, <tt/Replaces/
+<p>
+
+These fields describe the package's relationships with other packages.
+Their syntax and semantics are described in <ref id="relationships">.
+
+<sect1 id="f-Description"><tt/Description/
+<p>
+
+In a binary package <tt/Packages/ file or main source control file
+this field contains a description of the binary package, in a special
+format. See <ref id="descriptions"> for details.
+<p>
+
+In a <tt/.changes/ file it contains a summary of the descriptions for
+the packages being uploaded. The part of the field before the first
+newline is empty; thereafter each line has the name of a binary
+package and the summary description line from that binary package.
+Each line is indented by one space.
+
+<sect1 id="f-Essential"><tt/Essential/
+<p>
+
+This is a boolean field which may occur only in the control file of a
+binary package (or in the <tt/Packages/ file) or in a per-package
+fields paragraph of a main source control data file.
+<p>
+
+If set to <tt/yes/ then <prgn/dpkg/ and <prgn/dselect/ will refuse to
+remove the package (though it can be upgraded and/or replaced). The
+other possible value is <tt/no/, which is the same as not having the
+field at all.
+
+<sect1 id="f-classification"><tt/Section/ and <tt/Priority/
+<p>
+
+These two fields classify the package. The <tt/Priority/ represents
+how important that it is that the user have it installed; the
+<tt/Section/ represents an application area into which the package has
+been classified.
+<p>
+
+When they appear in the <tt>debian/control</> file these fields give
+values for the section and priority subfields of the <tt/Files/ field
+of the <tt/.changes/ file, and give defaults for the section and
+priority of the binary packages.
+<p>
+
+The section and priority are represented, though not as separate
+fields, in the information for each file in the <qref
+id="f-Files"><tt/Files/</> field of a <tt/.changes/ file. The
+section value in a <tt/.changes/ file is used to decide where to
+install a package in the FTP archive.
+<p>
+
+These fields are not used by by <prgn/dpkg/ proper, but by
+<prgn/dselect/ when it sorts packages and selects defaults. See the
+Debian policy manual for the priorities in use and the criteria for
+selecting the priority for a Debian package, and look at the Debian
+FTP archive for a list of currently in-use priorities.
+<p>
+
+These fields may appear in binary package control files, in which case
+they provide a default value in case the <tt/Packages/ files are
+missing the information. <prgn/dpkg/ and <prgn/dselect/ will only use
+the value from a <tt/.deb/ file if they have no other information; a
+value listed in a <tt/Packages/ file will always take precedence. By
+default <prgn/dpkg-genchanges/ does not include the section and
+priority in the control file of a binary package - use the <tt/-isp/,
+<tt/-is/ or <tt/-ip/ options to achieve this effect.
+
+<sect1 id="f-Binary"><tt/Binary/
+<p>
+
+This field is a list of binary packages.
+<p>
+
+When it appears in the <tt/.dsc/ file it is the list of binary
+packages which a source package can produce. It does not necessarily
+produce all of these binary packages for every architecture. The
+source control file doesn't contain details of which architectures are
+appropriate for which of the binary packages.
+<p>
+
+When it appears in a <tt/.changes/ file it lists the names of the
+binary packages actually being uploaded.
+<p>
+
+The syntax is a list of binary packages separated by
+commas.<footnote>A space after each comma is conventional.</footnote>
+Currently the packages must be separated using only spaces in the
+<tt/.changes/ file.
+
+<sect1 id="f-Installed-Size"><tt/Installed-Size/
+<p>
+
+This field appears in the control files of binary packages, and in the
+<tt/Packages/ files. It gives the total amount of disk space
+required to install the named package.
+<p>
+
+The disk space is represented in kilobytes as a simple decimal number.
+
+<sect1 id="f-Files"><tt/Files/
+<p>
+
+This field contains a list of files with information about each one.
+The exact information and syntax varies with the context. In all
+cases the the part of the field contents on the same line as the field
+name is empty. The remainder of the field is one line per file, each
+line being indented by one space and containing a number of sub-fields
+separated by spaces.
+<p>
+
+In the <tt/.dsc/ (Debian source control) file each line contains the
+MD5 checksum, size and filename of the tarfile and (if applicable)
+diff file which make up the remainder of the source
+package.<footnote>That is, the parts which are not the
+<tt/.dsc/.</footnote> The exact forms of the filenames are described
+in <ref id="sourcearchives">.
+<p>
+
+In the <tt/.changes/ file this contains one line per file being
+uploaded. Each line contains the MD5 checksum, size, section and
+priority and the filename. The section and priority are the values of
+the corresponding fields in the main source control file - see <ref
+id="f-classification">. If no section or priority is specified then
+<tt/-/ should be used, though section and priority values must be
+specified for new packages to be installed properly.
+<p>
+
+The special value <tt/byhand/ for the section in a <tt/.changes/ file
+indicates that the file in question is not an ordinary package file
+and must by installed by hand by the distribution maintainers. If the
+section is <tt/byhand/ the priority should be <tt/-/.
+<p>
+
+If a new Debian revision of a package is being shipped and no new
+original source archive is being distributed the <tt/.dsc/ must still
+contain the <tt/Files/ field entry for the original source archive
+<tt/<var/package/-<var/upstream-version/.orig.tar.gz/, but the
+<tt/.changes/ file should leave it out. In this case the original
+source archive on the distribution site must match exactly,
+byte-for-byte, the original source archive which was used to generate
+the <tt/.dsc/ file and diff which are being uploaded.
+
+
+<sect1 id="f-Standards-Version"><tt/Standards-Version/
+<p>
+
+The most recent version of the standards (the <prgn/dpkg/ programmers'
+and policy manuals and associated texts) with which the package
+complies. This is updated manually when editing the source package to
+conform to newer standards; it can sometimes be used to tell when a
+package needs attention.
+<p>
+
+Its format is the same as that of a version number except that no
+epoch or Debian revision is allowed - see <ref id="versions">.
+
+
+<sect1 id="f-Distribution"><tt/Distribution/
+<p>
+
+In a <tt/.changes/ file or parsed changelog output this contains the
+(space-separated) name(s) of the distribution(s) where this version of
+the package should be or was installed. Distribution names follow the
+rules for package names. (See <ref id="f-Package">).
+<p>
+
+Current distribution values are:
+<taglist>
+<tag/<em/stable//
+<item>
+This is the current `released' version of Debian GNU/Linux. A new
+version is released approximately every 3 months after the
+<em/development/ code has been <em/frozen/ for a month of testing.
+Once the distribution is <em/stable/ only major bug fixes are
+allowed. When changes are made to this distribution, the minor version
+number is increased (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).
+
+<tag/<em/unstable//
+<item>
+This distribution value refers to the <em/developmental/ part of the Debian
+distribution tree. New packages, new upstream versions of packages and
+bug fixes go into the <em/unstable/ directory tree. Download
+from this distribution at your own risk.
+
+<tag/<em/contrib//
+<item>
+The packages with this distribution value do not meet the criteria for
+inclusion in the main Debian distribution as defined by the Policy
+Manual, but meet the criteria for the <em/contrib/ Distribution. There
+is currently no distinction between stable and unstable packages in
+the <em/contrib/ or <em/non-free/ distributions. Use your best
+judgement in downloading from this Distribution.
+
+<tag/<em/non-free//
+<item>
+Like the packages in the <em/contrib/ seciton, the packages in
+<em/non-free/ do not meet the criteria for inclusion in the main
+Debian distribution as defined by the Policy Manual. Again, use your
+best judgement in downloading from this Distribution.
+
+<tag/<em/experimental//
+<item>
+The packages with this distribution value are deemed by their
+maintainers to be high risk. Oftentimes they represent early beta or
+developmental packages from various sources that the maintainers want
+people to try, but are not ready to be a part of the other parts of
+the Debian distribution tree. Download at your own risk.
+
+<tag/<em/frozen//
+<item>
+From time to time, (currently, every 3 months) the <em/unstable/
+distribution enters a state of `code-freeze' in anticipation of
+release as a <em/stable/ version. During this period of testing
+(usually 4 weeks) only fixes for existing or newly-discovered bugs
+will be allowed.
+
+</taglist>
+<p>
+You should list <em/all/ distributions that the package should be
+installed into. Except in unusual circumstances, installations to
+<em/stable/ should also go into <em/frozen/ (if it exists) and
+<em/unstable/. Likewise, installations into <em/frozen/ should also go
+into <em/unstable/.
+
+<sect1 id="f-Urgency"><tt/Urgency/
+<p>
+
+This is a description of how important it is to upgrade to this
+version from previous ones. It consists of a single keyword usually
+taking one of the values <tt/LOW/, <tt/MEDIUM/ or <tt/HIGH/) followed
+by an optional commentary (separated by a space) which is usually in
+parentheses. For example:
+<example>
+Urgency: LOW (HIGH for diversions users)
+</example>
+<p>
+
+This field appears in the <tt/.changes/ file and in parsed changelogs;
+its value appears as the value of the <tt/urgency/ attribute in a
+<prgn/dpkg/-style changelog (see <ref id="dpkgchangelog">).
+<p>
+
+Urgency keywords are not case-sensitive.
+
+<sect1 id="f-Date"><tt/Date/
+<p>
+
+In <tt/.changes/ files and parsed changelogs, this gives the date the
+package was built or last edited.
+
+<sect1 id="f-Format"><tt/Format/
+<p>
+
+This field occurs in <tt/.changes/ files, and specifies a format
+revision for the file. The format described here is version <tt/1.5/.
+The syntax of the format value is the same as that of a package
+version number except that no epoch or Debian revision is allowed -
+see <ref id="versions">.
+
+<sect1 id="f-Changes"><tt/Changes/
+<p>
+
+In a <tt/.changes/ file or parsed changelog this field contains the
+human-readable changes data, describing the differences between the
+last version and the current one.
+<p>
+
+There should be nothing in this field before the first newline; all
+the subsequent lines must be indented by at least one space; blank
+lines must be represented by a line consiting only of a space and a
+full stop.
+<p>
+
+Each version's change information should be preceded by a `title' line
+giving at least the version, distribution(s) and urgency, in a
+human-readable way.
+<p>
+
+If data from several versions is being returned the entry for the most
+recent version should be returned first, and entries should be
+separated by the representation of a blank line (the `title' line may
+also be followed by the representation of blank line).
+
+<sect1 id="f-Filename"><tt/Filename/ and <tt/MSDOS-Filename/
+<p>
+
+These fields in <tt/Packages/ 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.
+
+<sect1 id="f-Size"><tt/Size/ and <tt/MD5sum/
+<p>
+
+These fields in <tt/Packages/ 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.
+
+<sect1 id="f-Status"><tt/Status/
+<p>
+
+This field in <prgn/dpkg/'s status file records whether the user wants a
+package installed, removed or left alone, whether it is broken
+(requiring reinstallation) or not and what its current state on the
+system is. Each of these pieces of information is a single word.
+
+<sect1 id="f-Config-Version"><tt/Config-Version/
+<p>
+
+If a package is not installed or not configured, this field in
+<prgn/dpkg/'s status file records the last version of the package which
+was successfully configured.
+
+<sect1 id="f-Conffiles"><tt/Conffiles/
+<p>
+
+This field in <prgn/dpkg/'s status file contains information about the
+automatically-managed configuration files held by a package. This
+field should <em/not/ appear anywhere in a package!
+
+<sect1>Obsolete fields
+<p>
+
+These are still recognised by <prgn/dpkg/ but should not appear anywhere
+any more.
+
+<taglist compact>
+
+<tag><tt/Revision/
+<tag><tt/Package-Revision/
+<tag><tt/Package_Revision/
+<item>
+The Debian revision part of the package version was at one point in a
+separate control file field. This field went through several names.
+
+<tag><tt/Recommended/
+<item>Old name for <tt/Recommends/
+
+<tag><tt/Optional/
+<item>Old name for <tt/Suggests/.
+
+<tag><tt/Class/
+<item>Old name for <tt/Priority/.
+
+</taglist>
+
+<chapt id="versions">Version numbering
+<p>
+
+Every package has a version number, in its <tt/Version/ control file
+field.
+<p>
+
+<prgn/dpkg/ imposes an ordering on version numbers, so that it can tell
+whether packages are being up- or downgraded and so that <prgn/dselect/
+can tell whether a package it finds available is newer than the one
+installed on the system. The version number format has the most
+significant parts (as far as comparison is concerned) at the
+beginning.
+<p>
+
+The version number format is:
+&lsqb<var/epoch/<tt/:/]<var/upstream-version/[<tt/-/<var/debian-revision/].
+<p>
+
+The three components here are:
+
+<taglist>
+
+<tag><var/epoch/
+<item>
+
+This is a single unsigned integer, which should usually be small. It
+may be omitted, in which case zero is assumed. If it is omitted then
+the <var/upstream-version/ may not contain any colons.
+<p>
+
+It is provided to allow mistakes in the version numbers of older
+versions of a package, and also a package's previous version numbering
+schemes, to be left behind.
+<p>
+
+<prgn/dpkg/ will not usually display the epoch unless it is essential
+(non-zero, or if the <var/upstream-version/ contains a colon);
+<prgn/dselect/ does not display epochs at all in the main part of the
+package selection display.
+
+<tag><var/upstream-version/
+<item>
+
+This is the main part of the version. It is usually version number of
+the original (`upstream') package of which the <tt/.deb/ file has been
+made, if this is applicable. Usually this will be in the same format
+as that specified by the upstream author(s); however, it may need to
+be reformatted to fit into <prgn/dpkg/'s format and comparison scheme.
+<p>
+
+The comparison behaviour of <prgn/dpkg/ with respect to the
+<var/upstream-version/ is described below. The <var/upstream-version/
+portion of the version number is mandatory.
+<p>
+
+The <var/upstream-version/ may contain only alphanumerics and the
+characters <tt/+/ <tt/./ <tt/-/ <tt/:/ (full stop, plus, hyphen,
+colon) and should start with a digit. If there is no
+<var/debian-revision/ then hyphens are not allowed; if there is no
+<var/epoch/ then colons are not allowed.
+
+<tag><var/debian-revision/
+<item>
+
+This part of the version represents the version of the modifications
+that were made to the package to make it a Debian binary package. It
+is in the same format as the <var/upstream-version/ and <prgn/dpkg/
+compares it in the same way.
+<p>
+
+It is optional; if it isn't present then the <var/upstream-version/
+may not contain a hyphen. This format represents the case where a
+piece of software was written specifically to be turned into a Debian
+binary package, and so there is only one `debianization' of it and
+therefore no revision indication is required.
+<p>
+
+It is conventional to restart the <var/debian-revision/ at <tt/1/ each
+time the <var/upstream-version/ is increased.
+<p>
+
+<prgn/dpkg/ will break the <var/upstream-version/ and
+<var/debian-revision/ apart at the last hyphen in the string. The
+absence of a <var/debian-revision/ compares earlier than the presence
+of one (but note that the <var/debian-revision/ is the least
+significant part of the version number).
+<p>
+
+The <var/debian-revision/ may contain only alphanumerics and the
+characters <tt/+/ and <tt/./ (plus and full stop).
+
+</taglist>
+
+The <var/upstream-version/ and <var/debian-revision/ parts are
+compared by <prgn/dpkg/ using the same algorithm:
+<p>
+
+The strings are compared from left to right.
+<p>
+
+First the initial part of each string consisting entirely of non-digit
+characters is determined. These two parts (one of which may be empty)
+are compared lexically. If a difference is found it is returned. The
+lexical comparison is a comparison of ASCII values modified so that
+all the letters sort earlier than all the non-letters.
+<p>
+
+Then the initial part of the remainder of each string which consists
+entirely of digit characters is determined. The numerical values of
+these two parts are compared, and any difference found is returned as
+the result of the comparison. For these purposes an empty string
+(which can only occur at the end of one or both version strings being
+compared) counts as zero.
+<p>
+
+These two steps are repeated (chopping initial non-digit strings and
+initial digit strings off from the start) until a difference is found
+or both strings are exhausted.
+<p>
+
+Note that the purpose of epochs is to allow us to leave behind
+mistakes in version numbering, and to cope with situations where the
+version numbering changes. It is <em/not/ there to cope with version
+numbers containing strings of letters which <prgn/dpkg/ cannot interpret
+(such as <tt/ALPHA/ or <tt/pre-/), or with silly orderings (the author
+of this manual has heard of a package whose versions went <tt/1.1/,
+<tt/1.2/, <tt/1.3/, <tt/1/, <tt/2.1/, <tt/2.2/, <tt/2/ and so forth).
+<p>
+
+If an upstream package has problematic version numbers they should be
+converted to a sane form for use in the <tt/Version/ field.
+<p>
+
+If you need to compare version numbers ina script, you may use
+<tt>dpkg --compare-versions ...</>. Type <tt>dpkg --help</> -->
+--for details on arguments.
+
+<chapt id="maintainerscripts">Package maintainer scripts
+and installation procedure
+<sect>Introduction to package maintainer scripts
+<p>
+
+It is possible supply scripts as part of a package which <prgn/dpkg/
+will run for you when your package is installed, upgraded or removed.
+<p>
+
+These scripts should be the files <tt/preinst/, <tt/postinst/,
+<tt/prerm/ and <tt/postrm/ in the control area of the package. They
+must be proper exectuable files; if they are scripts (which is
+recommended) they must start with the usual <tt/#!/ convention. They
+should be readable and executable to anyone, and not world-writeable.
+<p>
+
+<prgn/dpkg/ looks at the exit status from these scripts. It is
+important that they exit with a non-zero status if there is an error,
+so that <prgn/dpkg/ can stop its processing. For shell scripts this
+means that you <em/almost always/ need to use <tt/set -e/ (this is
+usually true when writing shell scripts, in fact). It is also
+important, of course, that they don't exit with a non-zero status if
+everything went well.
+<p>
+
+It is necessary for the error recovery procedures that the scripts be
+idempotent: ie, invoking the same script several times in the same
+situation should do no harm. If the first call failed, or aborted
+half way through for some reason, the second call should merely do the
+things that were left undone the first time, if any, and exit with a
+success status.
+<p>
+
+When a package is upgraded a combination of the scripts from the old
+and new packages is called in amongst the other steps of the upgrade
+procedure. If your scripts are going to be at all complicated you
+need to be aware of this, and may need to check the arguments to your
+scripts.
+<p>
+
+Broadly speaking the <prgn/preinst/ is called before (a particular
+version of) a package is installed, and the <prgn/postinst/ afterwards;
+the <prgn/prerm/ before (a version of) a package is removed and the
+<prgn/postrm/ afterwards.
+<p>
+<!--
+ next paragraph by Guy Maor to close bug #2481
+ -->
+
+Programs called from maintainer scripts should not normally have a
+path prepended to them. Before installation is started <prgn/dpkg/
+checks to see if the programs <prgn/ldconfig/,
+<prgn/start-stop-daemon/, <prgn/install-info/, and <prgn/update-rc.d/
+can be found via the <tt/PATH/ environment variable. Those programs,
+and any other program that one would expect to on the <tt/PATH/,
+should thus be invoked without an absolute pathname. Maintainer
+scripts should also not reset the <tt/PATH/, though they might choose
+to modify it by pre- or appending package-specific directories. These
+considerations really apply to all shell scripts.
+
+<sect id="mscriptsinstact">Summary of ways maintainer scripts are called
+<p>
+
+<list compact>
+<item><var/new-preinst/ <tt/install/
+<item><var/new-preinst/ <tt/install/ <var/old-version/
+<item><var/new-preinst/ <tt/upgrade/ <var/old-version/
+<item><var/old-preinst/ <tt/abort-upgrade/ <var/new-version/
+</list>
+<p>
+
+<list compact>
+<item><var/postinst/ <tt/configure/ <var/most-recently-configured-version/
+<item><var/old-postinst/ <tt/abort-upgrade/ <var/new version/
+<item><var/conflictor's-postinst/ <tt/abort-remove/
+ <tt/in-favour/ <var/package/ <var/new-version/
+<item><var/deconfigured's-postinst/ <tt/abort-deconfigure/
+ <tt/in-favour/ <var/failed-install-package/ <var/version/
+ <tt/removing/ <var/conflicting-package/ <var/version/
+</list>
+<p>
+
+<list compact>
+<item><var/prerm/ <tt/remove/
+<item><var/old-prerm/ <tt/upgrade/ <var/new-version/
+<item><var/new-prerm/ <tt/failed-upgrade/ <var/old-version/
+<item><var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/
+ <var/package/ <var/new-version/
+<item><var/deconfigured's-prerm/ <tt/deconfigure/
+ <tt/in-favour/ <var/package-being-installed/ <var/version/
+ <tt/removing/ <var/conflicting-package/ <var/version/
+</list>
+<p>
+
+<list compact>
+<item><var/postrm/ <tt/remove/
+<item><var/postrm/ <tt/purge/
+<item><var/old-postrm/ <tt/upgrade/ <var/new-version/
+<item><var/new-postrm/ <tt/failed-upgrade/ <var/old-version/
+<item><var/new-postrm/ <tt/abort-install/
+<item><var/new-postrm/ <tt/abort-install/ <var/old-version/
+<item><var/new-postrm/ <tt/abort-upgrade/ <var/old-version/
+<item><var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/new-version/
+</list>
+
+
+<sect id="unpackphase">Details of unpack phase of installation or upgrade
+<p>
+
+The procedure on installation/upgrade/overwrite/disappear (ie, when
+running <tt/dpkg --unpack/, or the unpack stage of <tt/dpkg
+--install/) is as follows. In each case if an error occurs the
+actions in are general run backwards - this means that the maintainer
+scripts are run with different arguments in reverse order. These are
+the `error unwind' calls listed below.
+
+<enumlist>
+<item>
+
+<enumlist>
+<item>
+If a version the package is already
+installed, call
+<example>
+<var/old-prerm/ upgrade <var/new-version/
+</example>
+
+<item>
+If this gives an error (ie, a non-zero exit status), dpkg will
+attempt instead:
+<example>
+<var/new-prerm/ failed-upgrade <var/old-version/
+</example>
+Error unwind, for both the above cases:
+<example>
+<var/old-postinst/ abort-upgrade <var/new-version/
+</example>
+
+</enumlist>
+
+<item>
+If a `conflicting' package is being removed at the same time:
+<enumlist>
+
+<item>
+If any packages depended on that conflicting package and
+<tt/--auto-deconfigure/ is specified, call, for each such package:
+<example>
+<var/deconfigured's-prerm/ deconfigure \
+ in-favour <var/package-being-installed/ <var/version/ \
+ removing <var/conflicting-package/ <var/version/
+</example>
+Error unwind:
+<example>
+<var/deconfigured's-postinst/ abort-deconfigure \
+ in-favour <var/package-being-installed-but-failed/ <var/version/ \
+ removing <var/conflicting-package/ <var/version/
+</example>
+The deconfigured packages are marked as requiring configuration, so
+that if <tt/--install/ is used they will be configured again if
+possible.
+
+<item>
+To prepare for removal of the conflicting package, call:
+<example>
+<var/conflictor's-prerm/ remove in-favour <var/package/ <var/new-version/
+</example>
+Error unwind:
+<example>
+<var/conflictor's-postinst/ abort-remove \
+ in-favour <var/package/ <var/new-version/
+</example>
+
+</enumlist>
+
+<item>
+<enumlist>
+<item>
+If the package is being upgraded, call:
+<example>
+<var/new-preinst/ upgrade <var/old-version/
+</example>
+
+<item>
+Otherwise, if the package had some configuration files from a previous
+version installed (ie, it is in the `configuration files only' state):
+<example>
+<var/new-preinst/ install <var/old-version/
+</example>
+
+<item>
+Otherwise (ie, the package was completely purged):
+<example>
+<var/new-preinst/ install
+</example>
+Error unwind versions, respectively:
+<example>
+<var/new-postrm/ abort-upgrade <var/old-version/
+<var/new-postrm/ abort-install <var/old-version/
+<var/new-postrm/ abort-install
+</example>
+
+</enumlist>
+
+<item>
+The new package's files are unpacked, overwriting any that may be on
+the system already, for example any from the old version of the same
+package or from another package (backups of the old files are left
+around, and if anything goes wrong dpkg will attempt to put them back
+as part of the error unwind).
+<p>
+
+It is an error for a package to contains files which are on the system
+in another package, unless <tt/Replaces/ is used (see
+<ref id="replaces">). Currently the <tt/--force-overwrite/ flag is
+enabled, downgrading it to a warning, but this may not always be the
+case.
+<p>
+
+It is a more serious error for a package to contain a plain file or
+other kind of nondirectory where another package has a directory
+(again, unless <tt/Replaces/ is used). This error can be overridden
+if desired using <tt/--force-overwrite-dir/, but this is not advisable.
+<p>
+
+Packages which overwrite each other's files produce behaviour which
+though deterministic is hard for the system administrator to
+understand. It can easily lead to `missing' programs if, for example,
+a package is installed which overwrites a file from another package,
+and is then removed again.<footnote>Part of the problem is due to what
+is arguably a bug in <prgn/dpkg/.</footnote>
+<p>
+
+A directory will never be replaced by a symbolic links to a directory
+or vice versa; instead, the existing state (symlink or not) will be
+left alone and <prgn/dpkg/ will follow the symlink if there is one.
+
+<item>
+
+<enumlist>
+<item>
+If the package is being upgraded, call
+<example>
+<var/old-postrm/ upgrade <var/new-version/
+</example>
+
+<item>
+If this fails, <prgn/dpkg/ will attempt:
+<example>
+<var/new-postrm/ failed-upgrade <var/old-version/
+</example>
+Error unwind, for both cases:
+<example>
+<var/old-preinst/ abort-upgrade <var/new-version/
+</example>
+
+</enumlist>
+
+This is the point of no return - if <prgn/dpkg/ gets this far, it won't
+back off past this point if an error occurs. This will leave the
+package in a fairly bad state, which will require a successful
+reinstallation to clear up, but it's when <prgn/dpkg/ starts doing
+things that are irreversible.
+
+<item>
+Any files which were in the old version of the package but not in the
+new are removed.
+
+<item>
+The new file list replaces the old.
+
+<item>
+The new maintainer scripts replace the old.
+
+<item>
+Any packages all of whose files have been overwritten during the
+installation, and which aren't required for dependencies, are considered
+to have been removed. For each such package,
+
+<enumlist>
+<item>
+<prgn/dpkg/ calls:
+<example>
+<var/disappearer's-postrm/ disappear \
+ <var/overwriter/ <var/overwriter-version/
+</example>
+
+<item>
+The package's maintainer scripts are removed.
+
+<item>
+It is noted in the status database as being in a sane state, namely
+not installed (any conffiles it may have are ignored, rather than
+being removed by <prgn/dpkg/). Note that disappearing packages do not
+have their prerm called, because <prgn/dpkg/ doesn't know in advance
+that the package is going to vanish.
+
+</enumlist>
+
+<item>
+Any files in the package we're unpacking that are also listed in the
+file lists of other packages are removed from those lists. (This will
+lobotomise the file list of the `conflicting' package if there is one.)
+
+<item>
+The backup files made during installation, above, are deleted.
+
+<item>
+The new package's status is now sane, and recorded as `unpacked'. Here
+is another point of no return - if the conflicting package's removal
+fails we do not unwind the rest of the installation; the conflicting
+package is left in a half-removed limbo.
+
+<item>
+If there was a conflicting package we go and do the removal actions
+(described below), starting with the removal of the conflicting
+package's files (any that are also in the package being installed
+have already been removed from the conflicting package's file list,
+and so do not get removed now).
+
+</enumlist>
+
+<sect>Details of configuration
+<p>
+
+When we configure a package (this happens with <tt/dpkg --install/, or
+with <tt/--configure/), we first update the conffiles and then call:
+<example>
+<var/postinst/ configure <var/most-recently-configured-version/
+</example>
+<p>
+
+No attempt is made to unwind after errors during configuration.
+<p>
+
+If there is no most recently configured version <prgn/dpkg/ will pass a
+null argument; older versions of dpkg may pass
+<tt><unknown></tt> (including the angle brackets) in this case.
+Even older ones do not pass a second argument at all, under any
+circumstances.
+
+<sect>Details of removal and/or configuration purging
+<p>
+
+<enumlist>
+<item>
+<example>
+<var/prerm/ remove
+</example>
+
+<item>
+The package's files are removed (except conffiles).
+
+<item>
+<example>
+<var/postrm/ remove
+</example>
+
+<item>
+All the maintainer scripts except the postrm are removed.
+<p>
+
+If we aren't purging the package we stop here. Note that packages
+which have no postrm and no conffiles are automatically purged when
+removed, as there is no difference except for the <prgn/dpkg/ status.
+
+<item>
+The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files,
+<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed.
+
+<item>
+<example>
+<var/postrm/ purge
+</example>
+
+<item>
+The package's file list is removed.
+
+</enumlist>
+
+No attempt is made to unwind after errors during removal.
+
+
+<chapt id="descriptions">Descriptions of packages - the
+<tt/Description/ field
+<p>
+
+The <tt/Description/ control file field is used by <prgn/dselect/ when
+the user is selecting which packages to install and by <prgn/dpkg/
+when it displays information about the status of packages and so
+forth. It is included on the FTP site in the <prgn/Packages/ files,
+and may also be used by the Debian WWW pages.
+<p>
+
+The description is intended to describe the program to a user who has
+never met it before so that they know whether they want to install it.
+It should also give information about the significant dependencies and
+conflicts between this package and others, so that the user knows why
+these dependencies and conflicts have been declared.
+<p>
+
+The field's format is as follows:
+<example>
+Description: <var/single line synopsis/
+ <var/extended description over several lines/
+</example>
+<p>
+
+The synopsis is often printed in lists of packages and so forth, and
+should be as informative as possible. Every package should also have
+an extended description.
+<p>
+
+<sect>Types of formatting line in the extended description
+<p>
+
+<list>
+<item>
+Those starting with a single space are part of a paragraph.
+Successive lines of this form will be word-wrapped when displayed.
+The leading space will usually be stripped off.
+
+<item>
+Those starting with two or more spaces. These will be displayed
+verbatim. If the display cannot be panned horizontally the
+displaying program will linewrap them `hard' (ie, without taking
+account of word breaks). If it can they will be allowed to trail
+off to the right. None, one or two initial spaces may be deleted,
+but the number of spaces deleted from each line will be the same
+(so that you can have indenting work correctly, for example).
+
+<item>
+Those containing a single space followed by a single full stop
+character. These are rendered as blank lines. This is the <em/only/
+way to get a blank line - see below.
+
+<item>
+Those containing a space, a full stop and some more characters. These
+are for future expansion. Do not use them.
+</list>
+
+<sect>Notes about writing descriptions
+<p>
+
+<em/Always/ start extended description lines with at least one
+whitespace character. Fields in the control file and in the Packages
+file are separated by field names starting in the first column, just
+as message header fields are in RFC822. Forgetting the whitespace
+will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or
+later.</footnote> to produce a syntax error when trying to build the
+package. If you force it to build anyway <prgn/dpkg/ will refuse to
+install the resulting mess.
+<p>
+
+<em/Do not/ include any completely <em/empty/ lines. These separate
+different records in the Packages file and different packages in the
+<tt>debian/control</> file, and are forbidden in package control
+files. See the previous paragraph for what happens if you get this
+wrong.
+<p>
+
+The single line synopsis should be kept brief - certainly under 80
+characters. <prgn/dselect/ displays between 25 and 49 characters
+without panning if you're using an 80-column terminal, depending on
+what display options are in effect.
+<p>
+
+Do not include the package name in the synopsis line. The display
+software knows how to display this already, and you do not need to
+state it. Remember that in many situations the user may only see
+the synopsis line - make it as informative as you can.
+<p>
+
+The extended description should describe what the package does and
+how it relates to the rest of the system (in terms of, for
+example, which subsystem it is which part of).
+<p>
+
+The blurb that comes with a program in its announcements and/or
+<prgn/README/ files is rarely suitable for use in a description. It
+is usually aimed at people who are already in the community where the
+package is used. The description field needs to make sense to anyone,
+even people who have no idea about any of the
+things the package deals with.
+<p>
+
+Put important information first, both in the synopis and extended
+description. Sometimes only the first part of the synopsis or of
+the description will be displayed. You can assume that there will
+usually be a way to see the whole extended description.
+<p>
+
+You may include information about dependencies and so forth in the
+extended description, if you wish.
+<p>
+
+Do not use tab characters. Their effect is not predictable.
+<p>
+
+Do not try to linewrap the summary (the part on the same line as the
+field name <tt/Description/) into the extended description. This will
+not work correctly when the full description is displayed, and makes
+no sense where only the summary is available.
+
+<sect>Example description in control file for Smail
+<p>
+
+<example>
+Package: smail
+Version: 3.1.29.1-13
+Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk>
+Recommends: pine | mailx | elm | emacs | mail-user-agent
+Suggests: metamail
+Depends: cron, libc5
+Conflicts: sendmail
+Provides: mail-transport-agent
+Description: Electronic mail transport system.
+ Smail is the recommended mail transport agent (MTA) for Debian.
+ .
+ An MTA is the innards of the mail system - it takes messages from
+ user-friendly mailer programs and arranges for them to be delivered
+ locally or passed on to other systems as required.
+ .
+ In order to make use of it you must have one or more user level
+ mailreader programs such as elm, pine, mailx or Emacs (which has Rmail
+ and VM as mailreaders) installed. If you wish to send messages other
+ than just to other users of your system you must also have appropriate
+ networking support, in the form of IP or UUCP.
+</example>
+
+<chapt id="relationships">Declaring relationships between packages
+<p>
+
+Packages can declare in their control file that they have certain
+relationships to other packages - for example, that they may not be
+installed at the same time as certain other packages, and/or that they
+depend on the presence of others, or that they should overwrite files
+in certain other packages if present.
+<p>
+
+This is done using the <tt/Depends/, <tt/Recommends/, <tt/Suggests/,
+<tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields.
+<p>
+
+<sect id="depsyntax">Syntax of relationship fields
+<p>
+
+These fields all have a uniform syntax. They are a list of package
+names separated by commas.
+<p>
+
+In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/
+(the fields which declare dependencies of the package in which they
+occur on other packages) these package names may also be lists of
+alternative package names, separated by vertical bar symbols <tt/|/
+(pipe symbols).
+<p>
+
+All the fields except <tt/Provides/ may restrict their applicability
+to particular versions of each named package. This is done in
+parentheses after each individual package name; the parentheses should
+contain a relation from the list below followed by a version number,
+in the format described in <ref id="versions">.
+<p>
+
+The relations allowed are
+<tt/<</,
+<tt/<=/,
+<tt/=/,
+<tt/>=/ and
+<tt/>>/
+for strictly earlier, earlier or equal, exactly equal, later or equal
+and strictly later, respectively. The forms <tt/</ and <tt/>/
+were used to mean earlier/later or equal, rather than strictly
+earlier/later, so they should not appear in new packages (though
+<prgn/dpkg/ still supports them).
+<p>
+
+Whitespace may appear at any point in the version specification, and
+must appear where it's necessary to disambiguate; it is not otherwise
+significant. For consistency and in case of future changes to
+<prgn/dpkg/ it is recommended that a single space be used after a
+version relationship and before a version number; it is usual also to
+put a single space after each comma, on either side of each vertical
+bar, and before each open parenthesis.
+<p>
+
+For example:
+<example>
+Package: metamail
+Version: 2.7-3
+Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh
+</example>
+
+<sect>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/
+<p>
+
+These four fields are used to declare a dependency by one package on
+another. They appear in the depending package's control file.
+<p>
+
+All but <tt/Pre-Depends/ (discussed below) take effect <em/only/ when
+a package is to be configured. They do not prevent a package being on
+the system in an unconfigured state while its dependencies are
+unsatisfied, and it is possible to replace a package whose
+dependencies are satisfied and which is properly installed with a
+different version whose dependencies are not and cannot be satisfied;
+when this is done the depending package will be left unconfigured
+(since attempts to configure it will give errors) and will not
+function properly.
+<p>
+
+For this reason packages in an installation run are usually all
+unpacked first and all configured later; this gives later versions of
+packages with dependencies on later versions of other packages the
+opportunity to have their dependencies satisfied.
+<p>
+
+Thus <tt/Depends/ allows package maintainers to impose an order in
+which packages should be configured.
+
+<taglist>
+<tag><tt/Depends/
+<item>
+
+This declares an absolute dependency.
+<p>
+
+<prgn/dpkg/ will not configure
+packages whose dependencies aren't satisfied. If it is asked to make
+an installation which would cause an installed package's dependencies
+to become unsatisfied it will complain<footnote>Current versions
+(1.2.4) of <prgn/dpkg/ have a bug in this area which will cause some of
+these problems to be ignored.</footnote>, unless
+<tt/--auto-deconfigure/ is specified, in which case those packages
+will be deconfigured before the installation proceeds.
+<p>
+
+<prgn/dselect/ makes it hard for the user to select packages for
+installation, removal or upgrade in a way that would mean that
+packages' <prgn/Depends/ fields would be unsatisfied. The user can
+override this if they wish, for example if they know that <prgn/dselect/
+has an out-of-date view of the real package relationships.
+<p>
+
+The <tt/Depends/ field should be used if the depended-on package is
+required for the depending package to provide a significant amount of
+functionality.
+
+<tag><tt/Recommends/
+<item>
+This declares a strong, but not absolute, dependency.
+<p>
+
+<tt/Recommends/ is ignored by <prgn/dpkg/, so that users using the
+command-line (who are presumed to know what they're doing) will not be
+impeded.
+<p>
+
+It is treated by <prgn/dselect/ exactly as <tt/Depends/ is; this makes
+it hard for the user to select things so as to leave <tt/Recommends/
+fields unsatisfied, but they are able to do so by being persistent.
+<p>
+
+The <tt/Recommends/ field should list packages that would be found
+together with this one in all but unusual installations.
+
+<tag><tt/Suggests/
+<item>
+
+This is used to declare that one package may be more useful with one
+or more others. Using this field tells the packaging system and the
+user that the listed packages are be related to this one and can
+perhaps enhance its usefulness, but that installing this one without
+them is perfectly reasonable.
+<p>
+
+<prgn/dselect/ will offer suggsted packages to the system administrator
+when they select the suggesting package, but the default is not to
+install the suggested package.
+
+<tag><tt/Pre-Depends/
+<item>
+
+This field is like <tt/Depends/, except that it also forces <prgn/dpkg/
+to complete installation of the packages named before even starting
+the installation of the package which declares the predependency.
+<p>
+
+<prgn/dselect/ checks for predependencies when it is doing an
+installation run, and will attempt to find the packages which are
+required to be installed first and do so in the right order.
+<p>
+
+However, this process is slow (because it requires repeated
+invocations of <prgn/dpkg/) and troublesome (because it requires
+guessing where to find the appropriate files).
+<p>
+
+For these reasons, and because this field imposes restrictions on the
+order in which packages may be unpacked (which can be difficult for
+installations from multipart media, for example), <tt/Pre-Depends/
+should be used sparingly, preferably only by packages whose premature
+upgrade or installation would hamper the ability of the system to
+continue with any upgrade that might be in progress.
+<p>
+
+When the package declaring it is being configured, a
+<tt/Pre-Dependency/ will be considered satisfied only if the depending
+package has been correctly configured, just as if an ordinary
+<tt/Depends/ had been used.
+<p>
+
+However, when a package declaring a predependency is being unpacked
+the predependency can be satisfied even if the depended-on package(s)
+are only unpacked or half-configured, provided that they have been
+configured correctly at some point in the past (and not removed or
+partially removed since). In this case both the previously-configured
+and currently unpacked or half-configured versions must satisfy any
+version clause in the <tt/Pre-Depends/ field.
+
+</taglist>
+
+When selecting which level of dependency to use you should consider
+how important the depended-on package is to the functionality of the
+one declaring the dependency. Some packages are composed of
+components of varying degrees of importance. Such a package should
+list using <tt/Depends/ the package(s) which are required by the more
+important components. The other components' requirements may be
+mentioned as Suggestions or Recommendations, as appropriate to the
+components' relative importance.
+
+<sect1>Dependencies on shared libraries
+<p>
+
+The dependency fields listed above are used by packages which need
+shared libraries to declare dependencies on the appropriate packages.
+<p>
+
+These dependencies are usually determined automatically using
+<prgn/dpkg-shlibdeps/ and inserted in the package control file using
+the control file substitution variables mechanism; see <ref
+id="srcsubstvars"> and <ref id="sourcetools">.
+
+<sect1>Deconfiguration due to removal during bulk installations
+<p>
+
+If <prgn/dpkg/ would like to remove a package due to a conflict, as
+described above, but this would violate a dependency of some other
+package on the system, <prgn/dpkg/ will usually not remove the
+conflicting package and halt with an error.
+<p>
+
+However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used
+<prgn/dpkg/ will automatically `deconfigure' the package with the
+problematic dependency, so that the conflicting package can be removed
+and the package we're trying to install can be installed. If
+<prgn/dpkg/ is being asked to install packages (rather than just
+unpacking them) it will try to reconfigure the package when it has
+unpacked all its arguments, in the hope that one of the other packages
+it is installing will satisfy the problematic dependency.
+<p>
+
+<prgn/dselect/ supplies this argument to <prgn/dpkg/ when it invokes it,
+so that bulk installations proceed smoothly.
+
+<sect id="conflicts">Alternative packages - <tt/Conflicts/ and <tt/Replaces/
+<p>
+
+When one package declares a conflict with another <prgn/dpkg/ will
+refuse to allow them to be installed on the system at the same time.
+<p>
+
+If one package is to be installed, the other must be removed first -
+if the package being installed is marked as replacing (<ref
+id="replaces">) the one on the system, or the one on the system is
+marked as deselected, or both packages are marked <tt/Essential/, then
+<prgn/dpkg/ will automatically remove the package which is causing the
+conflict, otherwise it will halt the installation of the new package
+with an error.
+<p>
+
+<prgn/dselect/ makes it hard to select conflicting packages, though the
+user can override this if they wish. If they do not override it then
+<prgn/dselect/ will select one of the packages for removal, and the user
+must make sure it is the right one. In the future <prgn/dselect/ will
+look for the presence of a <tt/Replaces/ field to help decide which
+package should be installed and which removed.
+<p>
+
+A package will not cause a conflict merely because its configuration
+files are still installed; it must be at least half-installed.
+<p>
+
+A special exception is made for packages which declare a conflict with
+their own package name, or with a virtual package which they provide
+(see below): this does not prevent their installation, and allows a
+package to conflict with others providing a replacement for it. You
+use this feature when you want the package in question to be the only
+package providing something.
+<p>
+
+A <tt/Conflicts/ entry should almost never have an `earlier than'
+version clause. This would prevent <prgn/dpkg/ from upgrading or
+installing the package which declared such a conflict until the
+upgrade or removal of the conflicted-with package had been completed.
+This aspect of installation ordering is not handled by <prgn/dselect/,
+so that the use <tt/Conflicts/ in this way is likely to cause problems
+for `bulk run' upgrades and installations.
+<p>
+
+
+<sect id="virtual">Virtual packages - <tt/Provides/
+<p>
+
+As well as the names of actual (`concrete') packages, the package
+relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and
+<tt/Conflicts/ may mention virtual packages.
+<p>
+
+A virtual package is one which appears in the <tt/Provides/ control
+file field of another package. The effect is as if the package(s)
+which provide a particular virtual package name had been listed by
+name everywhere were the virtual package name appears.
+<p>
+
+If there are both a real and a virtual package of the same name then
+the dependency may be satisfied (or the conflict caused) by either the
+real package or any of the virtual packages which provide it. This is
+so that, for example, supposing we have
+<example>
+Package: vm
+Depends: emacs
+</example>
+and someone else releases an xemacs package they can say
+<example>
+Package: xemacs
+Provides: emacs
+</example>
+and all will work in the interim (until a purely virtual package name
+is decided on and the <tt/emacs/ and <tt/vm/ packages are changed to
+use it).
+<p>
+
+If a dependency or a conflict has a version number attached then only
+real packages will be considered to see whether the relationship is
+satisfied (or the prohibition violated, for a conflict) - it is
+assumed that a real package which provides virtual package is not of
+the `right' version. So, a <tt/Provides/ field may not contain
+version numbers, and the version number of the concrete package which
+provides a particular virtual package will not be looked at when
+considering a dependency on or conflict with the virtual package name.
+<p>
+
+It is likely that the ability will be added in a future release of
+<prgn/dpkg/ to specify a version number for each virtual package it
+provides. This feature is not yet present, however, and is expected
+to be used only infrequently.
+<p>
+
+If you want to specify which of a set of real packages should be the
+default to satisfy a particular dependency on a virtual package, you
+should list the real package as alternative before the virtual.
+<p>
+
+
+<sect id="replaces"><tt/Replaces/ - overwriting files and replacing packages
+<p>
+
+The <tt/Replaces/ control file field has two purposes, which come into
+play in different situations.
+<p>
+
+Virtual packages (<ref id="virtual">) are not considered when looking
+at a <tt/Replaces/ field - the packages declared as being replaced
+must be mentioned by their real names.
+
+<sect1>Overwriting files in other packages
+<p>
+
+Firstly, as mentioned before, it is usually an error for a package to
+contains files which are on the system in another package, though
+currently the <tt/--force-overwrite/ flag is enabled by default,
+downgrading the error to a warning,
+<p>
+
+If the overwriting package declares that it replaces the one
+containing the file being overwritten then <prgn/dpkg/ will proceed, and
+replace the file from the old package with that from the new. The
+file will no longer be listed as `owned' by the old package.
+<p>
+
+If a package is completely replaced in this way, so that <prgn/dpkg/
+does not know of any files it still contains, it is considered to have
+disappeared. It will be marked as not wanted on the system (selected
+for removal) and not installed. Any conffiles details noted in the
+package will be ignored, as they will have been taken over by the
+replacing package(s). The package's <prgn/postrm/ script will be run to
+allow the package to do any final cleanup required.
+See <ref id="mscriptsinstact">.
+<p>
+
+In the future <prgn/dpkg/ will discard files which overwrite those from
+another package which declares that it replaces the one being
+installed (so that you can install an older version of a package
+without problems).
+<p>
+
+This usage of <tt/Replaces/ only takes effect when both packages are
+at least partially on the system at once, so that it can only happen
+if they do not conflict or if the conflict has been overridden.
+
+<sect1>Replacing whole packages, forcing their removal
+<p>
+
+Secondly, <tt/Replaces/ allows <prgn/dpkg/ and <prgn/dselect/ to resolve
+which package should be removed when a conflict - see
+<ref id="conflicts">. This usage only takes effect when the two
+packages <em/do/ conflict, so that the two effects do not interfere
+with each other.
+<p>
+
+<sect>Defaults for satisfying dependencies - ordering
+<p>
+
+Ordering is significant in dependency fields.
+<p>
+
+Usually dselect will suggest to the user that they select the package
+with the most `fundamental' class (eg, it will prefer Base packages to
+Optional ones), or the one that they `most wanted' to select in some
+sense.
+<p>
+
+In the absence of other information <prgn/dselect/ will offer a
+default selection of the first named package in a list of
+alternatives.
+<p>
+
+However, there is no way to specify the `order' of several packages
+which all provide the same thing, when that thing is listed as a
+dependency.
+<p>
+
+Therefore a dependency on a virtual package should contain a concrete
+package name as the first alternative, so that this is the default.
+<p>
+
+For example, consider the set of packages:
+
+<example>
+Package: glibcdoc
+Recommends: info-browser
+
+Package: info
+Provides: info-browser
+
+Package: emacs
+Provides: info-browser
+</example>
+<p>
+
+If <prgn/emacs/ and <prgn/info/ both have the same priority then
+<prgn/dselect/'s choice is essentially random. Better would be
+<example>
+Package: glibcdoc
+Recommends: info | info-browser
+</example>
+so that <prgn/dselect/ defaults to selecting the lightweight standalone
+info browser.
+
+
+
+<chapt id="conffiles">Configuration file handling
+<p>
+
+<prgn/dpkg/ can do a certain amount of automatic handling of package
+configuration files.
+<p>
+
+Whether this mechanism is appropriate depends on a number of factors,
+but basically there are two approaches to any particular configuration
+file.
+<p>
+
+The easy method is to ship a best-effort configuration in the package,
+and use <prgn/dpkg/'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>
+
+The hard method is to build the configuration file from scratch in the
+<prgn/postinst/ 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.
+
+<sect>Automatic handling of configuration files by <prgn/dpkg/
+<p>
+
+A package may contain a control area file called <tt/conffiles/. 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>
+
+When a package is upgraded <prgn/dpkg/ will process the configuration
+files during the configuration stage, shortly before it runs the
+package's <prgn/postinst/ script,
+<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>
+
+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 - ie, 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>
+
+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>
+
+When a package is installed for the first time <prgn/dpkg/ will install
+the file that comes with it, unless that would mean overwriting a file
+already on the filesystem.
+<p>
+
+However, note that <prgn/dpkg/ will <em/not/ 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>
+
+Note that a package should <em/not/ modify a <prgn/dpkg/-handled
+conffile in its maintainer scripts. Doing this will lead to
+<prgn/dpkg/ giving the user confusing and possibly dangerous options
+for conffile update when the package is upgraded.
+
+<sect>Fully-featured maintainer script configuration handling
+<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/ script.
+<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>
+
+When using this method there are a couple of important issues which
+should be considered:
+<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>
+
+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
+<tt>/usr/sbin</>, by convention called <tt/<var/package/config/ and
+then run that if appropriate from the post-installation script. The
+<tt/<var/package/config/ 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/ flag to
+overwrite it.
+
+
+
+<chapt id="alternatives">Alternative versions of an interface -
+<prgn/update-alternatives/
+<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>
+
+For example, there are several versions of the <prgn/vi/ editor, and
+there is no reason to prevent all of them from being installed at
+once, each under their own name (<prgn/nvi/, <prgn/vim/ or whatever).
+Nevertheless it is desirable to have the name <tt/vi/ refer to
+something, at least by default.
+<p>
+
+If all the packages involved cooperate, this can be done with
+<prgn/update-alternatives/.
+<p>
+
+Each package provides its own version under its own name, and calls
+<prgn/update-alternatives/ in its postinst to register its version
+(and again in its prerm to deregister it).
+<p>
+
+See the manpage <manref name=update-alternatives section=8> for
+details.
+<p>
+
+If <prgn/update-alternatives/ does not seem appropriate you may wish
+to consider using diversions instead.
+
+
+<chapt id="diversions">Diversions - overriding a package's version of a file
+<p>
+
+It is possible to have <prgn/dpkg/ 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>
+
+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>
+
+Before deciding to use a diversion, read <ref id="alternatives"> to
+see if you really want a diversion rather than several alternative
+versions of a program.
+<p>
+
+There is a diversion list, which is read by <prgn/dpkg/, and updated
+by a special program <prgn/dpkg-divert/. Please see <manref
+name=dpkg-divert section=8> for full details of its operation.
+<p>
+
+When a package wishes to divert a file from another, it should call
+<prgn/dpkg-divert/ in its preinst to add the diversion and rename the
+existing file. For example, supposing that a <prgn/smailwrapper/
+package wishes to install a wrapper around <tt>/usr/sbin/smail</>:
+<example>
+if [ install = "$1" ]; then
+ dpkg-divert --package smailwrapper --add --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+fi
+</example>
+Testing <tt/$1/ is necessary so that the script doesn't try to add the
+diversion again when <prgn/smailwrapper/ is upgraded. The
+<tt/--package smailwrapper/ ensures that <prgn/smailwrapper/'s copy of
+<tt>/usr/sbin/smail</> can bypass the diversion and get installed as
+the true version.
+<p>
+
+The postrm has to do the reverse:
+<example>
+if [ remove = "$1" ]; then
+ dpkg-divert --package smailwrapper --remove --rename \
+ --divert /usr/sbin/smail.real /usr/sbin/smail
+fi
+</example>
+<p>
+
+Do not attempt to divert a file which is vitally important for the
+system's operation - when using <prgn/dpkg-divert/ there is a time,
+after it has been diverted but before <prgn/dpkg/ has installed the
+new version, when the file does not exist.
+
+
+<chapt id="sharedlibs">Shared libraries
+<p>
+
+Packages containing shared libraries must be constructed with a little
+care to make sure that the shared library is always available. This
+is especially important for packages whose shared libraries are
+vitally important, such as the libc.
+<p>
+
+Firstly, your package should install the shared libraries under their
+normal names. For example, the <prgn/libgdbm1/ package should install
+<tt/libgdbm.so.1.7.3/ as <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The
+files should not be renamed or relinked by any prerm or postrm
+scripts; <prgn/dpkg/ will take care of renaming things safely without
+affecting running programs, and attempts to interfere with this are
+likely to lead to problems.
+<p>
+
+Secondly, your package should include the symlink that <prgn/ldconfig/
+would create for the shared libraries. For example, the
+<prgn/libgdbm1/ package should include a symlink from
+<tt>/usr/lib/libgdbm.so.1</tt> to <tt/libgdbm.so.1.7.3/. This is
+needed so that <prgn/ld.so/ can find the library in between the time
+<prgn/dpkg/ installs it and <prgn/ldconfig/ is run in the
+<prgn/postinst/ script. Futhermore, and <em/this is very important/,
+the library must be placed before the symlink pointing to it in the
+<tt/.deb/ file. This is so that by the time <prgn/dpkg/ comes to
+install the symlink (overwriting the previous symlink pointing at an
+older version of the library) the new shared library is already in
+place. Currently the way to ensure the ordering is done properly is
+to install the library in the appropriate <tt>debian/tmp/.../lib</>
+directory before creating the symlink, by putting the commands in the
+<tt>debian/rules</> in the appropriate order.
+<p>
+
+<!--
+ next Paragraph added to close Bug #5299, Guy Maor
+ -->
+
+Thirdly, the development package should contain a symlink for the
+shared library without a version number. For example, the
+<tt/libgdbm1-dev/ package should include a symlink from
+<tt>/usr/lib/libgdm.so</> to <tt/libgdm.so.1.7.3/. This symlink is
+needed by <prgn/ld/ when compiling packages as it will only look for
+<tt/libgdm.so/ and <tt/libgdm.a/ when compiling dynamically or
+statically, respectively.
+<p>
+
+<!--
+ next paragraph changed by Christian Schwarz (see policy weekly #6)
+ -->
+
+Any package installing shared libraries in a directory that's listed
+in <tt>/etc/ld.so.conf</tt> or in one of the default library
+directories of <prgn/ld.so/ (currently, these are <tt>/usr/lib</tt>
+and <tt>/lib</tt>) must call <prgn/ldconfig/ in its <prgn/postinst/
+script if and only if the first argument is `configure'. However, it
+is important not to call <prgn/ldconfig/ in the postrm or preinst
+scripts in the case where the package is being upgraded (see <ref
+id="unpackphase">), as <prgn/ldconfig/ will see the temporary names
+that <prgn/dpkg/ uses for the files while it is installing them and
+will make the shared library links point to them, just before
+<prgn/dpkg/ continues the installation and removes the links!
+<p>
+
+<!--
+ moved from section 2.2 , DMorris
+ -->
+
+<sect id="shlibs">The <tt/shlibs/ File Format
+<p>
+
+This file is for use by <prgn/dpkg-shlibdeps/ and is required when
+your package provides shared libraries.
+<p>
+
+Each line is of the form:
+<example>
+<var/library-name/ <var/version-or-soname/ <var/dependencies .../
+</example>
+<p>
+
+<var/library-name/ is the name of the shared library, for example
+<tt/libc5/.
+<p>
+
+<var/version-or-soname/ is the soname of the library - ie, the thing
+that must exactly match for the library to be recognised by
+<prgn/ld.so/. Usually this is major version number of the library.
+<p>
+
+<var/dependencies/ has the same syntax as a dependency field in a
+binary package control file. It should give details of which
+package(s) are required to satisfy a binary built against the version
+of the library contained in the package. See <ref id="depsyntax">.
+<p>
+
+For example, if the package <tt/foo/ contains <tt/libfoo.so.1.2.3/,
+where the soname of the library is <tt/libfoo.so.1/, and the first
+version of the package which contained a minor number of at least
+<tt/2.3/ was <var/1.2.3-1/, then the package's <var/shlibs/ could
+say:
+<example>
+libfoo 1 foo (>= 1.2.3-1)
+</example>
+<p>
+
+The version-specific dependency is to avoid warnings from <prgn/ld.so/
+about using older shared libraries with newer binaries.
+
+<sect>Further Technical information on <tt/shlibs/</>
+
+<!--
+ following section mostly provided by Heiko Schlittermann
+ edited by DMorris
+ -->
+
+<sect1><em/What/ are the <tt/shlibs/ files?
+<p>
+
+The <tt>debian/shlibs</> file provides a way of checking
+for shared library dependencies on packaged binaries. They are
+intended to be used by package maintainers to make their lives easier.
+<p>
+
+Other <tt/shlibs/ files that exist on a Debian system are
+<list>
+<item> <tt>/etc/dpkg/shlibs.default</>
+<item> <tt>/etc/dpkg/shlibs.override</>
+<item> <tt>/var/lib/dpkg/info/*.shlibs</>
+<item> <tt>debian/shlibs.local</>
+</list>
+
+These files are used by <prgn/dpkg-shlibdeps/ when creating a binary
+package.
+
+<sect1><em/How/ does <prgn/dpkg-shlibdeps/ work?
+<p>
+
+<prgn/dpkg-shlibdeps/ calls <prgn/ldd/ to determine the shared libraries
+used by the compiled binaries passed through its command line.
+<p>
+
+For each shared library, <prgn/dpkg-shlibdeps/ needs to know
+<list compact>
+<item>the package containing the library, and
+<item>the library version number,
+</list>
+<p>
+it scans the following files in this order.
+<enumlist compact>
+<item><tt>debian/shlibs.local</>
+<item><tt>/etc/dpkg/shlibs.override</>
+<item><tt>/var/lib/dpkg/info/*.shlibs</>
+<item><tt>/etc/dpkg/shlibs.default</>
+</enumlist>
+
+<sect1><em/Who/ maintains the various <tt/shlibs/ files?
+<p>
+
+<list compact>
+<item><tt>/etc/dpkg/shlibs.default</> - the maintainer of dpkg
+<item><tt>/var/lib/dpkg/info/<var/package/.shlibs</> - the maintainer of each
+package
+<item><tt>/etc/dpkg/shlibs.override</> - the local system administrator
+<item><tt>debian/shlibs.local</> - the maintainer of the package
+</list>
+
+The <tt/shlibs.default/ file is managed by <prgn/dpkg/. The entries in
+<tt/shlibs.default/ that are provided by <prgn/dpkg/ are just there to
+fix things until the shared library packages all have <tt/shlibs/
+files.
+
+<sect1><em/How/ to use <prgn/dpkg-shlibdeps/ and the <tt/shlibs/ files?
+
+<sect2>If your package doesn't provide a shared library
+<p>
+
+Put a call to <prgn/dpkg-shlibs/ into your <tt>debian/rules</> file.
+If your package contains only binaries (e.g. no scripts) use:
+<example>
+dpkg-shlibdeps debian/tmp/usr/{bin,sbin}/*
+</example>
+
+If <prgn/dpkg-shlibdeps/ doesn't complain, you're done. If it does
+complain you might need to create your own <tt>debian/shlibs.local</>
+file.
+
+<sect2>If your package provides a shared library
+<p>
+
+Create a <tt>debian/shlibs</> file and let <tt>debian/rules</> install
+it in the control area:
+
+<example>
+install -m644 debian/shlibs debian/tmp/DEBIAN
+</example>
+
+If your package contains additional binaries see above.
+
+<sect1><em/How/ to write <tt>debian/shlibs.local</>
+<p>
+
+This file is intended only as a <em/temporary/ fix if your binaries
+depend on a library which doesn't provide its own
+<tt>/var/lib/dpkg/*.shlibs</> file yet.
+<p>
+
+Let's assume you are packaging a binary <tt/foo/. Your output in
+building the package might look like this.
+
+<example>
+$ ldd foo
+libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0
+libc.so.5 => /lib/libc.so.5.2.18
+libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0
+</example>
+
+And when you ran <prgn/dpkg-shlibdeps/
+
+<example>
+$ dpkg-shlibdeps -o foo
+dpkg-shlibdeps: warning: unable to find dependency information
+for shared library libbar
+(soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends)
+shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18)
+</example>
+
+The <prgn/foo/ binary depends on the <prgn/libbar/ shared library, but
+no package seems to provide a <tt/*.shlibs/ file in
+<tt//var/lib/dpkg/info/. Let's determine the package responsible:
+<p>
+
+<example>
+$ dpkg -S /usr/X11R6/lib/libbar.so.1.0
+bar1: /usr/X11R6/lib/libbar.so.1.0
+$ dpkg -s bar1 | grep Version
+Version: 1.0-1
+</example>
+
+This tells us that the <prgn/bar1/ package, version 1.0-1 is the one
+we are using. Now we can create our own <tt>debian/shlibs.local</> to
+temporarly fix the above problem. Include the following line into your
+<tt>debian/shlibs.local</> file.
+
+<example>
+ libbar 1 bar1 (>= 1.0-1)
+</example>
+
+Now your package build should work. As soon as the maintainer of
+<prgn/libbar1/ provides a <tt/shlibs/ file, you can remove your
+<tt>debian/shlibs.local</> file.
+
+<chapt id="methif"><prgn/dselect/'s interface to its installation methods
+<p>
+
+<prgn/dselect/ calls scripts from its installation methods when it
+needs to actually access data from the distribution. The core program
+<prgn/dselect/ itself just calls these scripts and provides the
+package and access method selection interfaces. The installation
+methods are responsible for invoking <prgn/dpkg/ as appropriate.
+<p>
+
+Each installation method has three scripts:
+<list compact>
+<item>Setup installation parameters.
+<item>Update list of available packages.
+<item>Install.
+</list>
+<p>
+
+<prgn/dselect/ searches for methods in <tt>/usr/lib/dpkg/methods</>
+and <tt>/usr/local/lib/dpkg/methods</>.
+
+<sect>Functions of the method scripts
+<p>
+
+The setup script is run just after the user has chosen an installation
+method. It should prompt the user for parameters like the site to
+NFS-mount or FTP from, the directory to use, or the directory or
+filesystem where the <tt/.deb/ files can be found, or the tape or
+floppy device to install from. It should store the responses under
+<tt>/var/lib/dpkg/methods</> - see below. If no available
+packages list is available it should perhaps offer to scan the
+available packages.
+<p>
+
+The update script should obtain a list of available packages if
+possible, and run <tt/dpkg --update-avail/, <tt/dpkg --merge-avail/
+and/or <tt/dpkg --forget-old-unavail/ to load it into <prgn/dpkg/ and
+<prgn/dselect/'s database of available packages. If no packages list
+was available and the user was offered and accepted the option of
+scanning the actual files available this scan should be done here,
+using <tt/dpkg --record-avail/.
+<p>
+
+The install script should feed all the available <tt/.deb/ files to
+<tt/dpkg --iGOEB/ (this is equivalent to <tt/dpkg --install
+--refuse-downgrade --selected-only --skip-same-version
+--auto-deconfigure/). The <tt/-R/ (<tt/--recursive/) option for
+traversing subdirectories may also be useful here).
+<p>
+
+If any of these scripts needs to display a message for the user, it
+should wait for the user to hit `return' before exiting so that
+dselect doesn't immediately rewrite the screen.
+<p>
+
+If a method script succeeds (returns a zero exit status)
+<prgn/dselect/ will return immediately to the main menu, with the
+`next' option highlighted ready for the user to select it. If it
+fails <prgn/dselect/ will display a message and wait for the user to
+hit return.
+
+<sect>Location and arguments of the method scripts
+<p>
+
+A set of scripts (henceforth known as a group) may provide several
+methods on the `main menu' with different behaviour. For example,
+there might be a generic get-packages-by-FTP group which might provide
+methods in the main menu for installation directly from one of the
+Debian mirror sites as well as for installation from a user-specified
+site.
+<p>
+
+Each group of methods implemented by the same set of scripts should
+have a subdirectory <tt>/usr/lib/dpkg/methods/<var/group/</> or
+<tt>/usr/local/lib/dpkg/methods/<var/group/</>, containing:
+<taglist compact>
+<tag><tt/names/
+<item>a list of user-visible methods provided by these scripts.
+<tag><tt/setup/
+<tag><tt/update/
+<tag><tt/install/
+<item>executable programs, the scripts themselves.
+<tag><tt/desc.<var/option//
+<item>description file.
+</taglist>
+<p>
+
+<tt/names/ will be formatted as a list of lines, each containing:
+<example>
+<var/sequence/ <var/method/ <var/summary/
+</example>
+<p>
+
+<var/sequence/ is a two-digit number that will be used much like
+<tt/rc.d/ prefixes to control the order in the main menu. If in doubt
+use 50.
+<p>
+
+<var/method/ is a name which is displayed by <prgn/dselect/ as the
+name of the method, and which will be passed to <tt/setup/,
+<tt/update/ and <tt/unpack/ as their first argument.
+<p>
+
+<var/summary/ is the brief description string for <prgn/dselect/'s menu.
+<p>
+
+Each of the three scripts gets the same three arguments: <var/vardir/,
+<var/group/ and <var/method/. <var/vardir/ is the base directory for
+storing <prgn/dpkg/ and <prgn/dselect/'s state, usually
+<tt>/var/lib/dpkg</>; this is passed in so that the <tt/--admindir/
+option to <prgn/dselect/ is honoured).
+<p>
+
+Each option may have an extended description in
+<tt/desc.<var/option//. This should be formatted like the extended
+description part of a <tt/Description/ field entry <em/shifted one
+character to the left/.
+<p>
+
+<tt><var/vardir//methods</> will exist, and a method group may use a
+<tt><var/vardir//methods/<var/group/</> directory to store its state.
+<p>
+
+The group name and method name must follow the rules for C identifiers.
+
+<chapt id="conversion">Conversion procedure from old source packages
+<p>
+
+This is a brief summary of the procedure for converting a
+pre-2.0.0.0-format source package into the new format.
+<p>
+
+You are strongly advised to download and examine the <prgn/hello/
+package, and to read the section in the <prgn/dpkg/ programmers'
+manual describing the source packaging tools. More detail about the
+exact functionality of these tools is available in <manref
+name=dpkg-source section=1>.
+<p>
+
+<list>
+
+<item>
+Download the original source code from wherever it can be found and do
+any rearrangement required to make it look like the original tree of
+the Debian source. Put it in
+<tt><var/package/-<var/upstream-version/.orig/</> or
+<tt/<var/package/_<var/upstream-version/.orig.tar.gz/.
+
+<item>
+Rename all files <tt/debian.*/ to <tt>debian/*</>. There may be some
+exceptions to this, but this is a good start.
+
+<item>
+Edit the <tt>debian/changelog</> - create or rename it if necessary.
+Add a new revision to the top with the appropriate details, and a
+local variables entry to the bottom to set Emacs to the right mode:
+<example>
+Local variables:
+mode: debian-changelog
+End:
+</example>
+
+<item>
+Edit/create <tt>debian/control</>:
+<list compact>
+<item>
+Remove the <tt/Version/ field. If it is generated unusually (not
+equal to the source version) you must use the -v option to
+dpkg-gencontrol (see below). <tt/Section/, <tt/Priority/,
+<tt/Maintainer/ go above the first blank line, most of the rest below.
+
+<item>
+Reorder the fields and add a blank line at an appropriate point,
+separating the source package fields from the binary package
+fields.
+
+<item>
+Add the <tt/Source/ field.
+
+<item>
+Add the <tt/Standards-Version/ field. (Please check out the Debian
+Policy Manual for details about this field.)
+
+<item>
+Change the <tt/Architecture/ field for each package to <tt/any/,
+<tt/all/ or whatever. If there isn't an <tt/Architecture/ field add
+one.
+
+<item>
+If any other use of sed or things used to happen to make the binary
+control files use <prgn/dpkg-gencontrol/'s variable substitution
+features to achieve the same effect. Use <tt>debian/substvars</> if
+you need to put unusally-generated information (apart from details of
+<tt/.deb/ files) in the <tt/.changes/ file too.
+</list>
+
+<item>
+Edit the <tt>debian/rules</>:
+<list compact>
+<item>
+Remove the <prgn/source/ and <prgn/diff/ and any <prgn/changes/ and
+<prgn/dist/ targets. These things now happen in a package-independent
+way and are not done by <tt>debian/rules</>.
+<item>
+Split the <prgn/binary/ target into <prgn/binary-arch/ and
+<prgn/binary-indep/; in many cases all of <prgn/binary/ should go into
+<prgn/binary-arch/. Create the <prgn/binary/ target and the unused of
+the two other <prgn/binary-*/ targets if there is one - you can copy
+the ones from the <prgn/hello/ package.
+<item>
+Change the <prgn/binary/ target to use <prgn/dpkg-gencontrol/ to make
+the package control file(s). Move it to after all the files have been
+installed but just before the last <prgn/chown/ and <prgn/chmod/ in
+the target.
+<item>
+Change occurrences of <tt/debian-tmp/ to <tt>debian/tmp</>.
+<item>
+Change occurrences of <tt/debian.{post,pre}{inst,rm}/ to
+<tt>debian/*</>.
+<item>
+Remove the version number setting at the top, if there is one.
+<item>
+Ensure that the package's Debian-specific and upstream changelogs are
+installed.
+</list>
+
+<item>
+Change the package to use <prgn/dpkg-shlibdeps/ to determine its
+shared library dependencies and substitute them in. Shared library
+dependencies should no longer be hardwired in the source package.
+
+<item>
+Check that the <tt>debian/README</> is really the copyright file, and
+if so rename it to <tt>debian/copyright</> and edit
+<tt>debian/rules</> to cope with this and to change the installation
+of the copyright file from <tt>/usr/doc/<var/package//copyright</>
+to <tt>/usr/doc/copyright/<var/package/</>. If it isn't then
+find <tt>debian/copyright</> and decide what to do with the
+<tt>README</>.
+
+<item>
+Check for various other anachronisms and problems:
+<list compact>
+<item>
+Remove any <tt/Package_Revision/, <tt/Package-Revision/ or
+<tt/Revision/ fields.
+<item>
+Rename <tt/Optional/ to <tt/Suggests/, <tt/Recommended/ to
+<tt/Recommends/.
+<item>
+Change <tt>/usr/doc/examples/<var/package/</> to
+<tt>/usr/doc/<var/package//examples</>.
+<item>
+Make sure that manpages are installed compressed.
+<item>
+Check that the description has an extended description, is
+well-formatted and meaningful and helpful to people wanting to know
+whether to install a package.
+</list>
+
+<item>
+Look everything over.
+
+<item>
+Do a test build using <tt/dpkg-buildpackage -us -uc -sa
+-r<var/whatever//. Check the permissions and locations of files in
+the resulting package by examining the output of <tt/dpkg-deb
+--contents/, and check that the source build happened OK. Test
+install the binary package(s) and test extract the source package(s).
+
+<item>
+Sign the release: either rebuild everything with <tt/dpkg-buildpackage
+-sa/, or PGP-sign the <tt/.dsc/, rebuild the <tt/.changes/ using
+<tt/dpkg-genchanges -sa/, and then PGP-sign the <tt/.changes/.
+
+</list>
+<p>
+
+The use of <tt/-sa/ on <prgn/dpkg-buildpackage/ and
+<prgn/dpkg-genchanges/ is important when doing the first
+build/uploading of a new-format source package. Unless this happens
+to be Debian revision <tt/0/ or <tt/1/ by default the original source
+tarfile will not be included in the uploaded files listed in the
+<tt/.changes/ file, and so it won't be installed on the FTP site.
+<tt/-sa/ requests that the original source be included regardless.
+
+</book>
--- /dev/null
+<!doctype debiandoc system [
+<!-- include version information so we don't have to hard code it
+ within the document -->
+<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+]>
+<debiandoc>
+<!--
+ Debian GNU/Linux Policy Manual.
+ Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
+ released under the terms of the GNU
+ General Public License, version 2 or (at your option) any later.
+ Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
+ Revised November 27, 1996, David A. Morris, bweaver@debian.org
+ New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
+ Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
+ Maintainer since 1997, Christian Schwarz, schwarz@debian.org
+ Christoph Lameter contributed the "Web Standard"
+ -->
+
+<book>
+
+<title>Debian Policy Manual
+<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+<author>Christian Schwarz <email/schwarz@debian.org/
+<author>revised: David A. Morris <email/bweaver@debian.org/
+<version>version &version;, &date;
+
+<abstract>
+This manual describes the policy requirements for the Debian GNU/Linux
+distribution. This includes the structure and contents of the Debian
+archive, several design issues of the operating system, as well as
+technical requirements that each package must satisfy to be included
+in the distribution.
+</abstract>
+
+<copyright>Copyright ©1996,1997,1998 Ian Jackson and Christian Schwarz.
+<p>
+
+This manual is free software; you may redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+<p>
+
+This is distributed in the hope that it will be useful, but
+<em>without any warranty</em>; without even the implied warranty of
+merchantability or fitness for a particular purpose. See the GNU
+General Public License for more details.
+<p>
+
+A copy of the GNU General Public License is available as
+<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
+distribution or on the World Wide Web at
+<url id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it
+by writing to the Free Software Foundation, Inc., 59 Temple Place -
+Suite 330, Boston, MA 02111-1307, USA.
+<p>
+
+<toc sect>
+
+<chapt id="scope">About this manual
+<p>
+
+<sect>Scope
+<p>
+
+This manual describes the policy requirements for the Debian GNU/Linux
+distribution. This includes the structure and contents of the Debian
+archive, several design issues of the operating system, as well as
+technical requirements that each package must satisfy to be included
+in the distribution.
+<p>
+
+This manual does <em/not/ describe the technical mechanisms involved
+in package creation, installation, and removal. This information can
+be found in the <em>Debian Packaging Manual</em> and the <em>Debian
+System Administrators' Manual</em>.
+<p>
+
+This document assumes familiarity with these other two manuals.
+Unfortunately, the <em>System Administrators' Manual</em> does not
+exist yet.
+<p>
+
+Much of the information presented in this manual will be useful even
+when building a package which is to be distributed in some other way
+or is for local use.
+<p>
+
+<sect>New versions of this document
+<p>
+
+The current version of this document is always accessible from the
+Debian FTP server at
+<url id="ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz">
+or from the Debian WWW server at
+<url id="http://www.debian.org/doc/manuals/debian-policy/">
+<p>
+
+There is also a home page for the <em>Debian Policy Manual</em> that
+contains links to the current development version of this document as
+well as an archive of old versions. The URL is
+<url id="http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-policy/">
+<p>
+
+In addition, this manual is distributed via the Debian package
+<tt>debian-policy</tt>
+<p>
+
+<sect>Feedback
+<p>
+
+As the Debian GNU/Linux system is continuously evolving this manual is
+changed from time to time.
+<p>
+
+While the authors of this document tried hard not to include any typos
+or other errors these still occur. If you discover an error in this
+manual or if you want to tell us any comments, suggestions, or critics
+please send an email to the Debian Policy Manager, Christian
+Schwarz <email>schwarz@debian.org</email>, the developers' mailing
+list <email>debian-devel@lists.debian.org</email>, or submit a bug report
+against the <tt>debian-policy</tt> package.
+<p>
+
+<chapt>The Debian Archive
+<p>
+
+The Debian GNU/Linux system is maintained and distributed as a
+collection of <em>packages</em>. Since there are so many of them (over
+1000) they are split into <em>sections</em> and <em>priorities</em> to
+simplify handling of them.
+<p>
+
+The effort of the Debian project is to build a free operating system,
+but not every package we want to make accessible is <em>free</em> in
+our sense (see Debian Free Software Guidelines, below), or may be
+imported/exported without restrictions. Thus, the archive is split
+into the sections <em/main/, <em/non-us/, <em/non-free/, and
+<em/contrib/.
+<p>
+
+The <em/main/ section forms the <em>Debian GNU/Linux distribution</em>.
+<p>
+
+Packages in the other sections are not considered as part of the
+Debian distribution, though we support their use, and we provide
+infrastructure for them (such as our bug-tracking system and mailing
+lists). This Debian Policy Manual applies to these packages as well.
+<p>
+
+<sect id="pkgcopyright">Package copyright and sections
+<p>
+
+The aims of this policy are:
+<p>
+
+<list compact>
+<item>
+We want to make as much software available as we can.<p>
+<item>
+We want to encourage everyone to write free software.<p>
+<item>
+We want to make it easy for people to produce CD-ROMs of our system
+without violating any licenses, import/export restrictions, or any
+other laws.<p>
+</list>
+<p>
+
+<sect1>The Debian Free Software Guidelines
+<p>
+
+The Debian Free Software Guidelines (DFSG) as is our definition of `free'
+software.
+<p>
+
+<enumlist>
+<item>Free Redistribution
+<p>
+The license of a Debian component may not restrict any party from
+selling or giving away the software as a component of an aggregate
+software distribution containing programs from several different
+sources. The license may not require a royalty or other fee for such
+sale.
+<p>
+
+<item>Source Code
+<p>
+
+The program must include source code, and must allow distribution in
+source code as well as compiled form.
+<p>
+
+<item>Derived Works
+<p>
+
+The license must allow modifications and derived works, and must allow
+them to be distributed under the same terms as the license of the original
+software.
+<p>
+
+<item>Integrity of The Author's Source Code
+<p>
+
+The license may restrict source-code from being distributed in modified
+form <em/only/ if the license allows the distribution of ``patch files''
+with the source code for the purpose of modifying the program at build
+time. The license must explicitly permit distribution of software built
+from modified source code. The license may require derived works to
+carry a different name or version number from the original software.
+(This is a compromise. The Debian group encourages all authors to not
+ restrict any files, source or binary, from being modified.)
+<p>
+
+<item>No Discrimination Against Persons or Groups
+<p>
+
+The license must not discriminate against any person or group of
+persons.
+<p>
+
+<item>No Discrimination Against Fields of Endeavor
+<p>
+
+The license must not restrict anyone from making use of the program
+in a specific field of endeavor. For example, it may not restrict the
+program from being used in a business, or from being used for genetic
+research.
+<p>
+
+<item>Distribution of License
+<p>
+
+The rights attached to the program must apply to all to whom the
+program is redistributed without the need for execution of an
+additional license by those parties.
+<p>
+
+<item>License Must Not Be Specific to Debian
+<p>
+
+The rights attached to the program must not depend on the program's
+being part of a Debian system. If the program is extracted from Debian
+and used or distributed without Debian but otherwise within the terms
+of the program's license, all parties to whom the program is redistributed
+should have the same rights as those that are granted in conjunction with
+the Debian system.
+<p>
+
+<item>License Must Not Contaminate Other Software
+<p>
+
+The license must not place restrictions on other software that is
+distributed along with the licensed software. For example, the
+license must not insist that all other programs distributed on the
+same medium must be free software.
+<p>
+
+<item>Example Licenses
+<p>
+The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are examples of licenses
+that we consider <em/free/.
+
+</enumlist>
+<p>
+
+<sect1>The main section
+<p>
+
+Every package in "main" must comply with the DFSG (Debian Free
+Software Guidelines).
+<p>
+
+In addition, the packages in "main"
+<p>
+
+<list compact>
+<item>must not require a package outside of "main" for compilation or
+execution (thus, the package may not declare a "Depends" or
+"Recommends" relationship on a non-main package),
+<p>
+<item>must not be so buggy that we refuse to support them,
+<p>
+<item>must meet all policy requirements presented in this manual.
+</list>
+<p>
+
+<sect1>The contrib section
+<p>
+
+Every package in "contrib" must comply with the DFSG.
+<p>
+
+Examples of packages which would be included in "contrib" are
+<p>
+<list compact>
+<item>free packages which require "contrib", "non-free", or "non-US"
+ packages or packages which are not in our archive at all for
+ compilation or execution,
+<p>
+<item>wrapper packages or other sorts of free accessories for
+ non-free programs,
+<p>
+<item>packages which we don't want to support because they are too
+ buggy, and
+<p>
+<item>packages which fail to meet some other policy requirements in
+ a serious way.
+</list>
+<p>
+
+<sect1>The non-free section
+<p>
+
+`Non-free' contains packages which are not compliant with the DFSG
+or which are encumbered by patents or other legal issues that make
+their distribution problematic.
+<p>
+
+All packages in `non-free' must be electronically distributable across
+international borders.
+<p>
+
+<sect1>The non-us server
+<p>
+
+Some programs with cryptographic program code must be stored on the
+"non-us" server because of export restrictions of the U.S.
+<p>
+
+This applies only to packages which contain cryptographic code. A package
+containing a program with an interface to a cryptographic program or a
+program that's dynamically linked against a cryptographic library can be
+distributed if it is capable of running without the cryptography library
+or program.
+<p>
+
+<sect1>Further copyright considerations
+<p>
+
+Every package must be accompanied by a verbatim copy of its copyright
+and distribution license in the file
+/usr/doc/<package-name>/copyright (see <ref id="copyrightfile">
+for details).
+<p>
+
+We reserve the right to restrict files from being included anywhere in
+our archives if
+<p>
+<list compact>
+<item>their use or distribution would break a law,
+<p>
+<item>there is an ethical conflict in their distribution or use,
+<p>
+<item>we would have to sign a license for them, or
+<p>
+<item>their distribution would conflict with other project policies.
+</list>
+<p>
+
+Programs whose authors encourage the user to make donations are fine
+for the main distribution, provided that the authors do not claim that
+not donating is immoral, unethical, illegal or something similar;
+otherwise they must go in contrib (or non-free, if even distribution
+is restricted by such statements).
+<p>
+
+Packages whose copyright permission notices (or patent problems) do
+not allow redistribution even of only binaries, and where no special
+permission has been obtained, cannot be placed on the Debian FTP site and
+its mirrors at all.
+<p>
+
+Note, that under international copyright law (this applies in
+the United States, too) <em/no/ distribution or
+modification of a work is allowed without an explicit notice saying
+so. Therefore a program without a copyright notice <em/is/
+copyrighted and you may not do anything to it without risking being
+sued! Likewise if a program has a copyright notice but no statement
+saying what is permitted then nothing is permitted.
+<p>
+
+Many authors are unaware of the problems that restrictive copyrights
+(or lack of copyright notices) can cause for the users of their
+supposedly-free software. It is often worthwhile contacting such
+authors diplomatically to ask them to modify their license
+terms. However, this is a politically difficult thing to do and you
+should ask for advice on <tt/debian-devel/ first.
+<p>
+
+When in doubt, send mail to <email/debian-devel@lists.debian.org/. Be
+prepared to provide us with the copyright statement. Software covered
+by the GPL, public domain software and BSD-like copyrights are safe;
+be wary of the phrases `commercial use prohibited' and `distribution
+restricted'.
+<p>
+
+<sect1>Subsections
+<p>
+
+The packages in the <em/main/, <em/contrib/, and <em/non-free/
+sections are grouped further into <em>subsections</em> to simplify
+handling of them.
+<p>
+
+The section for each package is specified in the package's <em>control
+record</em>. However, the maintainer of the Debian archive may
+override this selection to assure the consistency of the Debian
+distribution.
+<p>
+
+Please check the current Debian distribution to see which sections are
+available.
+<p>
+
+<sect>Priorities
+<p>
+
+Each package is given a certain <em>priority</em> value, which is
+included in the package's <em>control
+record</em>. This information is used in the Debian package management
+tool to separate high-priority packages from less-important packages.
+<p>
+
+The following <em>priority levels</em> are supported by the Debian
+package management system, <prgn/dpkg/.
+<p>
+
+<taglist>
+<tag><tt/required/
+<item>
+<tt/required/ packages are necessary for the proper functioning of the
+system. You must not remove these packages or your system may become
+totally broken and you may not even be able to use
+<prgn/dpkg/ to put things back. Systems with only the <tt/required/
+packages are probably unusable, but they do have enough functionality
+to allow the sysadmin to boot and install more software.
+
+<tag><tt/important/
+<item>
+Important programs, including those which one would expect to find on
+any Unix-like system. If the expectation is that an experienced Unix
+person who found it missing would say `What the F*!@<+ is going on,
+where is <prgn/foo/', it should be in <tt/important/. This is an
+important criterion because we are trying to produce, amongst other
+things, a free Unix. Other packages without which the system will not
+run well or be usable should also be here. This does <em/not/
+include Emacs or X11 or TeX or any other large applications. The
+<tt/important/ packages are just a bare minimum of commonly-expected
+and necessary tools.
+
+<tag><tt/standard/
+<item>
+These packages provide a reasonably small but not too limited
+character-mode system. This is what will install by default if the
+user doesn't select anything else. It doesn't include many large
+applications, but it does include Emacs (this is more of a piece of
+infrastructure than an application) and a reasonable subset of TeX and
+LaTeX (if this is possible without X).
+
+<tag><tt/optional/
+<item>
+(In a sense everything is optional that isn't required, but that's not
+what is meant here.) This is all the software that you might
+reasonably want to install if you didn't know what it was or don't
+have specialised requirements. This is a much larger system and includes
+X11, a full TeX distribution, and lots of applications.
+
+<tag><tt/extra/
+<item>
+This contains packages that conflict with others with higher
+priorities, or are only likely to be useful if you already know what
+they are or have specialised requirements.
+
+</taglist>
+<p>
+
+Packages may not depend on packages with lower priority values.
+If this should happen, one of the priority values will have to
+be adapted.
+<p>
+
+<sect>Binary packages
+<p>
+
+The Debian GNU/Linux distribution is based on the Debian package
+management system, called <prgn/dpkg/. Thus, all packages in the
+Debian distribution have to be provided in the <tt/.deb/ file format.
+<p>
+
+<sect1>The package name
+<p>
+
+Every package must have a name that's unique within the Debian
+archive.
+<p>
+
+Package names may only consist of lower case letters, digits (0-9),
+plus (+) or minus (-) signs, and periods (.).
+<p>
+
+The package name is part of the file name of the <tt/.deb/ file and is
+included in the control field information.
+<p>
+
+<sect1>The maintainer of a package
+<p>
+
+Every package must have exactly one maintainer at a time. This person
+is responsible that the license of the package's software complies with
+the policy of the distribution this package is included in.
+<p>
+
+The maintainer must be specified in the <tt/Maintainer/ control field
+with the correct name and a working email address for the Debian
+maintainer of the package. If one person maintains several packages
+he/she should try to avoid having different forms of their name and
+email address in different <tt/Maintainer/ fields.
+<p>
+
+If the maintainer of a package quits from the Debian project the
+Debian QA Group takes over the maintainership of the package until
+someone else volunteers for that task. These packages are called
+<em>orphaned packages</em>.
+<p>
+
+<sect1>The description of a package
+<p>
+
+Every Debian package should have an extended description stored in the
+appropriate field of the control record.
+<p>
+
+The description should be written so that it tells the user what they
+need to know to decide whether to install the package. This
+description should not just be copied from the blurb for the program.
+Instructions for configuring or using the package should not be
+included--that is what installation scripts, manual pages, Info files,
+etc. are for. Copyright statements and other
+administrivia should not be included--that is what the copyright file
+is for.
+<p>
+
+<sect1>Dependencies
+<p>
+
+Every package has to specify the dependency information about other
+packages, that are required for the first to work correctly.
+<p>
+
+For example, for any shared libraries required by dynamically-linked
+executable binary in a package a dependency entry has to be provided.
+<p>
+
+It is not necessary for other packages to declare any dependencies
+they have on other packages which are marked <tt/Essential/ (see below).
+<p>
+
+Sometimes, a package requires another package to be installed
+<em>and</em> configured before it can be installed. In this case,
+you'll have to specify a <tt/Pre-Depends/ entry for the package.
+<p>
+
+You must not specify a <tt/Pre-Depends/ entry for a package before
+this has been discussed on the <tt/debian-devel/ mailing list and a
+consensus about doing that has been reached.
+<p>
+
+<sect1>Virtual packages
+<p>
+
+Sometimes, there are several packages doing more-or-less the same
+job. In this case, it's useful to define a <em>virtual package</em>
+who's name describes the function the packages have. (The virtual
+packages just exist logically, not physically--that's why they are
+called <em>virtual</em>.) The packages with this particular function
+will then <em>provide</em> the virtual package. Thus, any other
+package requiring that function can simply depend on the virtual
+package without having to specify all possible packages individually.
+<p>
+
+All packages must use virtual package names where appropriate, and
+arrange to create new ones if necessary. They must not use virtual
+package names (except privately, amongst a cooperating group of
+packages) unless they have been agreed upon and appear in the list of
+virtual package names.
+<p>
+
+The latest version of the authoritative list of virtual package names
+can be found on <ftpsite>ftp.debian.org</> in
+<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</>
+or your local mirror. In addition, it is included in the
+<tt>debian-policy</tt> package. The procedure for updating the list is
+described at the top of the file.
+<p>
+
+<sect1>Base packages
+<p>
+
+The packages included in the <tt/base/ section have a special
+function. They form a minimum subset of the Debian GNU/Linux system
+that is installed before everything else on a new system. Thus, only
+very few packages are allowed to go into the <tt/base/ section to keep
+the required disk usage very small.
+<p>
+
+Most of these packages should have the priority value <tt/required/ or
+at least <tt/important/, and many of them will be tagged
+<tt/essential/ (see below).
+<p>
+
+You must not place any packages into the <tt/base/ section before this
+has been discussed on the <tt/debian-devel/ mailing list and a
+consensus about doing that has been reached.
+<p>
+
+<sect1>Essential packages
+<p>
+
+Some packages are tagged <tt/essential/. (They have <tt/Essential:
+yes/ in their package control record.) This flag is used for packages
+that are <em>essential</em> for a system.
+<p>
+
+Since these packages can not easily be removed (you'll have to specify
+an extra <em>force option</em> to <prgn/dpkg/) this flag should only
+be used where absolutely necessary.
+
+A shared library package should not be tagged <em>essential</em>--the
+dependencies will prevent its premature removal, and we need to be
+able to remove it when it has been superseded.
+<p>
+
+You must not tag any packages <tt/essential/ before this has been
+discussed on the <tt/debian-devel/ mailing and a consensus about doing
+that has been reached.
+<p>
+
+<sect1>Maintainer scripts
+<p>
+
+The package installation scripts should avoid producing output which
+it is unnecessary for the user to see and should rely on <prgn/dpkg/
+to stave off boredom on the part of a user installing many packages.
+This means, amongst other things, using the <tt/--quiet/ option on
+<prgn/install-info/.
+<p>
+
+Packages should try to minimise the amount of prompting they need to
+do, and they should ensure that the user will only ever be asked each
+question once. This means that packages should try to use appropriate
+shared configuration files (such as <tt>/etc/papersize</> and
+<tt>/etc/nntpserver</>), rather than each prompting for their own list
+of required pieces of information.
+<p>
+
+It also means that an upgrade should not ask the same questions again,
+unless the user has used <tt/dpkg --purge/ to remove the package's
+configuration. The answers to configuration questions should be
+stored in an appropriate place in <tt>/etc</> so that the user can
+modify them, and how this has been done should be documented.
+<p>
+
+If a package has a vitally important piece of information to pass to
+the user (such as "don't run me as I am, you must edit the following
+configuration files first or you risk your system emitting
+badly-formatted messages"), it should display this in the
+<prgn/postinst/ script and prompt the user to hit return to
+acknowledge the message. Copyright messages do not count as vitally
+important (they belong in <tt>/usr/doc/copyright</>); neither do
+instructions on how to use a program (these should be in on line
+documentation, where all the users can see them).
+<p>
+
+Any necessary prompting should almost always be confined to the
+post-installation script, and should be protected with a conditional
+so that unnecessary prompting doesn't happen if a package's
+installation fails and the <prgn/postinst/ is called with
+<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/.
+<p>
+
+Errors which occur during the execution of an installation script
+<em/must/ be checked and the installation <em/must not/ continue after
+an error.
+<p>
+
+Note, that <ref id="scripts">, in general applies to package
+maintainer scripts, too.
+<p>
+
+Do not use <prgn/dpkg-divert/ on a file belonging to another package
+without consulting the maintainer of that package first.
+<p>
+
+In order for <prgn/update-alternatives/ to work correctly all the
+packages which supply an instance of the `shared' command name (or, in
+general, filename) must use it. You can use <tt/Conflicts/ to force
+the deinstallation of other packages supplying it which do not (yet)
+use <prgn/update-alternatives/. It may in this case be appropriate to
+specify a conflict on earlier versions on something--this is an
+exception to the usual rule that this is not allowed.
+<p>
+
+<sect>Source packages
+<p>
+
+<sect1>Standards conformance
+<p>
+
+You should specify the most recent version of the packaging standards
+with which your package complies in the source package's
+<tt/Standards-Version/ field.
+<p>
+
+This value will be used to file bug reports automatically if your
+package becomes too much out of date.
+<p>
+
+The value corresponds to a version of the Debian manuals, as can be
+found on the title page or page headers and footers (depending on the
+format).
+<p>
+
+The version number has four components--major and minor number and
+major and minor patch level. When the standards change in a way that
+requires every package to change the major number will be changed.
+Significant changes that will require work in many packages will be
+signaled by a change to the minor number. The major patch level will
+be changed for any change to the meaning of the standards, however
+small; the minor patch level will be changed when only cosmetic,
+typographical or other edits which do not change the meaning are made,
+or changes which do not affect the contents of packages.
+<p>
+
+You should regularly, and especially if your package has become out of
+date, check for the newest Policy Manual available and update your
+package, if necessary. When your package complies with the new
+standards you may update the <tt/Standards-Version/ source package
+field and release it.
+<p>
+
+<sect1>Changes to the upstream sources
+<p>
+
+If changes to the source code are made that are generally applicable
+please try to get them included in the upstream version of the package
+by supplying the upstream authors with the changes in whatever form
+they prefer.
+<p>
+
+If you need to configure the package differently for Debian or for
+Linux, and the upstream source doesn't provide a way to configure it
+the way you need to, please add such configuration facilities (for
+example, a new <prgn/autoconf/ test or <tt/#define/) and send the
+patch to the upstream authors, with the default set to the way they
+originally had it. You can then easily override the default in your
+<tt>debian/rules</tt> or wherever is appropriate.
+<p>
+
+Please make sure that the <prgn/configure/ utility detects the correct
+architecture specification string (refer to <ref id="arch-spec"> for
+details).
+<p>
+
+If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/
+scripts are used, you should edit the <tt/.in/ files rather than
+editing the <prgn/Makefile/ directly. This allows the user to
+reconfigure the package if necessary. You should <em/not/ configure
+the package and edit the generated <prgn/Makefile/! This makes it
+impossible for someone else to later reconfigure the package.
+<p>
+
+<sect1>Documenting your changes
+<p>
+
+Document your changes and updates to the source package properly in
+the <tt>debian/changelog</tt> file.
+<p>
+
+A copy of the file which will be installed in
+<tt>/usr/doc/<var/package//copyright</tt> should be in
+<tt>debian/copyright</tt>.
+<p>
+
+In non-experimental packages you may only use a format for
+<tt>debian/changelog</> which is supported by the most recent released
+version of <prgn/dpkg/. If your format is not supported and there is
+general support for it you should contact the <prgn/dpkg/ maintainer
+to have the parser script for your format included in the <prgn/dpkg/
+package. (You will need to agree that the parser and its
+manpage may be distributed under the GNU GPL, just as the rest of
+<prgn/dpkg/ is.)
+<p>
+
+<sect1>Error trapping in makefiles
+<p>
+
+When <prgn/make/ invokes a command in a makefile (including your
+package's upstream makefiles and the <tt>debian/rules</>) it does so
+using <tt/sh/. This means that <tt/sh/'s usual bad error handling
+properties apply: if you include a miniature script as one of the
+commands in your makefile you'll find that if you don't do anything
+about it then errors are not detected and <prgn/make/ will blithely
+continue after problems.
+<p>
+
+Every time you put more than one shell command (this includes using a
+loop) in a makefile command you <em/must/ make sure that errors are
+trapped. For simple compound commands, such as changing directory and
+then running a program, using <tt/&&/ rather than semicolon as
+a command separator is sufficient. For more complex commands
+including most loops and conditionals you must include a separate
+<tt/set -e/ command at the start of every makefile command that's
+actually one of these miniature shell scripts.
+<p>
+
+<sect1>Obsolete constructs and libraries
+<p>
+
+The include file <prgn/<varargs.h>/ is provided to support
+end-users compiling very old software; the library <tt/libtermcap/ is
+provided to support the execution of software which has been linked
+against it (either old programs or those such as Netscape which are
+only available in binary form).
+<p>
+
+Debian packages should be ported to include <prgn/<stdarg.h>/ and
+<tt/ncurses/ when they are built.
+<p>
+
+<chapt>The Operating System
+<p>
+
+<sect>Filesystem hierarchy
+<p>
+
+<sect1>Linux Filesystem Structure
+<p>
+
+The location of all installed files and directories must comply fully
+with the Linux Filesystem Structure (FSSTND). The latest version of
+this document can be found alongside this manual or on
+<ftpsite/tsx-11.mit.edu/ in
+<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>. Specific
+questions about following the standard may be asked on
+<prgn/debian-devel/, or referred to Daniel Quinlan, the FSSTND
+coordinator, at <email/quinlan@pathname.com/.
+<p>
+
+<sect1>Site-specific programs
+<p>
+
+As mandated by the FSSTND no package should place any files in
+<tt>/usr/local</>, either by putting them in the filesystem archive to
+be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer
+scripts.
+<p>
+
+However, the package should create empty directories below
+<tt>/usr/local</> so that the system administrator knows where to
+place site-specific files. These directories should be removed on
+package removal if they are empty.
+<p>
+
+Note, that this applies only to directories <em/below/
+<tt>/usr/local</>, not <em/in/ <tt>/usr/local</>. The directory
+<tt>/usr/local</> itself may only contain the sub-directories listed
+in FSSTND, section 4.8. However, you may create directories below them
+as you wish. You may not remove any of the directories listed in 4.8,
+even if you created them.
+<p>
+
+Since <tt>/usr/local</> may be mounted read-only from a remote server,
+these directories have to be created and removed by the <tt/postinst/
+and <tt/prerm/ maintainer scripts. These scripts must not fail if
+either of these operations fail. (In the future, it will be possible to
+tell <prgn/dpkg/ not to unpack files matching certain patterns, so
+that the directories can be included in the <tt/.deb/ packages and
+system administrators who do not wish these directories in /usr/local
+do not need to have them.)
+<p>
+
+For example, the <prgn/emacs/ package will contain
+<example>
+ mkdir -p /usr/local/lib/emacs/site-lisp || true
+</example>
+in the <tt/postinst/ script, and
+<example>
+ rmdir /usr/local/lib/emacs/site-lisp && \
+ rmdir /usr/local/lib/emacs || \
+ true
+</example>
+in the <tt/prerm/ script.
+<p>
+
+If you do create a directory in <tt>/usr/local</> for local additions
+to a package, you must ensure that settings in <tt>/usr/local</tt>
+take precedence over the equivalents in <tt>/usr</tt>.
+<p>
+
+The <tt>/usr/local</> directory itself and all the subdirectories
+created by the package should have permissions 2775 (group-writable
+and set-group-id) and be owned by <tt/root.staff/.
+<p>
+
+<sect>Users and groups
+<p>
+
+The Debian system can be configured to use either plain or shadow
+passwords.
+<p>
+
+Some user ids (UIDs) and group ids (GIDs) are reserved globally for
+use by certain packages. Because some packages need to include files
+which are owned by these users or groups, or need the ids compiled
+into binaries, these ids must be used on any Debian system only for
+the purpose for which they are allocated. This is a serious
+restriction, and we should avoid getting in the way of local
+administration policies. In particular, many sites allocate users
+and/or local system groups starting at 100.
+<p>
+
+Apart from this we should have dynamically allocated ids, which should
+by default be arranged in some sensible order--but the behaviour
+should be configurable.
+<p>
+
+No package except <tt>base-passwd</> may modify <tt>/etc/passwd</>,
+<tt>/etc/shadow</>, or <tt>/etc/group</>.
+<p>
+
+The UID and GID ranges are as follows:
+<taglist>
+<tag>0-99:
+<item>
+Globally allocated by the Debian project, must be the same on
+every Debian system. These ids will appear in the <tt>passwd</> and
+<tt>group</>
+files of all Debian systems, new ids in this range being added
+automatically as the <tt>base-passwd</> package is updated.
+<p>
+
+Packages which need a single statically allocated uid or gid should
+use one of these; their maintainers should ask the <tt>base-passwd</>
+maintainer for ids.
+<p>
+
+<tag>100-999:
+<item>
+Dynamically allocated system users and groups. Packages
+which need a user or group, but can have this user or group allocated
+dynamically and differently on each system, should use `<tt>adduser
+--system</>' to create the group and/or user. <prgn>adduser</> will
+check for the
+existence of the user or group, and if necessary choose an unused id
+based on the ranged specified in <tt>adduser.conf</>.
+<p>
+
+<tag>1000-29999:
+<item>
+Dynamically allocated user accounts. By default <prgn>adduser</>
+will choose UIDs and GIDs for user accounts in this range, though
+<tt>adduser.conf</> may be used to modify this behaviour.
+<p>
+
+<tag>30000-59999:
+<item>
+Reserved.
+<p>
+
+<tag>60000-64999:
+<item>
+Globally allocated by the Debian project, but only created on
+demand. The ids are allocated centrally and statically, but the actual
+accounts are only created on users' systems on demand.
+<p>
+
+These ids are for packages which are obscure or which require many
+statically-allocated ids. These packages should check for and create
+the accounts in <tt>/etc/passwd</> or <tt>/etc/group</> (using
+<prgn>adduser</> if it has this facility) if necessary. Packages
+which are likely to require further allocations should have a `hole'
+left after them in the allocation, to give them room to grow.
+<p>
+
+<tag>65000-65533:
+<item>
+Reserved.
+<p>
+
+<tag>65534:
+<item>
+User `<tt>nobody</>.'
+<p>
+
+<tag>65535:
+<item>
+<tt>(uid_t)(-1) == (gid_t)(-1)</>. NOT TO BE USED, because it is the
+error return sentinel value.
+<p>
+</taglist>
+
+<sect>Files
+<p>
+
+<sect1>Binaries
+<p>
+
+It is not allowed that two packages install programs with different
+functionality but with the same filenames. (The case of two programs
+having the same functionality but different implementations is handled via
+`alternatives.') If this case happens, one of the programs has to be
+renamed. The maintainers should report this to the developers' mailing
+and try to find a consensus about which package will have to be renamed.
+If a consensus can not be reached, <em>both</> programs must be renamed.
+<p>
+
+Generally the following compilation parameters should be used:
+<example>
+ CC = gcc
+ CFLAGS = -O2 -g -Wall # sane warning options vary between programs
+ LDFLAGS = # none
+ install -s # (or use strip on the files in debian/tmp)
+</example>
+<p>
+
+Note that all installed binaries should be
+stripped, either by using the <tt/-s/ flag to <prgn/install/, or by calling
+<prgn/strip/ on the binaries after they have been copied into
+<tt>debian/tmp</> but before the tree is made into a package.
+<p>
+
+The <tt/-g/ flag is useful on compilation so that you have available a
+full set of debugging symbols in your built source tree, in case
+anyone should file a bug report involving (for example) a core dump.
+<p>
+
+The <tt/-N/ flag should not be used. On a.out systems it may have
+been useful for some very small binaries, but for ELF it has no good
+effect.
+<p>
+
+It is up to the package maintainer to decide what compilation options
+are best for the package. Certain binaries (such as
+computationally-intensive programs) may function better with certain
+flags (<tt/-O3/, for example); feel free to use them. Please use good
+judgment here. Don't use flags for the sake of it; only use them if
+there is good reason to do so. Feel free to override the upstream
+author's ideas about which compilation options are best--they are
+often inappropriate for our environment.
+<p>
+
+<sect1>Libraries
+<p>
+
+All libraries must have a shared version in the lib package and a static
+version in the lib-dev package. The shared version must be compiled with
+<tt/-fPIC/, and the static version must not be. In other words, each
+<tt/*.c/ file is compiled twice.
+<p>
+
+You have to specify the gcc option <tt>-D_REENTRANT</tt> when building
+a library (either static or shared) to make the library compatible with
+LinuxThreads.
+<p>
+
+Note that all installed shared libraries should be stripped with
+<example>
+ strip --strip-unneeded <your-lib>
+</example>
+(The option `--strip-unneeded' makes <tt>strip</tt> remove only the symbols
+which aren't needed for relocation processing.)
+Shared libraries can function perfectly well when
+stripped, since the symbols for dynamic linking are in a separate part
+of the ELF object file.
+<p>
+
+Note that under some circumstances
+it may be useful to install a shared library unstripped, for example
+when building a separate package to support debugging.
+<p>
+
+Please make sure that you use only released versions of shared
+libraries to build your packages; otherwise other users will not be
+able to run your binaries properly. Producing source packages that
+depend on unreleased compilers is also usually a bad idea.
+<p>
+
+<sect1>Shared libraries
+<p>
+
+Packages involving shared libraries should be split up into several
+binary packages.
+<p>
+
+For a straightforward library which has a development environment and
+a runtime kit including just shared libraries you need to create two
+packages: <tt/<var/libraryname/<var/soname// (<var/soname/ is
+the shared object name of the shared library--it's the thing that has
+to match exactly between building an executable and running it for the
+dynamic linker to be able run the program; usually the <var/soname/
+is the major number of the library) and
+<tt/<var/libraryname/<var/soname/-dev/.
+<p>
+
+If you prefer only to support one development version at a time you
+may name the development package <tt/<var/libraryname/-dev/; otherwise
+you may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that
+the user only installs one development version at a time (after all,
+different development versions are likely to have the same header
+files in them, causing a filename clash if both are installed).
+Typically the development version will also need an exact version
+dependency on the runtime library, to make sure that compilation and
+linking happens correctly.
+<p>
+
+Packages which use the shared library should have a dependency on the
+name of the shared library package,
+<tt/<var/libraryname/<var/soname//. When the <var/soname/ changes you
+can have both versions of the library installed while moving from the
+old library to the new.
+<p>
+
+If your package has some run-time support programs which use the
+shared library you must <em/not/ put them in the shared library
+package. If you do that then you won't be able to install several
+versions of the shared library without getting filename clashes.
+Instead, either create a third package for the runtime binaries (this
+package might typically be named <tt/<var/libraryname/-runtime/--note
+the absence of the <var/soname/ in the package name) or if the
+development package is small include them in there.
+<p>
+
+If you have several shared libraries built from the same source tree
+you can lump them all together into a single shared library package,
+provided that you change all their <var/soname/s at once (so that you
+don't get filename clashes if you try to install different versions of
+the combined shared libraries package).
+<p>
+
+Follow the directions in the <em>Debian Packaging Manual</em> for
+putting the shared library in its package, and make sure you include a
+<tt/shlibs/ control area file with details of the dependencies for
+packages which use the library.
+<p>
+
+Shared libraries should <em/not/ be installed executable, since
+<prgn/ld.so/ does not require this and trying to execute a shared
+library results in a core dump.
+<p>
+
+<sect1 id=scripts>Scripts
+<p>
+
+All command scripts, including the package maintainer scripts inside
+the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming
+the shell to be used to interpret them.
+<p>
+
+In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>.
+<p>
+
+Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly
+start with <tt>set -e</> so that errors are detected. Every script
+<em/must/ use <tt/set -e/ or check the exit status of <em/every/
+command.
+<p>
+
+The standard shell interpreter `<tt>/bin/sh</tt>' may be a symbolic
+link to any POSIX compatible shell. Thus, shell scripts specifying
+`<tt>/bin/sh</tt>' as interpreter may only use POSIX features. If a
+script requires non-POSIX features from the shell interpreter, the
+appropriate shell has to be specified in the first line of the script
+(e.g., `<tt>#!/bin/bash</tt>') and the package has to depend on the
+package providing the shell (unless the shell package is marked
+`Essential', e.g., in the case of <prgn/bash/).
+<p>
+
+Restrict your script to POSIX features when possible so that it may
+use <tt>/bin/sh</tt> as its interpreter. If your script works with
+<prgn/ash/, it's probably POSIX compliant, but if you are in doubt,
+use <tt>/bin/bash</tt>.
+<p>
+
+Perl scripts should check for errors when making any system calls,
+including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and
+<tt/system/.
+<p>
+
+<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages.
+See <em>Csh Programming Considered Harmful</>, one of the
+<tt/comp.unix.*/ FAQs. It can be found on <ftpsite>rtfm.mit.edu</> in
+<ftppath>/pub/usenet-by-group/comp.unix.programmer/Csh_Programming_Considered_Harmful</>.
+If an upstream package comes with <prgn/csh/ scripts then you must
+make sure that they start with <tt>#!/bin/csh</tt> and make your
+package depend on the <prgn/c-shell/ virtual package.
+<p>
+
+Any scripts which create files in world-writable directories (e.g., in
+<tt>/tmp</tt>) have to use a mechanism which will fail if a file with
+the same name already exists.
+<p>
+
+The Debian base distribution provides the <prgn/tempfile/ and
+<prgn/mktemp/ utilities for use by scripts for this purpose.
+<p>
+
+<sect1>Symbolic links
+<p>
+
+In general, symbolic links within a toplevel directory should be
+relative, and symbolic links pointing from one toplevel directory into
+another should be absolute. (A toplevel directory is a sub-directory
+of the root directory `/'.)
+<p>
+
+In addition, symbolic links should be specified as short as possible,
+i.e., link targets like `foo/../bar' are deprecated.
+<p>
+
+Note that when creating a relative link using <prgn/ln/ it is not
+necessary for the target of the link to exist relative to the working
+directory you're running <prgn/ln/ from; nor is it necessary to change
+directory to the directory where the link is to be made. Simply
+include the string that should appear as the target of the link (this
+will be a pathname relative to the directory in which the link
+resides) as the first argument to <prgn/ln/.
+<p>
+
+For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things
+like:
+<example>
+ ln -fs gcc $(prefix)/bin/cc
+ ln -fs gcc debian/tmp/usr/bin/cc
+ ln -fs ../sbin/sendmail $(prefix)/bin/runq
+ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+</example>
+<p>
+
+A symbolic link pointing to a compressed file should always have the
+same file extension as the referenced file. (For example, if a file
+`<tt>foo.gz</tt>' is referenced by a symbolic link, the filename of
+the link has to end with `<tt>.gz</tt>' too, as in `bar.gz.')
+<p>
+
+<sect1>Device files
+<p>
+
+No package may include device files in the package file tree.
+<p>
+
+If a package needs any special device files that are not included in
+the base system, it has to call <prgn/makedev/ in the <tt/postinst/
+script, after asking the user for permission to do so.
+<p>
+
+No package should remove any device files in the <tt/postrm/ or any
+other script. This is left to the system administrator.
+<p>
+
+Debian uses the serial devices <tt>/dev/tty*</tt>. Programs using the
+old <tt>/dev/cu*</tt> devices should be changed to use
+<tt>/dev/tty*</tt>.
+<p>
+
+<sect1>Configuration files
+<p>
+
+Any configuration files created or used by your package should reside
+in <tt>/etc</tt>. If there are several you should consider creating a
+subdirectory named after your package.
+<p>
+
+It is almost certain that any file in <tt>/etc</tt> that is in your
+package's filesystem archive should be listed in <prgn/dpkg/'s
+<tt/conffiles/ control area file. (See the <em>Debian Packaging
+Manual</em>).
+<p>
+
+Only packages that are tagged <em/conflicting/ with each other may
+specify the same file as <tt/conffile/. A package may not modify a
+configuration file of another package.
+<p>
+
+If two or more packages use the same configuration file, one of these
+packages has to be defined as <em/owner/ of the configuration file,
+i.e., it has to list the file as <tt/conffile/ and has to provide
+a program that modifies the configuration file.
+<p>
+
+The other packages have to depend on the <em/owner/ package and use
+that program to update the configuration file.
+<p>
+
+Sometimes it's appropriate to build a new package, which just provides
+the basic <em/infrastructure/ for the other packages and which manages
+the shared configuration files. (Check out the <prgn/sgml-base/
+package as an example.)
+<p>
+
+Files in <tt>/etc/skel</> will automatically be copied into new user
+accounts by <prgn/adduser/. They should not be referenced there by
+any program.
+<p>
+
+Therefore, if a program needs a dotfile to exist in advance in
+<tt/$HOME/ to work sensibly that dotfile should be installed in
+<tt>/etc/skel</> (and listed in conffiles, if it is not generated and
+modified dynamically by the package's installation scripts).
+<p>
+
+However, programs that require dotfiles in order to operate sensibly
+(dotfiles that they do not create themselves automatically, that is)
+are a bad thing, and programs should be configured by the Debian
+default installation as close to normal as possible.
+<p>
+
+Therefore, if a program in a Debian package needs to be configured in
+some way in order to operate sensibly that configuration should be
+done in a site-wide global configuration file elsewhere in
+<tt>/etc</>. Only if the program doesn't support a site-wide default
+configuration and the package maintainer doesn't have time to add it
+should a default per-user file be placed in <tt>/etc/skel</>.
+<p>
+
+<tt>/etc/skel</> should be as empty as we can make it. This is
+particularly true because there is no easy mechanism for ensuring that
+the appropriate dotfiles are copied into the accounts of existing
+users when a package is installed.
+<p>
+
+Ideally the sysadmin should not have to do any configuration other
+than that done (semi-)automatically by the <tt/postinst/ script.
+<p>
+
+<sect1>Permissions and owners
+<p>
+
+The rules in this section are guidelines for general use. If
+necessary you may deviate from the details below. However, if you do
+so you must make sure that what is done is secure and you must try to
+be as consistent as possible with the rest of the system. You should
+probably also discuss it on <prgn/debian-devel/ first.
+<p>
+
+Files should be owned by <tt/root.root/, and made writable only by
+the owner and universally readable (and executable, if appropriate).
+<p>
+
+Directories should be mode 755 or (for group-writability) mode 2775.
+The ownership of the directory should be consistent with its mode--if
+a directory is mode 2775, it should be owned by the group that needs
+write access to it.
+<p>
+
+Setuid and setgid executables should be mode 4755 or 2755
+respectively, and owned by the appropriate user or group. They should
+not be made unreadable (modes like 4711 or 2711 or even 4111); doing
+so achieves no extra security, because anyone can find the binary in
+the freely available Debian package--it is merely inconvenient. For
+the same reason you should not restrict read or execute permissions on
+non-set-id executables.
+<p>
+
+Some setuid programs need to be restricted to particular sets of
+users, using file permissions. In this case they should be owned by
+the uid to which they are set-id, and by the group which should be
+allowed to execute them. They should have mode 4754; there is no
+point in making them unreadable to those users who must not be allowed
+to execute them.
+<p>
+
+Do not arrange that the system administrator can only reconfigure the
+package to correspond to their local security policy by changing the
+permissions on a binary. Ordinary files installed by <prgn/dpkg/ (as
+opposed to conffiles and other similar objects) have their permissions
+reset to the distributed permissions when the package is reinstalled.
+Instead you should consider (for example) creating a group for people
+allowed to use the program(s) and making any setuid executables
+executable only by that group.
+<p>
+
+If you need to create a new user or group for your package there are
+two possibilities. Firstly, you may need to make some files in the
+binary package be owned by this user or group, or you may need to
+compile the user or group id (rather than just the name) into the
+binary (though this latter should be avoided if possible). In this
+case you need a statically allocated id.
+<p>
+
+You must ask for a user or group id from the base system maintainer,
+and must not release the package until you have been allocated one.
+Once you have been allocated one you must make the package depend on a
+version of the base system with the id present in <tt>/etc/passwd</tt>
+or <tt>/etc/group</tt>, or alternatively arrange for your package to
+create the user or group itself with the correct id (using
+<tt/adduser/) in its pre- or post-installation script (the latter is
+to be preferred if it is possible).
+<p>
+
+On the other hand, the program may able to determine the uid or gid
+from the group name at runtime, so that a dynamic id can be used. In
+this case you must choose an appropriate user or group name,
+discussing this on <prgn/debian-devel/ and checking with the base
+system maintainer that it is unique and that they do not wish you to
+use a statically allocated id instead. When this has been checked you
+must arrange for your package to create the user or group if necessary
+using <prgn/adduser/ in the pre- or post-installation script (again,
+the latter is to be preferred if it is possible).
+<p>
+
+Note that changing the numeric value of an id associated with a name
+is very difficult, and involves searching the filesystem for all
+appropriate files. You need to think carefully whether a static or
+dynamic id is required, since changing your mind later will cause
+problems.
+<p>
+
+<sect id="sysvinit">System run levels
+<p>
+
+<sect1>Introduction
+<p>
+
+The <tt>/etc/init.d</> directory contains the scripts executed by
+<prgn/init/ at boot time and when init state (or `runlevel') is
+changed (see <manref name=init section=8>). <p>
+
+These scripts are being referenced by symbolic links in the
+<tt>/etc/rc<var/n/.d</> directories. When changing runlevels,
+<prgn/init/ looks in the directory <tt>/etc/rc<var/n/.d</> for the
+scripts it should execute, where <var/n/ is the runlevel that is being
+changed to, or `S' for the boot-up scripts. <p>
+
+The names of the links all have the form <tt/S<var/mm/<var/script// or
+<tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and
+<var/script/ is the name of the script (this should be the same as the
+name of the actual script in <tt>/etc/init.d</>.
+
+When <prgn/init/ changes runlevel first the targets of the links whose
+names starting with a <tt/K/ are executed, each with the single
+argument <tt/stop/, followed by the scripts prefixed with an <tt/S/,
+each with the single argument <tt/start/. The <tt/K/ links are
+responsible for killing services and the <tt/S/ link for starting
+services upon entering the runlevel.
+<p>
+
+For example, if we are changing from runlevel 2 to runlevel 3, init
+will first execute all of the <tt/K/ prefixed scripts it finds in
+<tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts. The
+links starting with <tt/K/ will cause the referred-to file to be
+executed with an argument of <tt/stop/, and the <tt/S/ links with an
+argument of <tt/start/.
+<p>
+
+The two-digit number <var/mm/ is used to decide which order to start
+and stop things in--low-numbered links have their scripts run first.
+For example, the <tt/K20/ scripts will be executed before the <tt/K30/
+scripts. This is used when a certain service must be started before
+another. For example, the name server <prgn/bind/ might need to be
+started before the news server <prgn/inn/ so that <prgn/inn/ can set
+up its access lists. In this case, the script that starts <prgn/bind/
+should have a lower number than the script that starts <prgn/inn/ so
+that it runs first:
+<example>
+ /etc/rc2.d/S17bind
+ /etc/rc2.d/S70inn
+</example>
+
+<sect1>Writing the scripts
+<p>
+
+Packages can and should place scripts in <tt>/etc/init.d</> to start
+or stop services at boot time or during a change of runlevel. These
+scripts should be named <tt>/etc/init.d/<var/package/</>, and they
+should accept one argument, saying what to do:
+
+<taglist>
+<tag><tt/start/
+<item>start the service,
+<p>
+<tag><tt/stop/
+<item>stop the service,
+<p>
+<tag><tt/restart/
+<item>stop and restart the service,
+<p>
+<tag><tt/reload/
+<item>cause the configuration of the service to be
+reloaded without actually stopping and restarting the service,
+<p>
+<tag><tt/force-reload/
+<item>cause the configuration to be reloaded if the service supports
+this, otherwise restart the service.
+</taglist>
+
+The <tt/start/, <tt/stop/, <tt/restart/, and <tt/force-reload/ options
+must be supported by all scripts in <tt>/etc/init.d</>, the
+<tt/reload/ option is optional.
+<p>
+
+The <tt/init.d/ scripts should ensure that they will behave sensibly
+if invoked with <tt/start/ when the service is already running, or
+with <tt/stop/ when it isn't, and that they don't kill
+unfortunately-named user processes. The best way to achieve this is
+usually to use <prgn/start-stop-daemon/.
+<p>
+
+If a service reloads its configuration automatically (as in the case
+of <prgn/cron/, for example), the <tt/reload/ option of the
+<tt/init.d/ script should behave as if the configuration has been
+reloaded successfully.
+<p>
+
+These scripts should not fail obscurely when the configuration files
+remain but the package has been removed, as the default in <prgn/dpkg/
+is to leave configuration files on the system after the package has
+been removed. Only when it is executed with the <tt/--purge/ option
+will dpkg remove configuration files. Therefore, you should include a
+<tt/test/ statement at the top of the script, like this:
+<example>
+ test -f <var/program-executed-later-in-script/ || exit 0
+</example>
+
+<sect1>Managing the links
+<p>
+
+A program is provided, <prgn/update-rc.d/, to make it easier for
+package maintainers to arrange for the proper creation and removal of
+<tt>/etc/rc<var/n/.d</> symbolic links from their <tt/postinst/ and
+<tt/postrm/ scripts.
+<p>
+
+You should use this script to make changes to <tt>/etc/rc<var/n/.d</>
+and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in
+the actual archive.
+<p>
+
+By default <prgn/update-rc.d/ will start services in each of the
+multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt
+runlevel (0), the single-user runlevel (1) and the reboot runlevel
+(6). The system administrator will have the opportunity to customize
+runlevels by simply adding, moving, or removing the symbolic links in
+<tt>/etc/rc<var/n/.d</>.
+<p>
+
+To get the default behaviour for your package, put in your
+<tt/postinst/ script
+<example>
+ update-rc.d <var/package/ default >/dev/null
+</example>
+and in your <tt/postrm/
+<example>
+ if [ purge = "$1" ]; then
+ update-rc.d <var/package/ remove >/dev/null
+ fi
+</example>
+<p>
+
+This will use a default sequence number of 20. If it does not matter
+when or in which order the script is run, use this default. If it
+does, then you should talk to the maintainer of the <prgn/sysvinit/
+package or post to <tt>debian-devel</>, and they will help you choose
+a number.
+<p>
+
+For more information about using <tt/update-rc.d/, please consult its
+manpage <manref name=update-rc.d section=8>.
+<p>
+
+<sect1>Boot-time initialisation
+<p>
+
+There is another directory, <tt>/etc/rc.boot</>, which contains
+scripts which are run once per machine boot. This facility is
+provided for initialisation of hardware devices, cleaning up of
+leftover files, and so forth.
+<p>
+
+For example, the <prgn/kbd/ package provides a script here for
+initialising the keyboard layout and console font and mode.
+<p>
+
+The files in <tt>/etc/rc.boot</> should <em/not/ be links into
+<tt>/etc/init.d</>--they should be the scripts themselves.
+<p>
+
+<tt/rc.boot/ should <em/not/ be used for starting general-purpose
+daemons and similar activities. This should be done using the
+<tt/rc<var/n/.d/ scheme, above, so that the services can be started
+and stopped cleanly when the runlevel changes or the machine is to be
+shut down or rebooted.
+<p>
+
+<sect1>Notes
+<p>
+
+<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
+the <tt/.deb/ filesystem archive! <em/This will cause problems!/
+You should create them with <prgn/update-rc.d/, as above.
+<p>
+
+<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in
+<prgn/dpkg/'s conffiles list! <em/This will cause problems!/ <em/Do/,
+however, include the <tt>/etc/init.d</> scripts in conffiles. (This
+is important since we want to give the local system administrator the
+chance to adapt the scripts to the local system--e.g., to disable a
+service without deinstalling the package, or to specify some special
+command line options when starting a service--while making sure her
+changes aren't lost during the next package upgrade.) <p>
+
+<sect1>Example
+<p>
+
+The <prgn/bind/ DNS (nameserver) package wants to make sure that the
+nameserver is running in multiuser runlevels, and is properly shut
+down with the system. It puts a script in <tt>/etc/init.d</>, naming
+the script appropriately <tt/bind/. As you can see, the script
+interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/
+signal (causing it to reload its configuration); this way the user can
+say <tt>/etc/init.d/bind reload</> to reload the name server.
+<p>
+
+<example>
+ #!/bin/sh
+ #
+ # Original version by Robert Leslie <rob@mars.org>, edited by iwj and cs
+
+ test -x /usr/sbin/named || exit 0
+
+ case "$1" in
+ start)
+ echo -n "Starting domain name service: named"
+ start-stop-daemon --start --quiet --exec /usr/sbin/named
+ echo "."
+ ;;
+ stop)
+ echo -n "Stopping domain name service: named"
+ start-stop-daemon --stop --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ echo "."
+ ;;
+ restart)
+ echo -n "Restarting domain name service: named"
+ start-stop-daemon --stop --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ start-stop-daemon --start --verbose --exec /usr/sbin/named
+ echo "."
+ ;;
+ force-reload|reload)
+ echo -n "Reloading configuration of domain name service: named"
+ start-stop-daemon --stop --signal 1 --quiet \
+ --pidfile /var/run/named.pid --exec /usr/sbin/named
+ echo "."
+ ;;
+ *)
+ echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
+ exit 1
+ ;;
+ esac
+
+ exit 0
+</example>
+<p>
+
+Another example on which to base your <tt>/etc/init.d</> scripts is in
+<tt>/etc/init.d/skeleton</>.
+<p>
+
+If this package is happy with the default setup from
+<prgn/update-rc.d/, namely an ordering number of 20 and having named
+running in all runlevels, it can say in its <tt/postinst/:
+<example>
+ update-rc.d bind default >/dev/null
+</example>
+And in its <tt/postrm/, to remove the links when the package is purged:
+<example>
+ if [ purge = "$1" ]; then
+ update-rc.d acct remove >/dev/null
+ fi
+</example>
+<p>
+
+<sect>Cron jobs
+<p>
+
+Packages may not touch the configuration file <tt>/etc/crontab</>, nor
+may they modify the files in <tt>/var/spool/cron/crontabs</>.
+<p>
+
+If a package wants to install a job that has to be executed via
+cron, it should place a file with the name if the package in one
+of the following directories:
+<example>
+ /etc/cron.daily
+ /etc/cron.weekly
+ /etc/cron.monthly
+</example>
+As these directory names say, the files within them are executed on
+a daily, weekly, or monthly basis, respectively.
+<p>
+
+If a certain job has to be executed more frequently than `daily,' the
+package should install a file
+<tt>/etc/cron.d/<package-name></tt> tagged as configuration
+file. This file uses the same syntax as <tt>/etc/crontab</tt> and is
+processed by <prgn/cron/ automatically. (Note, that scripts in the
+<tt>/etc/cron.d</tt> directory are not handled by
+<prgn/anacron/. Thus, you should only use this directory for jobs
+which may be skipped if the system is not running.)
+<p>
+
+All files installed in any of these directories have to be scripts
+(shell scripts, Perl scripts, etc.) so that they can easily be
+modified by the local system administrator. In addition, they have to
+be registered as configuration file.
+<p>
+
+The scripts in these directories have to check, if all necessary
+programs are installed before they try to execute them. Otherwise,
+problems will arise when a package was removed (but not purged), since
+the configuration files are kept on the system in this situation.
+<p>
+
+<sect>Console messages
+<p>
+
+This section describes different formats for messages written to
+standard output by the <tt>/etc/init.d</> scripts. The intent is to
+improve the consistency of Debian's startup and shutdown look and
+feel.
+<p>
+
+Please look very careful at the details. We want to get the messages
+to look exactly the same way concerning spaces, punctuation, and case
+of letters.
+<p>
+
+Here is a list of overall rules that you should use when you create output
+messages. They can be useful if you have a non-standard message that isn't
+covered in the sections below.
+<p>
+
+<list>
+<item>
+ Every message should cover one line, start with a capital letter and
+ end with a period `.'.
+<p>
+
+<item>
+ If you want to express that the computer is working on something
+ (performing a specific task, not starting or stopping a program), we
+ use an ``ellipsis'', namely three dots `...'. Note that we don't insert
+ spaces in front of or behind the dots.
+ If the task has been completed we write `done.' and a line feed.
+<p>
+
+<item>
+ Design your messages as if the computer is telling you what he is
+ doing (let him be polite :-) but don't mention ``him'' directly.
+ For example, if you think of saying
+<example>
+ I'm starting network daemons: nfsd mountd.
+</example>
+ just say
+<example>
+ Starting network daemons: nfsd mountd.
+</example>
+</list>
+<p>
+
+The following formats must be used
+<p>
+
+<list>
+<item>
+ when daemons get started.
+<p>
+
+ Use this format if your script starts one or more daemons.
+ The output should look like this (a single line, no leading spaces):
+<example>
+ Starting <description>: <daemon-1> <daemon-2> <...> <daemon-n>.
+</example>
+ The <description> should describe the subsystem the daemon or set of
+ daemons are part of, while <daemon-1> up to <daemon-n>
+ denote each daemon's name (typically the file name of the program).
+<p>
+
+ For example, the output of /etc/init.d/lpd would look like:
+<example>
+ Starting printer spooler: lpd.
+</example>
+<p>
+
+ This can be achieved by saying
+<example>
+ echo -n "Starting printer spooler: lpd"
+ start-stop-daemon --start --quiet lpd
+ echo "."
+</example>
+ in the script. If you have more than one daemon to start, you should
+ do the following:
+<example>
+ echo -n "Starting remote filesystem services:"
+ echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
+ echo -n " mountd"; start-stop-daemon --start --quiet mountd
+ echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
+ echo "."
+</example>
+ This makes it possible for the user to see what takes so long and when
+ the final daemon has been started. Please be careful where to put spaces:
+ In the example above the system administrator can easily comment out
+ a line if he don't wants to start a specific daemon, while the displayed
+ message still looks good.
+<p>
+
+<item>
+ when something needs to be configured.
+<p>
+
+ If you have to set up different parameters of the system upon boot up,
+ you can use this format:
+<example>
+ Setting <parameter> to `<value>'.
+</example>
+<p>
+
+ You can use the following echo statement to get the quotes right:
+<example>
+ echo "Setting DNS domainname to \`"value"'."
+</example>
+<p>
+
+ Note that the left quotation mark (`) is different from the right (').
+
+<item>
+ when a daemon is stopped.
+<p>
+
+ When you stop a daemon you should issue a message similar to the startup
+ message, except that `Starting' is replaced with `Stopping'.
+<p>
+
+ So stopping the printer daemon will like like this:
+<example>
+ Stopping printer spooler: lpd.
+</example>
+
+<item>
+ when something is executed.
+<p>
+
+ There a several examples where you have to run a program at system
+ startup or shutdown to perform a specific task. For example, setting
+ the system's clock via `netdate' or killing all processes when the
+ system comes down. Your message should like this:
+<example>
+ Doing something very useful...done.
+</example>
+ You should print the `done.' right after the job has been completed,
+ so that the user gets informed why he has to wait. You can get this
+ behaviour by saying
+<example>
+ echo -n "Doing something very useful..."
+ do_something
+ echo "done."
+</example>
+ in your script.
+
+<item>
+ when the configuration is reloaded.
+<p>
+
+ When a daemon is forced to reload its configuration files you
+should use the following format:
+<example>
+ Reloading <daemon's-name> configuration...done.
+</example>
+
+<item>
+ when none of the above rules apply.
+<p>
+
+ If you have to print a message that doesn't fit into the styles described
+ above, you can use something appropriate, but please have a look at the
+ overall rules listed above.
+</list>
+<p>
+
+<sect>Menus
+<p>
+
+The Debian <tt/menu/ packages provides a unique interface between
+packages providing applications and documents, and <em/menu programs/
+(either X window managers or text-based menu programs as
+<prgn/pdmenu/).
+<p>
+
+All packages that provide applications that need not be passed any
+special command line arguments for normal operation should register a
+menu entry for those applications, so that users of the <tt/menu/
+package will automatically get menu entries in their window managers,
+as well in shells like <tt/pdmenu/.
+<p>
+
+Please refer to the <em>Debian Menu System</em> document that comes
+with the <tt/menu/ package for information about how to register your
+applications and web documents.
+<p>
+
+<sect>Keyboard configuration
+<p>
+
+To achieve a consistent keyboard configuration (i.e., all applications
+interpret a keyboard event the same way) all programs in the Debian
+distribution have to be configured to comply with the following
+guidelines.
+<p>
+
+Here is a list that contains certain keys and their interpretation:
+
+<taglist>
+<tag><tt/<--/
+<item>delete the character to the left of the cursor
+<p>
+<tag><tt/Delete/
+<item>delete the character to the right of the cursor
+<p>
+<tag><tt/Control+H/
+<item>emacs: the help prefix
+</taglist>
+
+The interpretation of any keyboard events should be independent of the
+terminal that's used (either the console, X windows, rlogin/telnet
+session, etc.).
+<p>
+
+The following list explains how the different programs should be set
+up to achieve this:
+<p>
+
+<list compact>
+<item>`<tt><--</tt>' generates KB_Backspace in X.
+<p>
+<item>`<tt/Delete/' generates KB_Delete in X.
+<p>
+<item>X translations are set up to make KB_Backspace generate ASCII DEL,
+ and to make KB_Delete generate <tt>ESC [ 3 ~</tt> (this is the vt220 escape
+ code for the `delete character' key). This must be done by loading
+ the resources using xrdb on all local X displays, not using the
+ application defaults, so that the translation resources used
+ correspond to the xmodmap settings.
+<p>
+<item>The Linux console is configured to make `<tt><--</tt>' generate DEL, and
+ `Delete' generate <tt>ESC [ 3 ~</tt> (this is the case at the moment).
+<p>
+<item>X applications are configured so that Backspace deletes left, and
+ Delete deletes right. Motif applications already work like this.
+<p>
+<item>stty erase <tt>^?</tt> .
+<p>
+<item>The `xterm' terminfo entry should have <tt>ESC [ 3 ~</tt> for kdch1, just
+ like TERM=linux and TERM=vt220.
+<p>
+<item>Emacs is programmed to map KB_Backspace or the `stty erase'
+ character to delete-backward-char, and KB_Delete or kdch1 to
+ delete-forward-char, and <tt>^H</tt> to help as always.
+<p>
+<item>Other applications use the `stty erase' character and kdch1 for the
+ two delete keys, with ASCII DEL being `delete previous character'
+ and kdch1 being `delete character under cursor'.
+</list>
+<p>
+
+This will solve the problem except for:
+<p>
+
+<list compact>
+<item>Some terminals have a <tt><--</tt> key that cannot be made to produce
+ anything except <tt>^H</tt>. On these terminals Emacs help will be
+ unavailable on <tt>^H</tt> (assuming that the `stty erase' character takes
+ precedence in Emacs, and has been set correctly). M-x help or F1
+ (if available) can be used instead.
+<p>
+<item>Some operating systems use <tt>^H</tt> for stty erase. However, modern
+ telnet versions and all rlogin versions propagate stty settings,
+ and almost all UNIX versions honour stty erase. Where the stty
+ settings are not propagated correctly things can be made to work by
+ using stty manually.
+<p>
+<item>Some systems (including previous Debian versions) use xmodmap to
+ arrange for both <tt><--</tt> and Delete to generate KB_Delete). We can
+ change the behaviour of their X clients via the same X resources
+ that we use to do it for our own, or have our clients be configured
+ via their resources when things are the other way around. On
+ displays configured like this Delete will not work, but <tt><--</tt> will.
+<p>
+<item>Some operating systems have different kdch1 settings in their
+ terminfo for xterm and others. On these systems the Delete key
+ will not work correctly when you log in from a system conforming to
+ our policy, but <tt><--</tt> will.
+</list>
+<p>
+
+<sect>Environment variables
+<p>
+
+No program may depend on environment variables to get reasonable
+defaults. (That's because these environment variables would have to
+be set in a system-wide configuration file like /etc/profile, which is
+not supported by all shells.)
+<p>
+
+If a program should depend on environment variables for its
+configuration, the program has to be changed to fall back to a
+reasonable default configuration if these environment variables are
+not present. If this cannot be done easily (e.g., if the source code
+of a non-free program is not available), the program should be
+replaced by a small `wrapper' shell script which sets the environment
+variables and calls the original program.
+<p>
+
+Here is an example of a wrapper script for this purpose:
+
+<example>
+#!/bin/sh
+BAR=/var/lib/fubar
+export BAR
+exec /usr/lib/foo/foo "$@"
+</example>
+<p>
+
+Furthermore, as <tt>/etc/profile</tt> is a configuration file of the
+<prgn/bash/ package, no other package may put any environment
+variables or other commands into that file.
+<p>
+
+
+
+<chapt>Customized programs
+<p>
+
+<sect id="arch-spec">Architecture specification strings
+<p>
+
+If a program needs to specify an <em>architecture specification
+string</> in some place, the following format has to be used:
+<example>
+ <arch>-linux
+</example>
+where `<arch>' is one of the following: i386, alpha, arm, m68k,
+powerpc, sparc.
+<p>
+
+Note, that we don't want to use `<arch>-debian-linux' to apply
+to the rule `architecture-vendor-os' since this would make our
+programs incompatible to other Linux distributions. Also note, that we
+don't use `<arch>-unknown-linux', since the `unknown' does not
+look very good.
+<p>
+
+<sect>Daemons
+<p>
+
+The configuration files <tt>/etc/services</tt>,
+<tt>/etc/protocols</tt>, and <tt>/etc/rpc</tt> are managed by the
+<prgn/netbase/ package and may not be modified by other packages.
+<p>
+
+If a package requires a new entry in one of these files, the
+maintainer has to get in contact with the <prgn/netbase/ maintainer,
+who will add the entries and release a new version of the
+<prgn/netbase/ package.
+<p>
+
+The configuration file <tt>/etc/inetd.conf</tt> may be modified by the
+package's scripts only via the <prgn/update-inetd/ script or the
+<prgn/DebianNet.pm/ Perl module.
+<p>
+
+If a package wants to install an example entry into
+<tt>/etc/inetd.conf</tt>, the entry has to be preceded with exactly
+one hash character (#). Such lines are treated as `commented out by
+user' by the <prgn/update-inetd/ script and are not changed or
+activated during a package updates.
+<p>
+
+<sect>Editors and pagers
+<p>
+
+Some programs have the ability to launch an editor or pager
+program to edit or display a text document. Since there are
+lots of different editors and pagers available in the Debian
+distribution, the system administrator and each user should have
+the possibility to choose his/her preferred editor and pager.
+<p>
+
+In addition, every program should choose a good default
+editor/pager if none is selected by the user or system
+administrator.
+<p>
+
+Thus, every program that launches an editor or pager has to use the
+EDITOR or PAGER environment variables to determine the editor/pager
+the user wants to get started. If these variables are not set, the
+programs `/usr/bin/editor' and `/usr/bin/pager' have to be used,
+respectively.
+<p>
+
+These two files are managed through `alternatives.' That is,
+every package providing an editor or pager has to call the
+`update-alternatives' script to register these programs.
+<p>
+
+If it is very hard to adapt a program to make us of the EDITOR
+and PAGER variable, that program should be configured to use
+`/usr/bin/sensible-editor' and `/usr/bin/sensible-pager' as
+editor or pager program, respectively. These are two scripts
+provided in the Debian base system that check the EDITOR and
+PAGER variables and launches the appropriate program or
+falls back to `/usr/bin/editor' and `/usr/bin/pager',
+automatically.
+<p>
+
+Since the Debian base system already provides an editor and
+a pager program, there is no need for a package to depend on
+`editor' and `pager', nor is it necessary for a package to
+provide such virtual packages.
+<p>
+
+<sect id="web-appl">Web servers and applications
+<p>
+
+This section describes the locations and URLs that have to be used by
+all web servers and web application in the Debian system.
+<p>
+
+<enumlist>
+<item>Cgi-bin executable files are installed in the directory
+<example>
+ /usr/lib/cgi-bin/<cgi-bin-name>
+</example>
+and can be referred to as
+<example>
+ http://localhost/cgi-bin/<cgi-bin-name>
+</example>
+<p>
+
+<item>Access to html documents
+<p>
+
+Html documents for a package are stored in /usr/doc/<package> and can be
+referred to as
+<example>
+ http://localhost/doc/<package>/<filename>
+</example>
+<p>
+
+<item>Web Document Root
+<p>
+
+Web Applications should try to avoid storing files in the Web Document Root.
+Instead use the /usr/doc/<package> directory for documents and
+register the Web Application via the menu package. If access to the
+web-root is unavoidable then use
+<example>
+ /var/www
+</example>
+as the Document Root. This might be just a symbolic link to the location where the
+sysadmin has put the real document root.
+<p>
+
+</enumlist>
+<p>
+
+<sect>Mail transport agents
+<p>
+
+Debian packages which process electronic mail, whether
+mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/
+make sure that they are compatible with the configuration decisions
+below. Failure to do this may result in lost mail, broken <tt/From:/
+lines, and other serious brain damage!
+<p>
+
+The mail spool is <tt>/var/spool/mail</> and the interface to send a
+mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND). The
+mail spool is part of the base system and not part of the MTA package.
+<p>
+
+All Debian MUAs and MTAs have to use the <tt>maillock</tt> and
+<tt>mailunlock</tt> functions provided by the <tt>liblockfile</tt>
+packages to lock and unlock mail boxes. These functions implement
+a NFS-safe locking mechanism. (It is ok if MUAs and MTAs don't link
+against liblockfile but use a <em/compatible/ mechanism. Please
+compare the mechanisms very carefully!)
+<p>
+
+Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has
+chosen otherwise. A MUA may remove a mailbox (unless it has
+nonstandard permissions) in which case the MTA or another MUA must
+recreate it if needed. Mailboxes must be writable by group mail.
+<p>
+
+The mail spool is 2775 <tt/mail.mail/, and MUAs need to be setgid
+mail to do the locking mentioned above (and obviously need to avoid
+accessing other users' mailboxes using this privilege).
+<p>
+
+<tt>/etc/aliases</> is the source file for the system mail aliases
+(e.g., postmaster, usenet, etc.)--it is the one which the sysadmin
+and <tt/postinst/ scripts may edit. After <tt>/etc/aliases</> is edited
+the program or human editing it must call <prgn/newaliases/. All MTA
+packages should come with a <prgn/newaliases/ program, even if it does
+nothing, but older MTA packages do not do this so programs should not
+fail if <prgn/newaliases/ cannot be found.
+<p>
+
+The convention of writing <tt/forward to <var/address// in the mailbox
+itself is not supported. Use a <tt/.forward/ file instead.
+<p>
+
+The location for the <prgn/rmail/ program used by UUCP for incoming
+mail is <tt>/usr/sbin/rmail</>, as per the FSSTND. Likewise,
+<prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in
+<tt>/usr/sbin/rsmtp</> if it is supported.
+<p>
+
+If you need to know what name to use (for example) on outgoing news
+and mail messages which are generated locally, you should use the file
+<tt>/etc/mailname</>. It will contain the portion after the username
+and <tt/@/ (at) sign for email addresses of users on the machine
+(followed by a newline).
+<p>
+
+A package should check for the existence of this file. If it exists
+it should use it without comment. (An MTA's prompting
+configuration script may wish to prompt the user even if it finds this
+file exists.) If it does not exist it should prompt the user
+for the value and store it in <tt>/etc/mailname</> as well as using it
+in the package's configuration. The prompt should make it clear that
+the name will not just be used by that package. For example, in this
+situation the INN package says:
+<example>
+ Please enter the `mail name' of your system. This is the hostname
+ portion of the address to be shown on outgoing news and mail messages.
+ The default is <var/syshostname/, your system's host name.
+ Mail name [`<var/syshostname/']:
+</example>
+where <var/syshostname/ is the output of <tt/hostname --fqdn/.
+<p>
+
+<sect>News system configuration
+<p>
+
+All the configuration files related to the NNTP (news) servers and
+clients should be located under <tt>/etc/news</tt>.
+<p>
+
+There are some configuration issues that apply to a number of
+news clients and server packages on the machine. These are:
+
+<taglist>
+<tag>/etc/news/organization
+<item>A string which shall appear as the
+ organization header for all messages posted
+ by NNTP clients on the machine
+<p>
+<tag>/etc/news/server
+<item>Contains the FQDN of the upstream NNTP
+ server, or localhost if the local machine is
+ an NNTP server.
+</taglist>
+
+Other global files may be added as required for cross-package news
+configuration.
+<p>
+
+<sect>Programs for the X Windows system
+<p>
+
+Some programs can be configured with or without support for X Windows.
+Typically these binaries produced when configured for X will need the
+X shared libraries to run.
+<p>
+
+Such programs should be configured <em/with/ X support, and should
+declare a dependency on <tt/xlib6g/ (for the X11R6 libraries).
+Users who wish to use the program can install just the relatively
+small <tt/xlib6g/ package, and do not need to install the whole of X.
+<p>
+
+Do not create two versions (one with X support and one without) of
+your package.
+<p>
+
+<em>Application defaults</em> files have to be installed in the
+directory <tt>/usr/X11R6/lib/X11/app-defaults/</tt>. They are
+considered as part of the program code. Thus, they should not be
+modified and should not be tagged as <em>conffile</em>. If the local
+system administrator wants to customise X applications globally, the
+file <tt>/etc/X11/Xresources</tt> should be used.
+<p>
+
+If you package a program that requires a non-free Motif library, it
+would be good if you can provide a "foo-smotif" and a "foo-dmotif"
+package, containing a (against Motif libraries) statically and a
+dynamically linked version, respectively. This way, users without
+Motif can use the package too, while users that have Motif installed
+get the advantages of a dynamically linked version.
+<p>
+
+However, if your package works reliably with lesstif, you should
+package it with lesstif, and not with Motif at all.
+<p>
+
+Note, that packages that require non-free Motif libraries can't go
+into the main section. If your package is free otherwise, it should go
+into contrib. Otherwise it has to go into non-free.
+<p>
+
+<sect>Emacs lisp programs
+<p>
+
+Please refer to the `Debian Emacs Policy' (documented in
+<tt>debian-emacs-policy.gz</tt> of the <prgn/emacsen-common/ package)
+for details of how to package emacs lisp programs.
+<p>
+
+<sect>Games
+<p>
+
+The permissions on /var/lib/games are 755 <tt/root.root/.
+<p>
+
+Each game decides on its own security policy.
+<p>
+
+Games which require protected, privileged access to high-score files,
+savegames, etc., must be made set-<em/group/-id (mode 2755) and
+owned by <tt/root.games/, and use files and directories with
+appropriate permissions (770 <tt/root.games/, for example). They must
+<em/not/ be made set-<em/user/-id, as this causes security
+problems. (If an attacker can subvert any set-user-id game
+they can overwrite the executable of any other, causing other players
+of these games to run a Trojan horse program. With a set-group-id
+game the attacker only gets access to less important game data, and if
+they can get at the other players' accounts at all it will take
+considerably more effort.)
+<p>
+
+Some packages, for example some fortune cookie programs, are
+configured by the upstream authors to install with their data files or
+other static information made unreadable so that they can only be
+accessed through set-id programs provided. Do not do this in a Debian
+package: anyone can download the <tt/.deb/ file and read the data from
+it, so there is no point making the files unreadable. Not making the
+files unreadable also means that you don't have to make so many
+programs set-id, which reduces the risk of a security hole.
+<p>
+
+As described in the FSSTND, binaries of games should be installed in
+the directory <tt>/usr/games</tt>. This also applies to games that use
+the X windows system. Manual pages for games (X and non-X games) should
+be installed in <tt>/usr/man/man6</tt>.
+<p>
+
+<chapt>Documentation
+<p>
+
+<sect>Manual pages
+<p>
+
+You must install manual pages in <prgn/nroff/ source form, in appropriate
+places under <tt>/usr/man</tt>. You should only use sections 1 to 9
+(see the FSSTND for more details). You must <em/not/ install a
+preformatted `cat page'.
+<p>
+
+If no manual page is available for a particular program, utility or
+function and this is reported as a bug on debian-bugs, a symbolic link
+from the requested manual page to the <manref name=undocumented
+section=7> manual page should be provided. This symbolic link can be
+created from <tt>debian/rules</> like this:
+<example>
+ ln -s ../man7/undocumented.7.gz \
+ debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9].gz
+</example>
+This manpage claims that the lack of a manpage has been reported as a
+bug, so you may only do this if it really has (you can report it
+yourself, if you like). Do not close the bug report until a proper
+manpage is available.
+<p>
+
+You may forward a complaint about a missing manpage to the upstream
+authors, and mark the bug as forwarded in the Debian bug tracking
+system. Even though the GNU Project do not in general consider the
+lack of a manpage to be a bug, we do--if they tell you that they
+don't consider it a bug you should leave the bug in our bug tracking
+system open anyway.
+<p>
+
+Manual pages should be installed compressed using <tt/gzip -9/.
+<p>
+
+If one manpage needs to be accessible via several names it is better
+to use a symbolic link than the <tt/.so/ feature, but there is no need
+to fiddle with the relevant parts of the upstream source to change
+from <tt/.so/ to symlinks--don't do it unless it's easy. Do not
+create hard links in the manual page directories, and do not put
+absolute filenames in <tt/.so/ directives. The filename in a <tt/.so/
+in a manpage should be relative to the base of the manpage tree
+(usually <tt>/usr/man</tt>).
+<p>
+
+<sect>Info documents
+<p>
+
+Info documents should be installed in <tt>/usr/info</tt>. They should
+be compressed with <tt/gzip -9/.
+<p>
+
+Your package must call <prgn/install-info/ to update the Info <tt/dir/
+file, in its post-installation script:
+<example>
+ install-info --quiet --section Development Development \
+ /usr/info/foobar.info
+</example>
+<p>
+
+It is a good idea to specify a section for the location of your
+program; this is done with the <tt/--section/ switch. To determine
+which section to use, you should look at <tt>/usr/info/dir</> on your
+system and choose the most relevant (or create a new section if none
+of the current sections are relevant). Note that the <tt/--section/
+flag takes two arguments; the first is a regular expression to match
+(case-insensitively) against an existing section, the second is used
+when creating a new one.
+<p>
+
+You must remove the entries in the pre-removal script:
+<example>
+ install-info --quiet --remove /usr/info/foobar.info
+</example>
+<p>
+
+If <prgn/install-info/ cannot find a description entry in the Info
+file you will have to supply one. See <manref name=install-info
+section=8> for details.
+<p>
+
+<sect>Additional documentation
+<p>
+
+Any additional documentation that comes with the package can be
+installed at the discretion of the package maintainer. Text
+documentation should be installed in a directory
+<tt>/usr/doc/<var/package/</tt>, where <var/package/ is the
+name of the package, and compressed with <tt/gzip -9/
+unless it is small.
+<p>
+
+If a package comes with large amounts of documentation which many
+users of the package will not require you should create a separate
+binary package to contain it, so that it does not take up disk space
+on the machines of users who do not need or want it installed.
+<p>
+
+It is often a good idea to put text information files (<tt/README/s,
+changelogs, and so forth) that come with the source package in
+<tt>/usr/doc/<var/package/</> in the binary package. However, you don't
+need to install the instructions for building and installing the package, of
+course!
+<p>
+
+<sect>Preferred documentation formats
+<p>
+
+The unification of Debian documentation is being carried out via HTML.
+<p>
+
+If your package comes with extensive documentation in a markup format
+that can be converted to various other formats you should if possible
+ship HTML versions in the binary package, in the directory
+<tt>/usr/doc/<var/package/</> or its subdirectories.
+<p>
+
+Other formats such as PostScript may be provided at your option.
+<p>
+
+<sect>Log files
+<p>
+
+Log files should usually be named <tt>/var/log/<var/package/.log</tt>.
+If you have many log files, or need a separate directory for
+permissions reasons (<tt>/var/log</tt> is writable only by
+<tt/root/), you should usually create a directory named
+<tt>/var/log/<var/package/</tt>.
+<p>
+
+Make sure that any log files are rotated occasionally so that they
+don't grow indefinitely; the best way to do this is to use
+<prgn/savelog/ program in an <tt>/etc/cron.daily</>,
+<tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script. Here is a good
+example:
+<example>
+ [ -d /var/log/apache/. ] || exit 0
+ umask 022
+ cd /var/log/apache
+ if [ -fs access.log ]
+ then
+ savelog -c 7 access.log > /dev/null
+ fi
+</example>
+<p>
+
+Make sure that any log files are removed when the package is purged
+(but not when it is only removed), by checking the argument to the
+<tt/postrm/ script (see the <em>Debian Packaging Manual</em> for
+details).
+<p>
+
+<sect id="copyrightfile">Copyright information
+<p>
+
+Every package must be accompanied by a verbatim copy of its copyright
+and distribution license in the file
+/usr/doc/<package-name>/copyright. This file must neither be
+compressed nor be a symbolic link.
+<p>
+
+In addition, the copyright file must say where the upstream sources
+(if any) were obtained, and explain briefly what modifications were
+made in the Debian version of the package compared to the upstream
+one. It must name the original authors of the package and the Debian
+maintainer(s) who were involved with its creation.
+<p>
+
+/usr/doc/<package-name> may be a symbolic link to a directory in
+/usr/doc only if two packages both come from the same source and the
+first package has a "Depends" relationship on the second. These rules
+are important because copyrights must be extractable by mechanical
+means.
+<p>
+
+Packages distributed under the UCB BSD license, the Artistic license,
+the GNU GPL, and the GNU LGPL should refer to the files
+/usr/doc/copyright/BSD, /usr/doc/copyright/Artistic,
+/usr/doc/copyright/GPL, and /usr/doc/copyright/LGPL.
+<p>
+
+Do not use the copyright file as a general <tt/README/ file. If your
+package has such a file it should be installed in
+<tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some
+other appropriate place.
+<p>
+
+<sect>Examples
+<p>
+
+Any examples (configurations, source files, whatever), should be
+installed in a directory <tt>/usr/doc/<var/package//examples</tt>.
+These files should not be referenced by any program--they're there
+for the benefit of the system administrator and users, as
+documentation only.
+<p>
+
+<sect id="instchangelog">Changelog files
+<p>
+
+This installed file must contain a copy of the <tt>debian/changelog</>
+file from your Debian source tree, and a copy of the upstream
+changelog file if there is one. They should usually be installed in
+<tt>/usr/doc/<var/package/</> as <tt/changelog.Debian.gz/ and
+<tt/changelog.gz/ respectively.
+<p>
+
+Both should be installed compressed using <tt/gzip -9/, as they will
+become large with time even if they start out small.
+<p>
+
+If the package has only one changelog which is used both as the Debian
+changelog and the upstream one because there is no separate upstream
+maintainer then that changelog should usually be installed as
+<tt>/usr/doc/<var/package//changelog.gz</>; if there is a separate
+upstream maintainer, but no upstream changelog, then the Debian
+changelog should still be called <tt/changelog.Debian.gz/.
+<p>
+
+</book>
--- /dev/null
+<html><head><title>Policy checklist for upgrading your packages</title></head>
+<body>
+
+<h1>Policy checklist for upgrading your packages</h1>
+
+<h2>About the checklist</h2>
+
+The checklist below has been created to simplify the upgrading process
+of old packages. Note, that this list is not `official.' If you have
+doubts about a certain topic, if you need more details, or if you
+think some other package does not comply with policy, please refer to
+the Policy Manual.
+<p>
+
+Here is how the check list works: Check out which policy version your
+packages complies with currently. Than move upwards until the top and
+check which of the items on the list might concern your package. If an
+item does not give you enough details, please check out the Policy
+Manual.
+<p>
+
+<h2>The checklist</h2>
+
+<pre>
+
+2.4.1.0 Apr 98
+
+ Policy Manual:
+ - Updated section 3.3.5 Symbolic links:
+ + symbolic links within a toplevel directory should be relative,
+ symbolic links between toplevel directories should be absolute
+ (cf., Policy Weekly Issue#6, topic 2)
+
+ - Updated section 4.9 Games:
+ + manpages for games should be installed in /usr/man/man6
+ (cf., Policy Weekly Issue#6, topic 3)
+
+ Packaging Manual:
+ - Updated prefix of chapter 12, Shared Libraries:
+ ldconfig must be called in the postinst script if the package
+ installs shared libraries
+ (cf., Policy Weekly Issue #6, fixes:bug#20515)
+
+2.4.0.0 Jan 98
+
+ - Updated section 3.3.4 Scripts:
+ + /bin/sh may be any POSIX compatible shell
+ + scripts including bashisms have to specify /bin/bash as
+ interpreter
+ + scripts which create files in world-writable directories
+ (e.g., in /tmp) should use tempfile or mktemp for creating
+ the directory
+
+ - Updated section 3.3.5 Symbolic Links:
+ + symbolic links referencing compressed files must have the same
+ file extension as the referenced file
+
+ - Updated section 3.3.6 Device files:
+ + /dev/tty* serial devices should be used instead of /dev/cu*
+
+ - Updated section 3.4.2 Writing the scripts [in /etc/init.d]:
+ + all /etc/init.d scripts have to provide the following options:
+ start, stop, restart, force-reload
+ + the reload option is optional and must never stop and restart
+ the service
+
+ - Updated section 3.5 Cron jobs:
+ + cron jobs that need to be executed more often than daily should
+ be installed into /etc/cron.d
+
+ - Updated section 3.7 Menus:
+ + removed section about how to register HTML docs to `menu'
+ (the corresponding section in 4.4, Web servers and applications,
+ has been removed in policy 2.2.0.0 already, so this one was
+ obsolete)
+
+ - New section 3.8 Keyboard configuration:
+ + details about how the backspace and delete keys should be
+ handled
+
+ - New section 3.9 Environment variables:
+ + no program must depend on environment variables to get a
+ reasonable default configuration
+
+ - New section 4.6 News system configuration:
+ + /etc/news/organization and /etc/news/server should be supported
+ by all news servers and clients
+
+ - Updated section 4.7 Programs for the X Windows system:
+ + programs requiring a non-free Motif library should be provided
+ as foo-smotif and foo-dmotif package
+ + if lesstif works reliably for such program, it should be linked
+ against lesstif and not against a non-free Motif library
+
+ - Updated section 4.9 Games:
+ + games for X Windows have to be installed in /usr/games, just as
+ non-X games
+
+2.3.0.1, 2.3.0.0 Sep 97
+
+ * new section `4.2 Daemons' including rules for
+ /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
+
+ * updated section about `Configuration files':
+ packages may not touch other packages' configuration files
+
+ * MUAs and MTAs have to use liblockfile
+
+2.2.0.0 Jul 97
+
+ * added section 4.1 `Architecture specification strings':
+ use
+ <arch>-linux
+ where <arch> is one of the following:
+ i386, alpha, arm, m68k, powerpc, sparc.
+
+ * detailed rules for /usr/local
+
+ * user ID's
+
+ * editor/pager policy
+
+ * cron jobs
+
+ * device files
+
+ * don't install shared libraries as executable
+
+ * app-defaults files may not be conffiles
+
+2.1.3.2, 2.1.3.1, 2.1.3.0 Mar 97
+
+ * two programs with different functionality must not have the
+ same name
+
+ * "Webstandard 3.0"
+
+ * "Standard for Console Messages"
+
+ * Libraries should be compiled with `-D_REENTRANT'
+
+ * Libraries should be stripped with "strip --strip-unneeded"
+
+2.1.2.2, 2.1.2.1, 2.1.2.0 Nov 96
+
+ * Some changes WRT shared libraries
+
+2.1.1.0 Sep 96
+
+ * No hard links in source packages
+
+ * Do not use dpkg-divert or update-alternatives without consultation
+
+ * Shared libraries must be installed stripped
+
+2.1.0.0 Aug 96
+
+ * Upstream changelog must be installed too
+</pre>
+
+<p>
+<hr>
+
+</body></html>
--- /dev/null
+
+ AUTHORITATIVE LIST OF VIRTUAL PACKAGE NAMES
+
+ Apr 1998, 14
+
+
+Below is an authoritative list of virtual package names currently
+in-use or proposed and not objected to. Please check the list below
+for things relevant to your packages.
+
+New packages MUST use virtual package names where appropriate (this
+includes making new ones - read on).
+
+Packages MUST NOT use virtual package names (except privately, amongst
+a cooperating group of packages) unless they have been agreed upon and
+appear in this list.
+
+The latest version of this file can be found in
+ doc/package-developer/virtual-package-names-list.text
+on your local Debian FTP site.
+
+The procedure for updating the list is as follows:
+
+1. Post to debian-devel saying what names you intend to use or what
+ other changes you wish to make.
+
+2. Wait a few days for comment.
+
+3. Mail the maintainer of the virtual package name list (Christian
+ Schwarz <schwarz@debian.org>) notifying him of the consensus reached (or
+ your suggestions if noone objected). Please include a proposed brief
+ description of the new virtual name(s) for the list. The list
+ maintainer will then post the new list to debian-devel and upload it
+ to the FTP site.
+
+4. Go and use the new or changed names.
+
+Chris.
+(based on earlier version by Warwick and Ian Jackson)
+
+
+Now, the list:
+
+X Windows
+---------
+xserver Any X server (used by other X packages)
+
+Miscellaneous
+-------------
+libc.so.4 An a.out shared C library, version 4.x.x.
+info-browser Something that can browser GNU Info files
+kernel-source Kernel source code
+kernel-headers Kernel header files (<linux/*.h>, <asm/*.h>)
+kernel-image Kernel image (vmlinuz, System.map, modules)
+httpd Any HTTP server
+postscript-viewer Anything that can display Postscript files
+postscript-preview Any preprocessor that creates Postscript output
+www-browser Something that can browse html files
+awk Anything providing suitable /usr/bin/{awk,nawk}
+c-shell Anything providing a suitable /usr/bin/csh
+pdf-viewer Anything that can display PDF files
+pdf-preview Any preprocessor that creates PDF output
+wordlist Anything that provides /usr/dict/words
+dotfile-module Anything that provides a module for the
+ Dotfile Generator
+ups-monitor Anything that is capable of controlling an UPS
+tclsh Anything that provides /usr/bin/tclsh
+wish Anything that provides /usr/bin/wish
+c-compiler Anything providing a C compiler
+fortran77-compiler Anything providing a Fortran77 compiler
+lambdamoo-core A lambdamoo-compatible datebase package
+lambdamoo-server Anything running a moo using a lambdamoo-core
+libc-dev Anything that provides header and object files
+ of `libc'
+emacsen Anything providing the GNU emacs or a compatible
+ editor
+
+News and Mail
+-------------
+mail-transport-agent Mail transport agents (Smail, Sendmail, &c)
+mail-reader Mail user agents (Pine, Elm, mailx, &c)
+news-transport-system Local news system (INN, C News or B News)
+news-reader Any news reader (trn, tin, &c)
+pgp A version of PGP (International or US)
+imap-client Any mail reader capable of accessing remote mail
+ folders using the IMAP protocol (e.g. Pine)
+imap-server Any IMAP mail server
+
+Old and obsolete virtual package names
+--------------------------------------
+Note, that no other package then the ones listed here should use
+these virtual package names.
+
+X11R5 provided by xcompat for compatibility reasons
+xr5shlib do.
+aout-x11r6lib do.
+X11R6 do.
+
+
+Changelog
+---------
+
+Ian Jackson:
+ 22 Sep 1995 Initial revision.
+
+Andrew Howell:
+ 26 Mar 1996 Added www-browser.
+
+Manoj Srivastava
+ 11 May 1996 Added kernel-image, added new location of this file
+
+Warwick Harvey:
+ 19 May 1996 Took over maintenance of list, changed instructions for
+ updating list
+ 25 Jul 1996 Added awk as per Chris Fearnley's suggestion
+ Added c-shell, which seemed to have dropped off at some stage
+ 2 Aug 1996 Added pdf-{viewer,preview}, compress, emacs
+ 5 Aug 1996 Added imap-{client,server}
+ 8 Aug 1996 Added editor
+ 20 Aug 1996 Added sgmls, removed metafont, dvilj, dvips
+ 25 Nov 1996 Removed editor (should have done this a long time ago)
+
+Christian Schwarz
+ 29 Apr 1997 New maintainer of this list
+ 5 May 1997 Added wordlist
+ 29 May 1997 Added dotfile-module, ups-monitor, tcl-interpreter,
+ tk-interpreter
+ 21 Jun 1997 Removed obsolete virtual packages: xR6shlib, xlibraries,
+ compress, emacs, sgmls, inews, gs_x, gs_svga, gs_both, xpmR6
+ Added new section about obsolete names
+ 1 Sep 1997 Renamed `tcl/tk-interpreter' to `tclsh/wish'
+ 21 Oct 1997 Added emacs, c-compiler, fortran77-compiler, lambdamoo-core,
+ lambdamoo-server
+ 29 Jan 1998 Added libc-dev, emacsen
+ 14 Apr 1998 Removed obsolete virtual package `emacs'
projects / debian / debian-policy.git / commitdiff