From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:04:26 +0000 (+0000) Subject: Initial revision X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=bceec08198198e2a21407528de76bcd756265e86;p=debian%2Fdebian-policy.git Initial revision Author: srivasta Date: 1998/09/07 07:45:57 Initial revision git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-7 --- diff --git a/FSSTND-FAQ b/FSSTND-FAQ new file mode 100644 index 0000000..e871fc0 --- /dev/null +++ b/FSSTND-FAQ @@ -0,0 +1,259 @@ +This is a collection of Frequently Asked Questions (and answers!) +about the Linux FSSTND project and document. It was composed by Ian +McCloghrie . 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 +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 . + + +========== 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/, 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. + diff --git a/debian-policy.desc b/debian-policy.desc new file mode 100644 index 0000000..90640f4 --- /dev/null +++ b/debian-policy.desc @@ -0,0 +1,19 @@ +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 diff --git a/debian/RELEASED b/debian/RELEASED new file mode 100644 index 0000000..e69de29 diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 0000000..3c2812b --- /dev/null +++ b/debian/changelog @@ -0,0 +1,466 @@ +debian-policy (2.4.1.4) unstable; urgency=low + + * New Maintainer + + -- Philip Hands 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 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 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 Tue, 16 Jun 1998 03:15:22 -0400 + +debian-policy (2.4.1.1) frozen unstable; urgency=low + + * Orphaned package + + -- Christian Schwarz 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 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 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 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 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 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 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 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 Tue, 29 Apr 1997 18:02:14 +0200 + +debian-policy (2.1.3.0) unstable; urgency=low + + * Initial Release. + * New Policy Manager: Christian Schwarz + * 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 . + * Added log-rotating example to section 3.2.9 that tests with `-sf', + as suggested by Boris D. Beletsky . + * 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 + . + * Added note to 4.1.2: Libraries should be stripped with + "strip --strip-unneeded", by Guy Maor . + * 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 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 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 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 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 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 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 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 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 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 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 Fri, 23 Aug 1996 04:05:36 +0100 + +debian-manuals (0.2.0.0) experimental; + + * Draft releases. + + -- Ian Jackson Wed, 21 Aug 1996 15:07:53 +0100 + +Local variables: +mode: debian-changelog +add-log-mailing-address: "phil@hands.com" +End: diff --git a/debian/control b/debian/control new file mode 100644 index 0000000..51eba22 --- /dev/null +++ b/debian/control @@ -0,0 +1,17 @@ +Source: debian-policy +Section: doc +Priority: extra +Maintainer: Debian Policy List +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 diff --git a/debian/copyright b/debian/copyright new file mode 100644 index 0000000..ed01efb --- /dev/null +++ b/debian/copyright @@ -0,0 +1,56 @@ + +This is the Debian package of Debian Policy Manual, the Linux +Filesystem Standard and related documents. It was assembled by +Christian Schwarz . + +------------------------------------------------------------------------------ +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. + +-------------------------------------------------------------------------- diff --git a/debian/dirs b/debian/dirs new file mode 100644 index 0000000..21c85a6 --- /dev/null +++ b/debian/dirs @@ -0,0 +1,2 @@ +usr/doc/debian-policy/fsstnd +usr/share/doc-base diff --git a/debian/postinst b/debian/postinst new file mode 100644 index 0000000..3cc6f11 --- /dev/null +++ b/debian/postinst @@ -0,0 +1,22 @@ +#!/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 diff --git a/debian/prerm b/debian/prerm new file mode 100644 index 0000000..aeed835 --- /dev/null +++ b/debian/prerm @@ -0,0 +1,5 @@ +#!/bin/sh + +if [ -x /usr/sbin/install-docs ]; then + /usr/sbin/install-docs -r debian-policy +fi diff --git a/debian/rules b/debian/rules new file mode 100755 index 0000000..f1817cd --- /dev/null +++ b/debian/rules @@ -0,0 +1,89 @@ +#!/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 "" >> version.ent + echo "" >> 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 diff --git a/fsstnd-1.2.ChangeLog b/fsstnd-1.2.ChangeLog new file mode 100644 index 0000000..c99496e --- /dev/null +++ b/fsstnd-1.2.ChangeLog @@ -0,0 +1,39 @@ +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 + , 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. diff --git a/fsstnd-1.2.dvi.gz b/fsstnd-1.2.dvi.gz new file mode 100644 index 0000000..a461c6c Binary files /dev/null and b/fsstnd-1.2.dvi.gz differ diff --git a/fsstnd-1.2.ps.gz b/fsstnd-1.2.ps.gz new file mode 100644 index 0000000..f764573 Binary files /dev/null and b/fsstnd-1.2.ps.gz differ diff --git a/fsstnd-1.2.txt.gz b/fsstnd-1.2.txt.gz new file mode 100644 index 0000000..0283d11 Binary files /dev/null and b/fsstnd-1.2.txt.gz differ diff --git a/libc6-migration.txt b/libc6-migration.txt new file mode 100644 index 0000000..7c8134f --- /dev/null +++ b/libc6-migration.txt @@ -0,0 +1,263 @@ + + 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. + libc5 | libfoo | /usr/lib/libc5-compat/libfoo.so. [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/-linuxlibc1/{lib,include} + + Note that 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/-linuxlibc1/lib/libfoo.so -> /usr/lib/libc5-compat/libfoo.so. + 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 . + + 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 Fri, 20 Jun 1997 08:32:03 +0200 + +libfoo (1.7.54-8) unstable; urgency=low + + * hamm release + + -- J.D. Maintainer Fri, 20 Jun 1997 08:32:03 +0200 + +libfoo (1.7.54-7) unstable; urgency=low + + * hamm release + + -- J.D. Maintainer Fri, 20 Jun 1997 08:32:03 +0200 + +libfoo (1.7.54-6) stable; urgency=low + + * added handling of bar. + + -- J.D. Maintainer Mon, 16 Jun 1997 18:45:14 +0200 +-=-=-=-=-=-=-=-=-= hamm changelog =-=-=-=-=-=-=-=-=- +libfoo (1.7.54-10) unstable; urgency=low + + * fixed bug #543547884 + + -- J.D. Maintainer Fri, 20 Jun 1997 08:52:09 +0200 + +libfoo (1.7.54-9) stable; urgency=low + + * bo release + + -- J.D. Maintainer 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 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 + diff --git a/packaging-manual.desc b/packaging-manual.desc new file mode 100644 index 0000000..434cc2c --- /dev/null +++ b/packaging-manual.desc @@ -0,0 +1,19 @@ +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 diff --git a/packaging.sgml b/packaging.sgml new file mode 100644 index 0000000..4a3f0a5 --- /dev/null +++ b/packaging.sgml @@ -0,0 +1,3574 @@ + + + + + + +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> diff --git a/policy.sgml b/policy.sgml new file mode 100644 index 0000000..d88c754 --- /dev/null +++ b/policy.sgml @@ -0,0 +1,2591 @@ +<!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> diff --git a/upgrading-checklist.html b/upgrading-checklist.html new file mode 100644 index 0000000..13aed5d --- /dev/null +++ b/upgrading-checklist.html @@ -0,0 +1,164 @@ +<html><head><title>Policy checklist for upgrading your packages + + +

Policy checklist for upgrading your packages

+ +

About the checklist

+ +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. +

+ +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. +

+ +

The checklist

+ +
+
+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
+
+ +

+

+ + diff --git a/virtual-package-names-list.txt b/virtual-package-names-list.txt new file mode 100644 index 0000000..c01cd6b --- /dev/null +++ b/virtual-package-names-list.txt @@ -0,0 +1,135 @@ + + 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 ) 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 (, ) +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'