diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 81 | ||||
| -rw-r--r-- | doc/auto-deconfiguration.txt | 62 | ||||
| -rw-r--r-- | doc/database-structure.fig | 487 | ||||
| -rw-r--r-- | doc/deb-control.5 | 104 | ||||
| -rw-r--r-- | doc/deb.5 | 69 | ||||
| -rw-r--r-- | doc/dependency-ordering.txt | 97 | ||||
| -rw-r--r-- | doc/descriptions.txt | 112 | ||||
| -rw-r--r-- | doc/disappear-replace.txt | 44 | ||||
| -rw-r--r-- | doc/diversions.text | 131 | ||||
| -rw-r--r-- | doc/dpkg.texi | 101 | ||||
| -rw-r--r-- | doc/essential-flag.txt | 43 | ||||
| -rw-r--r-- | doc/guidelines.info-1 | 1039 | ||||
| -rw-r--r-- | doc/guidelines.info-2 | 744 | ||||
| -rw-r--r-- | doc/guidelines.texi | 1936 | ||||
| -rw-r--r-- | doc/guidelines.texi.beforeeric | 1056 | ||||
| -rw-r--r-- | doc/guidelines.texi.rej | 33 | ||||
| -rw-r--r-- | doc/junk | 29 | ||||
| -rw-r--r-- | doc/maintainer-script-args.txt | 173 | ||||
| -rw-r--r-- | doc/upgrades+errors.txt | 220 | ||||
| -rw-r--r-- | doc/version-ordering.txt | 59 | ||||
| -rw-r--r-- | doc/virtual-dependencies.txt | 105 |
21 files changed, 6725 insertions, 0 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 000000000..9b9724c14 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,81 @@ +# Copyright (C) 1994 Ian Murdock <imurdock@debian.org> +# Copyright (C) 1994,1995 Ian Jackson <ijackson@nyx.cs.du.edu> +# +# This is free software; you can 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 along with dpkg; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +srcdir = @srcdir@ +VPATH = @srcdir@ + +prefix = @prefix@ +infodir = $(prefix)/info +mandir = $(prefix)/man +man5dir = $(mandir)/man5 +man5 = 5 +docdir = $(prefix)/doc +devdocdir = $(docdir)/dpkg + +DIST = Makefile.in $(SRC) $(MAN) + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_DATA = @INSTALL_DATA@ + +MAKEINFO = makeinfo +TEXI2DVI = texi2dvi + +DEVDOCS= auto-deconfiguration.txt dependency-ordering.txt \ + disappear-replace.txt diversions.text \ + essential-flag.txt version-ordering.txt + +# Files folded into main guidelines document +OBSOLETEDOCS= descriptions.txt upgrades+errors.txt \ + maintainer-script-args.txt virtual-dependencies.txt + +all: $(DEVDOCS) guidelines.info + +guidelines.info: guidelines.texi + $(MAKEINFO) $(srcdir)/guidelines.texi + +database-structure.ps: database-structure.fig + fig2dev -L ps -c -l _ -P <database-structure.fig >ps + mv ps database-structure.ps + +database-structure.monops: database-structure.ps + perl -pe 's:^/(col[0-7]) \{[01 ]*1[01 ]* setrgbcolor\}\ + bind def$$:/$$1 {} bind def:' database-structure.ps >ps + mv ps database-structure.monops + +#dpkg.dvi: +# $(TEXI2DVI) $(srcdir)/dpkg.texi +# +#dpkg.info: +# $(MAKEINFO) $(srcdir)/dpkg.texi + +clean: + rm -f database-structure.ps database-structure.monops ps + rm -f *.{aux,cp,dvi,fn,ky,log,pg,toc,tp,vr} + rm -f guidelines.info + +distclean: + rm -f Makefile *.orig *~ *.~* ./#*# + +install: all + $(INSTALL_DATA) deb.5 $(man5dir)/deb.$(man5) + $(INSTALL_DATA) deb-control.5 $(man5dir)/deb-control.$(man5) + $(INSTALL_DATA) guidelines.info guidelines.info-*[0-9] \ + $(infodir)/. + set -e; for d in $(DEVDOCS) ; do \ + $(INSTALL_DATA) $$d $(devdocdir)/$$d ; \ + done diff --git a/doc/auto-deconfiguration.txt b/doc/auto-deconfiguration.txt new file mode 100644 index 000000000..5cc0ef55b --- /dev/null +++ b/doc/auto-deconfiguration.txt @@ -0,0 +1,62 @@ +To: Debian developers list <debian-devel@pixar.com> +Subject: Re: dpkg maintainer script calls and arguments +In-Reply-To: <1506077@toto.iv> +FCC: ~/mail/Outbound +--text follows this line-- +In order to support easier upgrades where important packages get split +into several pieces, I have implemented the following scheme, which I +described on debian-private a while ago. It is enabled by the use of +`--auto-deconfigure', or `-B', and the dselect method scripts in +0.93.76 have been changed to supply this option. + +] I plan to make it possible to `deconfigure' packages at installation +] time, in order to keep dependency invariants satisfied. In a sane +] installation this will mean that everything will work right, even when +] (for example) an important package is split into two pieces or +] packages. +] +] Basically, suppose that package A is being split into A1 and A2, and B +] and C depend on A1 and A2 respectively. If you try to install A1 dpkg +] will consider removing A (because of the conflict between A and each +] of A1 and A2), but then C's dependency is not satisifed, and if you +] try to install A2 B's dependency wouldn't be satisfied. +] +] At the moment dpkg will simply refuse to do it. You have to say +] --force-depends, or remove either B or C. +] +] I'm going to arrange that dpkg will automatically deconfigure B or C, +] as appropriate, and try to reconfigure it later. +] +] So, if you do `dpkg -i A1.deb A2.deb' all will be well; if you do +] `dpkg -i A1.deb' you'll get A1 installed and configured correctly, but +] error messages about C being broken, and in order to fix C you'll have +] to install A2 as well, or return to A (dpkg will remove A1). +] +] All of this will appear very automatic to people who use dselect. +] People who do things manually will have a slightly more complicated +] task, as dpkg won't remove A (in the scenario above) unless it has +] been selected for deinstallation using dselect or dpkg --remove (which +] would fail because of the dependencies from B and C). + +This means that maintainer scripts can get called in two new ways: + <prerm(C)> deconfigure in-favour <A1> <version> removing <A> <v.> + <postinst(C)> abort-deconfigure in-favour <A1> <version> removing <A> <v.> +using the example package names above. + +The first call happens before the prerm script of the package which is +being removed (A) is called; the second happens if an error occurs and +dpkg wants to back out of the installation. + +If the installation of both A1 and A2 is successful dpkg will then +call both + <postinst(B)> configure + <postinst(C)> configure +as usual. + +Some time ago I posted a message documenting all the maintainer script +calls and their arguments. Below is a revised version of that +message. I shall upload it as maintainer-script-args.txt, and it +should go in project/standards. The top half of this message will go +in auto-deconfiguration.txt. + +Ian. diff --git a/doc/database-structure.fig b/doc/database-structure.fig new file mode 100644 index 000000000..462e2f6c2 --- /dev/null +++ b/doc/database-structure.fig @@ -0,0 +1,487 @@ +#FIG 2.1 +80 2 +6 59 74 199 169 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 129 199 129 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 149 199 149 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 129 69 169 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 59 109 199 109 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 139 129 139 169 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 199 169 199 89 59 89 59 169 199 169 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 139 89 139 109 9999 9999 +4 0 12 10 0 -1 0 0.000 4 5 24 64 104 name +4 0 12 10 0 -1 0 0.000 4 9 84 64 122 pkginfoperfile +4 0 12 10 0 -1 0 0.000 4 9 42 74 144 depends +4 0 12 10 0 -1 0 0.000 4 9 48 74 162 depended +4 0 12 10 0 -1 0 0.000 4 9 42 59 84 pkginfo +-6 +6 59 394 199 489 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 449 199 449 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 469 199 469 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 449 69 489 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 59 429 199 429 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 139 449 139 489 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 199 489 199 409 59 409 59 489 199 489 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 139 409 139 429 9999 9999 +4 0 12 10 0 -1 0 0.000 4 5 24 64 424 name +4 0 12 10 0 -1 0 0.000 4 9 84 64 442 pkginfoperfile +4 0 12 10 0 -1 0 0.000 4 9 42 74 464 depends +4 0 12 10 0 -1 0 0.000 4 9 48 74 482 depended +4 0 12 10 0 -1 0 0.000 4 9 42 59 404 pkginfo +-6 +6 59 234 199 329 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 289 199 289 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 309 199 309 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 69 289 69 329 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 59 269 199 269 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 139 289 139 329 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 199 329 199 249 59 249 59 329 199 329 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 139 249 139 269 9999 9999 +4 0 12 10 0 -1 0 0.000 4 5 24 64 264 name +4 0 12 10 0 -1 0 0.000 4 9 84 64 282 pkginfoperfile +4 0 12 10 0 -1 0 0.000 4 9 42 74 304 depends +4 0 12 10 0 -1 0 0.000 4 9 48 74 322 depended +4 0 12 10 0 -1 0 0.000 4 9 42 59 244 pkginfo +-6 +6 559 74 699 169 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 569 129 699 129 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 569 149 699 149 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 569 129 569 169 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 559 109 699 109 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 639 129 639 169 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 699 169 699 89 559 89 559 169 699 169 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 639 89 639 109 9999 9999 +4 0 12 10 0 -1 0 0.000 4 5 24 564 104 name +4 0 12 10 0 -1 0 0.000 4 9 84 564 122 pkginfoperfile +4 0 12 10 0 -1 0 0.000 4 9 42 574 144 depends +4 0 12 10 0 -1 0 0.000 4 9 48 574 162 depended +4 0 12 10 0 -1 0 0.000 4 9 42 559 84 pkginfo +-6 +6 399 119 499 214 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 499 214 499 134 399 134 399 214 499 214 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 399 154 499 154 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 399 174 499 174 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 399 194 499 194 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 439 134 439 214 9999 9999 +4 0 12 10 0 -1 0 0.000 4 7 12 404 149 up +4 0 12 10 0 -1 0 0.000 4 7 24 404 169 next +4 0 12 10 0 -1 0 0.000 4 7 24 404 189 list +4 0 12 10 0 -1 0 0.000 4 9 24 404 209 type +4 0 12 10 0 -1 0 0.000 4 9 60 399 129 dependency +-6 +6 654 224 754 319 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 754 319 754 239 654 239 654 319 754 319 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 654 259 754 259 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 654 279 754 279 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 654 299 754 299 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 694 239 694 319 9999 9999 +4 0 12 10 0 -1 0 0.000 4 7 12 659 254 up +4 0 12 10 0 -1 0 0.000 4 7 24 659 274 next +4 0 12 10 0 -1 0 0.000 4 7 24 659 294 list +4 0 12 10 0 -1 0 0.000 4 9 24 659 314 type +4 0 12 10 0 -1 0 0.000 4 9 60 654 234 dependency +-6 +6 164 294 174 304 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 164 294 174 304 9999 9999 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 164 304 174 294 9999 9999 +-6 +6 164 454 174 464 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 164 454 174 464 9999 9999 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 164 464 174 454 9999 9999 +-6 +6 464 159 474 169 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 464 159 474 169 9999 9999 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 464 169 474 159 9999 9999 +-6 +6 719 264 729 274 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 719 264 729 274 9999 9999 +2 1 0 1 1 0 0 0 0.000 7 0 0 + 719 274 729 264 9999 9999 +-6 +6 164 154 174 164 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 164 154 174 164 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 164 164 174 154 9999 9999 +-6 +6 354 339 364 349 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 354 339 364 349 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 354 349 364 339 9999 9999 +-6 +6 269 259 389 394 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 269 294 389 294 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 269 314 389 314 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 269 334 389 334 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 269 354 389 354 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 329 274 329 394 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 389 394 389 274 269 274 269 394 389 394 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 269 374 389 374 9999 9999 +4 0 12 10 0 -1 0 0.000 4 9 48 269 269 deppossi +4 0 12 10 0 -1 0 0.000 4 7 12 274 289 up +4 0 12 10 0 -1 0 0.000 4 7 24 274 309 next +4 0 12 10 0 -1 0 0.000 4 7 12 274 329 ed +4 0 12 10 0 -1 0 0.000 4 7 42 274 389 version +4 0 12 10 0 -1 0 0.000 4 7 42 274 349 nextrev +4 0 12 10 0 -1 0 0.000 4 7 42 274 369 backrev +-6 +6 354 359 364 369 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 354 359 364 369 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 354 369 364 359 9999 9999 +-6 +6 74 564 194 599 +4 0 12 12 0 -1 0 0.000 4 12 84 74 579 Package: foo +4 0 12 12 0 -1 0 0.000 4 12 119 74 595 Depends: a | b, c +-6 +6 389 449 399 459 +2 1 0 1 2 0 0 0 0.000 7 0 0 + 389 449 399 459 9999 9999 +2 1 0 1 2 0 0 0 0.000 7 0 0 + 389 459 399 449 9999 9999 +-6 +6 389 509 399 519 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 389 509 399 519 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 389 519 399 509 9999 9999 +-6 +6 304 409 424 544 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 304 444 424 444 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 304 464 424 464 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 304 484 424 484 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 304 504 424 504 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 364 424 364 544 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 424 544 424 424 304 424 304 544 424 544 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 304 524 424 524 9999 9999 +4 0 12 10 0 -1 0 0.000 4 9 48 304 419 deppossi +4 0 12 10 0 -1 0 0.000 4 7 12 309 439 up +4 0 12 10 0 -1 0 0.000 4 7 24 309 459 next +4 0 12 10 0 -1 0 0.000 4 7 12 309 479 ed +4 0 12 10 0 -1 0 0.000 4 7 42 309 539 version +4 0 12 10 0 -1 0 0.000 4 7 42 309 499 nextrev +4 0 12 10 0 -1 0 0.000 4 7 42 309 519 backrev +-6 +6 259 119 359 214 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 359 214 359 134 259 134 259 214 359 214 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 259 154 359 154 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 259 174 359 174 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 259 194 359 194 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 299 134 299 214 9999 9999 +4 0 12 10 0 -1 0 0.000 4 7 12 264 149 up +4 0 12 10 0 -1 0 0.000 4 7 24 264 169 next +4 0 12 10 0 -1 0 0.000 4 7 24 264 189 list +4 0 12 10 0 -1 0 0.000 4 9 24 264 209 type +4 0 12 10 0 -1 0 0.000 4 9 60 259 129 dependency +-6 +6 479 279 599 414 +6 564 359 574 369 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 564 359 574 369 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 564 369 574 359 9999 9999 +-6 +6 564 319 574 329 +2 1 0 1 2 0 0 0 0.000 7 0 0 + 564 319 574 329 9999 9999 +2 1 0 1 2 0 0 0 0.000 7 0 0 + 564 329 574 319 9999 9999 +-6 +6 479 279 599 414 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 479 314 599 314 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 479 334 599 334 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 479 354 599 354 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 479 374 599 374 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 539 294 539 414 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 599 414 599 294 479 294 479 414 599 414 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 479 394 599 394 9999 9999 +4 0 12 10 0 -1 0 0.000 4 9 48 479 289 deppossi +4 0 12 10 0 -1 0 0.000 4 7 12 484 309 up +4 0 12 10 0 -1 0 0.000 4 7 24 484 329 next +4 0 12 10 0 -1 0 0.000 4 7 12 484 349 ed +4 0 12 10 0 -1 0 0.000 4 7 42 484 409 version +4 0 12 10 0 -1 0 0.000 4 7 42 484 369 nextrev +4 0 12 10 0 -1 0 0.000 4 7 42 484 389 backrev +-6 +6 564 379 574 389 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 564 379 574 389 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 564 389 574 379 9999 9999 +-6 +1 3 0 1 4 0 0 0 0.000 1 0.000 569 304 5 5 569 304 574 309 +1 3 0 1 6 0 0 0 0.000 1 0.000 569 344 5 5 569 344 574 349 +4 0 0 12 0 -1 0 0.000 4 6 5 589 289 c +-6 +6 644 409 764 544 +6 729 489 739 499 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 729 489 739 499 9999 9999 +2 1 0 1 5 0 0 0 0.000 7 0 0 + 729 499 739 489 9999 9999 +-6 +6 729 449 739 459 +2 1 0 1 2 0 0 0 0.000 7 0 0 + 729 449 739 459 9999 9999 +2 1 0 1 2 0 0 0 0.000 7 0 0 + 729 459 739 449 9999 9999 +-6 +6 644 409 764 544 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 644 444 764 444 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 644 464 764 464 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 644 484 764 484 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 644 504 764 504 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 704 424 704 544 9999 9999 +2 2 0 1 -1 0 0 0 0.000 0 0 0 + 764 544 764 424 644 424 644 544 764 544 9999 9999 +2 1 2 1 -1 0 0 0 3.000 -1 0 0 + 644 524 764 524 9999 9999 +4 0 12 10 0 -1 0 0.000 4 9 48 644 419 deppossi +4 0 12 10 0 -1 0 0.000 4 7 12 649 439 up +4 0 12 10 0 -1 0 0.000 4 7 24 649 459 next +4 0 12 10 0 -1 0 0.000 4 7 12 649 479 ed +4 0 12 10 0 -1 0 0.000 4 7 42 649 539 version +4 0 12 10 0 -1 0 0.000 4 7 42 649 499 nextrev +4 0 12 10 0 -1 0 0.000 4 7 42 649 519 backrev +-6 +1 3 0 1 4 0 0 0 0.000 1 0.000 734 434 5 5 734 434 739 439 +1 3 0 1 6 0 0 0 0.000 1 0.000 734 474 5 5 734 474 739 479 +1 3 0 1 5 0 0 0 0.000 1 0.000 734 514 5 5 734 514 739 519 +4 0 0 12 0 -1 0 0.000 4 9 6 744 419 b +4 0 12 12 0 7 0 0.000 4 9 28 719 539 >1.0 +-6 +6 449 564 589 599 +4 0 12 12 0 -1 0 0.000 4 12 70 449 579 Package: c +4 0 12 12 0 -1 0 0.000 4 11 140 449 595 Recommends: b (>1.0) +-6 +1 3 0 1 1 0 0 0 0.000 1 0.000 169 139 5 5 169 139 174 144 +1 3 0 1 1 0 0 0 0.000 1 0.000 669 139 5 5 669 139 674 144 +1 3 0 1 1 0 0 0 0.000 1 0.000 329 164 5 5 329 164 334 169 +1 3 0 1 2 0 0 0 0.000 1 0.000 329 184 5 5 329 184 334 189 +1 3 0 1 2 0 0 0 0.000 1 0.000 469 184 5 5 469 184 474 189 +1 3 0 1 2 0 0 0 0.000 1 0.000 724 289 5 5 724 289 729 294 +1 3 0 1 5 0 0 0 0.000 1 0.000 169 479 5 5 169 479 174 484 +1 3 0 1 5 0 0 0 0.000 1 0.000 669 159 5 5 669 159 674 164 +1 3 0 1 4 0 0 0 0.000 1 0.000 724 249 5 5 724 249 729 254 +1 3 0 1 4 0 0 0 0.000 1 0.000 329 144 5 5 329 144 334 149 +1 3 0 1 4 0 0 0 0.000 1 0.000 469 144 5 5 469 144 474 149 +1 3 0 1 5 0 0 0 0.000 1 0.000 169 319 5 5 169 319 174 324 +1 3 0 1 2 0 0 0 0.000 1 0.000 359 304 5 5 359 304 364 309 +1 3 0 1 4 0 0 0 0.000 1 0.000 359 284 5 5 359 284 364 289 +1 3 0 1 6 0 0 0 0.000 1 0.000 359 324 5 5 359 324 364 329 +1 3 0 1 5 0 0 0 0.000 1 0.000 394 494 5 5 394 494 399 499 +1 3 0 1 4 0 0 0 0.000 1 0.000 394 434 5 5 394 434 399 439 +1 3 0 1 6 0 0 0 0.000 1 0.000 394 474 5 5 394 474 399 479 +2 1 0 1 5 0 0 0 0.000 7 1 0 + 0 0 1.000 4.000 8.000 + 169 479 299 479 9999 9999 +2 1 0 1 1 0 0 0 0.000 -1 0 1 + 0 0 1.000 4.000 8.000 + 394 164 329 164 9999 9999 +3 2 0 1 1 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 169 139 199 139 219 144 239 149 254 149 9999 9999 + 0.000 -190.000 186.321 138.362 193.821 138.362 203.746 139.584 + 214.444 142.861 223.556 145.139 234.254 148.416 241.590 149.319 + 245.340 149.319 0.000 -190.000 +3 2 0 1 1 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 669 139 704 144 719 154 734 234 9999 9999 + 0.000 -190.000 689.270 140.465 698.020 141.715 708.066 145.553 + 716.306 149.925 728.121 167.798 731.871 187.798 0.000 -190.000 +3 2 0 1 2 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 329 184 319 184 314 184 304 194 304 199 304 259 9999 9999 + 0.000 0.000 323.209 184.000 320.709 184.000 317.861 184.000 + 315.246 183.484 310.477 185.460 305.459 190.476 303.484 195.246 + 304.000 197.861 304.000 209.251 304.000 224.251 0.000 0.000 +3 2 0 1 2 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 359 304 389 309 399 339 404 384 404 419 9999 9999 + 0.000 0.000 376.183 303.206 383.683 304.456 396.372 315.299 + 397.434 331.869 401.243 349.210 403.427 373.663 404.332 389.993 + 404.332 398.743 0.000 0.000 +3 2 0 1 2 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 469 184 504 189 534 229 549 289 9999 9999 + 0.000 0.000 489.097 184.107 497.847 185.357 515.602 195.870 + 528.871 218.224 538.758 238.997 542.508 253.997 0.000 0.000 +3 2 0 1 2 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 724 289 709 299 704 414 9999 9999 + 0.000 0.000 714.657 293.115 710.907 295.615 696.821 320.614 + 695.571 349.364 0.000 0.000 +3 2 0 1 5 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 394 494 444 499 569 499 639 499 9999 9999 + 0.000 0.000 422.899 497.321 435.399 498.571 472.526 500.423 + 540.524 499.000 580.960 499.000 598.460 499.000 0.000 0.000 +3 2 0 1 5 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 669 159 649 159 634 164 604 204 579 289 9999 9999 + 0.000 0.000 657.478 158.436 652.478 158.436 645.334 159.595 + 637.243 161.663 623.745 171.392 609.302 193.426 596.954 218.053 + 590.704 239.303 0.000 0.000 +3 2 0 1 4 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 394 434 414 429 419 424 414 279 364 219 9999 9999 + 0.000 0.000 405.666 432.138 410.666 430.888 415.525 428.137 + 418.291 425.798 433.545 387.100 427.322 313.905 408.621 264.907 + 396.121 249.907 0.000 0.000 +3 2 0 1 4 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 569 304 554 234 529 189 504 174 9999 9999 + 0.000 0.000 562.162 263.254 558.412 245.754 549.770 222.731 + 537.823 198.122 525.252 185.125 519.002 181.375 0.000 0.000 +3 2 0 1 4 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 359 284 359 249 354 219 9999 9999 + 0.000 0.000 359.497 263.759 359.497 255.009 358.568 243.779 + 357.318 236.279 0.000 0.000 +3 2 0 1 4 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 734 434 724 379 724 324 9999 9999 + 0.000 0.000 727.366 402.355 724.866 388.605 723.148 369.549 + 723.148 355.799 0.000 0.000 +3 2 0 1 4 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 724 249 719 209 699 174 9999 9999 + 0.000 -190.000 722.530 225.840 721.280 215.840 716.720 202.160 + 711.720 193.410 0.000 -190.000 +3 2 0 1 4 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 329 144 304 144 269 139 219 124 204 124 9999 9999 + 0.000 -190.000 314.537 144.305 308.287 144.305 295.917 143.426 + 276.919 140.743 257.308 136.426 231.067 125.771 216.399 123.618 + 212.649 123.618 0.000 -190.000 +3 2 0 1 5 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 169 319 189 319 229 324 254 329 264 329 9999 9999 + 0.000 0.000 180.574 318.787 185.574 318.787 198.208 319.573 + 219.921 322.527 234.742 324.932 248.152 328.421 255.720 329.170 + 258.220 329.170 0.000 0.000 +3 2 0 1 6 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 394 474 339 469 299 469 259 469 234 469 204 469 9999 9999 + 0.000 0.000 362.200 470.679 348.450 469.429 329.874 468.586 + 308.112 469.000 289.888 469.000 268.112 469.000 253.305 469.000 + 239.695 469.000 228.874 469.000 221.374 469.000 0.000 0.000 +3 2 0 1 6 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 734 474 659 469 434 484 299 489 204 489 9999 9999 + 0.000 0.000 690.661 470.250 671.911 469.000 607.354 469.001 + 485.316 481.339 403.258 485.594 329.783 488.430 282.765 489.301 + 259.015 489.301 0.000 0.000 +3 2 0 1 6 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 569 344 594 339 619 304 634 204 644 174 9999 9999 + 0.000 0.000 583.473 343.015 589.723 341.765 603.620 332.780 + 615.079 313.689 628.219 281.222 628.581 226.603 635.271 198.699 + 637.771 191.199 0.000 0.000 +3 2 0 1 6 0 0 0 0.000 1 0 + 0 0 1.000 4.000 8.000 + 359 324 294 319 204 309 9999 9999 + 0.000 0.000 321.344 321.293 305.094 320.043 278.591 317.552 + 256.091 315.052 0.000 0.000 +3 2 0 1 5 0 0 0 0.000 0 1 + 0 0 1.000 4.000 8.000 + 429 514 564 519 714 519 734 514 9999 9999 + 0.000 0.000 507.163 517.323 540.913 518.573 598.180 519.633 + 679.471 523.251 717.559 518.562 722.559 517.312 0.000 0.000 +3 2 0 1 4 0 0 0 0.000 0 1 + 0 0 1.000 4.000 8.000 + 204 99 364 109 414 139 469 144 9999 9999 + 0.000 0.000 296.049 97.811 336.049 100.311 377.555 113.214 + 400.605 134.627 423.515 142.106 437.265 143.356 0.000 0.000 +4 0 0 12 0 -1 0 0.000 4 9 15 159 104 foo +4 0 0 12 0 -1 0 0.000 4 6 5 479 129 c +4 0 0 12 0 -1 0 0.000 4 12 42 309 209 depends +4 0 0 12 0 -1 0 0.000 4 12 42 449 209 depends +4 0 0 12 0 -1 0 0.000 4 9 6 744 234 b +4 0 0 12 0 -1 0 0.000 4 6 18 714 314 rec. +4 0 0 12 0 -1 0 0.000 4 6 6 164 264 a +4 0 0 12 0 -1 0 0.000 4 9 6 164 424 b +4 0 0 12 0 -1 0 0.000 4 6 5 664 104 c +4 0 0 18 0 -1 0 0.000 4 17 632 64 54 example of the structures (in the C code) which contain related packages information +4 0 12 12 0 -1 0 0.000 4 12 70 284 589 Package: a +4 0 0 12 0 -1 0 0.000 4 6 6 374 269 a +4 0 0 12 0 -1 0 0.000 4 9 6 384 419 b +4 0 0 12 0 -1 0 0.000 4 9 15 339 129 a|b +4 0 12 12 0 -1 0 0.000 4 12 70 674 589 Package: b diff --git a/doc/deb-control.5 b/doc/deb-control.5 new file mode 100644 index 000000000..9436641c6 --- /dev/null +++ b/doc/deb-control.5 @@ -0,0 +1,104 @@ +.\" Hey, Emacs! This is an -*- nroff -*- source file. +.\" Author: Raul Miller +.\" Includes text from the debian Guidelines by Ian Jackson, Ian Murdock +.TH DEB-CONTROL 5 "29th November 1995" "Debian Project" "Debian GNU/Linux" +.SH NAME +deb\-control \- Debian GNU/Linux packages' master control file format +.SH SYNOPSIS +control +.SH DESCRIPTION +Master control file format: +.LP +The `control' file contains a number of fields. Each field begins +with a tag, such as `PACKAGE' or `VERSION' (case insensitive), +followed by a colon, and the body of the field. Fields are delimited +only by field tags. In other words, field text may be multiple lines +in length, but the installation tools will generally join lines when +processing the body of the field. +.SH REQUIRED FIELDS +.TP +.BR PACKAGE: \ <Short\ name\ of\ package> +The value of this field is used to generate file names by some +installation tools. +.TP +.BR VERSION: \ <Original\ version\ number> +typically, this is the original portable package's version +number in whatever form the program's author uses. +.TP +.BR PACKAGE_REVISION: \ <Debian\ package\ revision\ number> +this should usually be a plain number, or perhaps two numbers +separated by a full stop. +.TP +.BR MAINTAINER: \ <Name\ and\ e-mail\ address\ of\ package\ maintainer> +should be in the format Joe Bloggs <jbloggs@foo.com>. +.TP +.BR DESCRIPTION: \ <Description\ of\ package> +.SH OPTIONAL FIELDS +.TP +.BR DEPENDS: \ <Short\ names\ of\ prerequisite\ packages> +list of packages that are required for this package to provide a +non-trivial amount of functionality. The package maintenance software +will not allow a package to be installed without also installing +packages listed in its +.B DEPENDS +field, and will rin the postinst scripts of packages listed in DEPENDS +fields before those of the packages which depend on them, and run +prerm scripts before. +.TP +.BR RECOMMENDED: \ <Short\ names\ of\ related,\ recommended\ packages> +lists packages that would be found together with +this one in all but unusual installations. The package maintenance +software will warn the user if they install a package without those +listed in its +.B RECOMMENDED +field. +.LP +The syntax of +.B DEPENDS +and +.B RECOMMENDED +is a list of groups of alternative packages. Each group is a list of +packages separated by vertical bar (or `pipe') symbols, `|'. The +groups are separated by commas. Each package is a package name +optionally followed by a version number specification in parentheses. +A version number may start with a `>', in which case any later version +will match, and may specify or omit the Debian packaging revision +(separated by a hyphen). Commas are to be read as `AND', and pipes as +`OR', with pipes binding more tightly. +.TP +.BR OPTIONAL: \ <Short\ names\ of\ related,\ optional\ packages> +lists packages that are related to this one and can perhaps enhance +its usefulness, but without which installing this package is perfectly +reasonable. The package maintenance software will not moan at the +user for not selecting +.B OPTIONAL +related packages, but may use the information in the +.B OPTIONAL +field to assist the user during package selection. +.TP +.BR CONFLICTS: \ <Short\ names\ of\ packages\ which\ conflict\ with\ this\ one> +lists packages that conflict with this one, for example by containing +files with the same names (an example would be Smail vs. Sendmail). +The package maintenance software will not allow conflicting packages +to be installed. Two conflicting packages should each include a +.B CONFLICTS +line mentioning the other. +.LP +The syntax of +.B OPTIONAL +and +.B CONFLICTS +is a list of package names, separated by commas (and optional +whitespace). In the +.B CONFLICTS +field, the comma should be read as `OR'. + +.SH BUGS +This manpage is seriously out of date. + +.SH SEE ALSO +.BR deb (5), +.BR dpkg (5), +.BR dpkg (8), +.BR dpkg-dep (8), +.BR dselect (8). diff --git a/doc/deb.5 b/doc/deb.5 new file mode 100644 index 000000000..35070eb8e --- /dev/null +++ b/doc/deb.5 @@ -0,0 +1,69 @@ +.\" Hey, Emacs! This is an -*- nroff -*- source file. +.\" Author: Raul Miller +.TH DEB 8 "29th November 1995" "Debian Project" "Debian GNU/Linux" +.SH NAME +deb - Debian GNU/Linux package format +.SH SYNOPSIS +.IB <packagename>.deb +.SH DESCRIPTION +Debian archive file format. +Version 0.93 is implemented as follows: +.TP +line 1: +version number +.RB ( 0.93 ...), +followed by +.BR newline . +.TP +line 2: +number of characters occupied by control area expressed in decimal, +followed by +.BR newline . +.TP +control area: +compressed gzipped ustar formatted archive. Must contain file named +.BR control . +May optionally contain files named: +.BR conffiles , +.BR preinst , +.BR prerm , +.BR postint , +.BR postrm . +.TP +files archive area: +compressed gzipped ustar formatted archive. [with file structures +designed to be unpacked in the root directory]. +.SH FILES +The files represented in the control area have special significance: +.TP +.B control +see +.BR deb-control (5). +.TP +.B conffiles +a line delimited list of "configuration files" which have special +significance to +.BR dpkg (8). +.TP +.B preinst +an executable to be run before unpacking the archived files. +.TP +.B prerm +an executable to be run before removing files from a prior installation. +.TP +.B postinst +an executable to be run after unpacking the archived files. +.TP +.B postrm +an executable to be run after removing files from a prior +installation. + +.BUGS +There is a new package format, which is not documented here. + +.SH SEE ALSO +.BR deb-control (5), +.BR dpkg (5), +.BR dpkg (8), +.BR dpkg-dep (8), +.BR dselect (8). diff --git a/doc/dependency-ordering.txt b/doc/dependency-ordering.txt new file mode 100644 index 000000000..f3f679408 --- /dev/null +++ b/doc/dependency-ordering.txt @@ -0,0 +1,97 @@ +To: Debian developers list <debian-devel@pixar.com> +Subject: Note about the default for virtal package dependencies + +As I wrote some time ago (see below), ordering is significant in the +Depends and Recommended fields - in the absence of other information +dselect will suggest to the user that they select the first named +package in a list of options. + +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. + +Eg, if we have: + Package: glibcdoc + Recommended: info-browser + + Package: info + Provides: info-browser + + Package: emacs + Provides: info-browser + +then (if emacs and info are both in the same Class) dselect's choice +will be essentially random. + +It is important to think about this problem, and to consider whether +to list one the the packages explicitly. + +For example, + Package: glibcdoc + Recommended: info | info-browser + +will do the same as the above, except that it will ensure that `info' +is the package which dselect will suggest to the user they also select +if the user has neither it nor Emacs and asks to select glibcdoc. + +This is not necessary if one of the packages has a more fundamental +Class - see the details below. + +Ian. + +------- Start of forwarded message ------- +To: Debian developers list <debian-devel@pixar.com> +Subject: Ordering is significant in Depends: and Recommends: + +For dselect, the ordering of alternative packages in a Depends: or +Recommended: line is significant. + +When an unsatisfied dependency (Depends or Recommended) or a conflict +is detected dselect will go into a `recursive package list', where the +user gets to choose how to resolve the problem. + +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. + +However, in the absence of other information dselect will prefer +packages listed earlier in the unsatisfied entry in the Depends or +Recommended field. + +NB: this doesn't apply to constructions of the form: + Package: auctex + Depends: emacs, tex +which specifies that auctex depends on *both* emacs and tex. In this +case dselect will suggest to the user that they select both packages. + +It applies to constructions of the form: + Package: a2gs + Recommended: gs_x | gs_both | gs_svga +Here, dselect will prefer gs_x because it is listed earlier. (In the +future I may make it more clever - it may be able to notice, to +continue the example, that the dependencies of gs_x are not yet +satisfied while those of gs_svga, are, and thus prefer the latter, or +in a different situation to notice that gs_both has extra dependencies +which are satisfied, and thus prefer it to gs_x and gs_svga. More +thought is needed in this area.) + +One final example. In the more complicated construction: + Package: trn + Depends: smail | sendmail, inn | inewsinn +dselect will prefer smail because it is a Standard package, and +Sendmail is only Optional, and will prefer inewsinn because it is +Recommended and inn is only Optional. So, the default (if none of the +other packages were selected) would be to select smail and inewsinn. + +However, if inewsinn were moved to Optional this would change, and inn +would be preferred whenever the issue arose after the change. + +Optional fields have the same structure as Depends and Recommended +fields, but they will not arrange for the packages they list to be +suggested for selection, though they will be offered to the user. + +Ian M: can this go in an appendix to the Guidelines ? + +Ian. +------- End of forwarded message ------- diff --git a/doc/descriptions.txt b/doc/descriptions.txt new file mode 100644 index 000000000..fdc302b1a --- /dev/null +++ b/doc/descriptions.txt @@ -0,0 +1,112 @@ +To: Debian developers list <debian-devel@pixar.com> +Subject: Package maintainers please look at your Description fields. + +dselect will be much more useful when more packages are more +informative in the Description they provide in their control file. + +So, when you next release a package, could you please check whether +the `control' file has a good description of the package, formatted as +described below ? + +A small amount of effort here on the part of package maintainers will +improve the looks of things quite a bit, I think. + +BTW, a number of packages have been indenting continuation lines in +their Description fields thus: + Description: gnomovision + Gnomovision is .... + further blurb ... +Please don't do this. According to the scheme described below (which +I've now implemented), dselect interprets the extra indentation to +mean `preformatted' text, and doesn't wordwrap it. + +Ian. + + +The format of the Description field is as follows: + +Description: <single line synopsis> + <extended description over several lines> + +The extended description has several kinds of line: + + - 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. + + - 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 right, for example). + + - those containing a single space followed by a single full stop +character. These are rendered as blank lines. This is the ONLY way +to get a blank line - see below. + + - those containing a space, a full stop and some more characters. +These are for future expansion. Don't use them. + +IMPORTANT and not so important TIPS: + +* 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 in +RFC822. Forgetting the whitespace will cause dpkg-deb (>=0.93.23) to +produce a syntax error when trying to build the package. If you force +it to build anyway dpkg will refuse to install the resulting mess. + +* DO NOT INCLUDE ANY COMPLETELY EMPTY LINES. These separate different +records in the Packages file, and are forbidden in control files. See +the previous paragraph for what happens if you get this wrong. + +* The single line synopsis should be kept brief - certainly under 80 +characters. My current working half-dselect displays the first 49 +characters if you're using an 80-column terminal. + +* Don't include the package name in the synopsis line. The display +software knows how to display this already, and you don't need to +state it. + +* The extended description should describe what the package does, and +what component it forms of any larger subsystem of which it is a part. + +* 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. + +* You may include information about dependencies and so forth in the +extended description, if you wish. + +* Don't use tab characters. Their effect is not predictable. + +Example control file for Smail: + +Package: smail +Version: 3.1.29.1 +Package_Revision: 8 +Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk> +Recommended: pine | elm | emacs | mh | mailx +Optional: metamail +Depends: cron +Conflicts: sendmail +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. + +-- +Ian Jackson, at home. ijackson@nyx.cs.du.edu or iwj10@cus.cam.ac.uk ++44 1223 575512 Escoerea on IRC. http://www.cl.cam.ac.uk/users/iwj10/ +2 Lexington Close, Cambridge, CB4 3LS, England. Urgent: iwj@cam-orl.co.uk diff --git a/doc/disappear-replace.txt b/doc/disappear-replace.txt new file mode 100644 index 000000000..8335a0ea4 --- /dev/null +++ b/doc/disappear-replace.txt @@ -0,0 +1,44 @@ +From ian Tue Apr 18 23:30:04 1995 +X-VM-v5-Data: ([nil nil nil nil nil nil nil nil nil] + [nil nil nil nil nil nil nil nil nil nil nil nil "^To:" nil nil nil nil nil nil nil] + nil) +X-VM-Summary-Format: "%3n %a %2d %3m %-19.19F %s\n" +X-VM-Labels: nil +X-VM-VHeader: ("Resent-" "From:" "Sender:" "To:" "Apparently-To:" "Cc:" "Subject:" "Date:") nil +X-VM-Bookmark: 5 +To: Debian developers list <debian-devel@pixar.com> +Subject: Handling of base packages + +I propose to implement the following scheme to enable obsolete base +packages to disappear, and to allow files in the base packages to move +between one package and another. + +1. When a package is installed, and contains files that are already +marked as belonging to some other package, the older package will have +the files that have been overwritten removed from its file list. + +2. When a package ceases to contain any files due to the action of +point 1 above, its postrm script is run with the argument `disappear' +(in place of `remove', `purge' or whatever). It will then be moved +into the `purge ok not-installed' state, so that it will cease to +appear in dpkg and dselect lists. Its conffiles will be ignored, +*not* purged. The prerm will *not* be run as the packaging system +doesn't know what files are in a package until it unpacks it. + +This will all happen during the `unpack' phase of the replacing +package. + +3. If a base system package which is being installed conflicts with +another base system package which is currently installed on the +system, the currently installed one will be removed first (the prerm +will be run with `replace <package> <version>' as arguments, then the +package will be removed, then the postrm will be run, likewise with +`replace'). If the replacement fails the removal will be aborted, +involving running the old packages' scripts with `abort-replace'. + +4. Base system packages may not be removed except under 2. or 3. +above. (There will be a --force-remove-base flag to allow foolhardy +users to go ahead anyway.) + +Ian. + diff --git a/doc/diversions.text b/doc/diversions.text new file mode 100644 index 000000000..8cfec095a --- /dev/null +++ b/doc/diversions.text @@ -0,0 +1,131 @@ +(These messages have been edited to conform to the terminology +eventually decided on.) + +------- start of digest (2 messages) (RFC 934 encapsulation) ------- +Resent-Message-Id: <m0tcceI-0002c6C@chiark.chu.cam.ac.uk> +Resent-From: ijackson (Ian Jackson) +Resent-To: ian +From: ian@chiark.chu.cam.ac.uk (Ian Jackson) +To: Debian developers list <debian-devel@pixar.com> +Subject: `diverting' dpkg for a particular file +Date: Wed, 17 Jan 96 18:31 GMT + +I'm almost finished with the implementation of a feature for dpkg that +will allow the sysadmin or package maintainer to prevent dpkg from +overwriting a particular file. + +Instead, whenever dpkg finds a package containing that file it +`redirects' the reference to an alternative name. + +Eg, if you were to `divert' /usr/sbin/smail to /usr/sbin/smail.real +then any package containing /usr/sbin/smail would have the file placed +as /usr/sbin/smail.real instead. The feature will work during package +removal, as well. + +There's provision for a single package to be named which is allowed to +provide a version of the file which will installed under the original +name. + +This feature shouldn't be mixed with the conffiles update mechanism, +as this is unlikely to produce useful results and likely to produce +confusion on the part of the user at the very least and possibly on +the part of dpkg too :-). + +No package should contain a file whose name is the diverted name of +another file; dpkg will spot this and balk if such a package is +installed when the diversion is in place, or if a diversion is set up +which involves overwriting an existing file whether managed by dpkg +or not (this latter check only happens if dpkg-divert is given the +--rename option which makes it actually rename any copy of the file +found in the filesystem). + +Only one diversion for a particular file is allowed, and you can't +divert A to B and then B to C. + +[...] + +This feature is intended to be used sparingly; a system administrator +can use it to keep a locally-installed version of a piece of system +software that has to live in a particular place. + +A package should preferably only use it if the package's main function +is to replace the file in question (whether or not the diverted - ie, +replaced, in this case - version of the file needs to be available); +otherwise a sysadmin might find that the feature wasn't available to +them when they wanted to install their own version of the file because +a package had already done so. + +It's possible that I might introduce a facility that would allow +*requests* for redirection of files to be redirected themselves, by +using a special 2nd-level redirection option. + +Ian. +------------------------------ +To: debian-devel@Pixar.com +Subject: Re: `overriding' dpkg for a particular file + +[...] +Forgive me for being perhaps rather baseic, but here are two examples, +diagrammatically: + +1. Administrator wants to replace a Debian-provided program with + their own version, or wants to put a wrapper around it: + ____________________ + smail.deb___________ / \ + | ... | |\____________________/| + | /usr/sbin/smail --+----. | | + | ... | \ | / | + |___________________| \ | /usr | + \ | /usr/sbin | + `-------> /usr/sbin/smail.real | + .-------> /usr/sbin/smail | + ~/stuff/smail/wrapper.c / | | + ~/stuff/smail/wrapper ----' \____________________/ + + # dpkg-divert --divert /usr/sbin/smail.real /usr/sbin/smail + # cp ~fred/stuff/smail/wrapper /usr/sbin/smail + +2. Package maintainer wants to provide an `improved' version of a + file in another package. + + fileutils.deb_______ ____________________ + | ... | / \ + | /bin/ls ----------+----. |\____________________/| + | ... | \ | | + |___________________| \ | / | + \ | /bin | + colour-ls.deb_______ `-------> /bin/ls.mono | + | ... | .--------> /bin/ls | + | /bin/ls ----------+------' | | + | ... | \____________________/ + |...................| + |preinst: | + | dpkg-divert --divert /bin/ls.mono \ + | --package colour-ls /bin/ls + |...................| + |postrm: | + | dpkg-divert --remove --divert /bin/ls.mono \ + | --package colour-ls /bin/ls + |___________________| + +We need a name that applies to `/usr/sbin/smail.real' and +`/bin/ls.mono', the filenames, in both situations, and another name +to apply to `/usr/sbin/smail' and `/bin/ls'. + +Raul Miller writes ("Re: `overriding' dpkg for a particular file"): +[...] +> Also, it would be nice to see either some documentation or some sort +> of warning about the case where the file is a directory. + +If the file is a directory there will be no good effect. This is +because the redirection would affect only the entry for the directory +itself in the packages whose instances if it were being redirected, +and would not affect any of the files in it. + +The most likely result is that dpkg will fail to install the package +because one of the directories where it has files doesn't exist. It +would probably create the `diverted' name of the directory, fail, and +then clean it up. + +Ian. +------- end ------- diff --git a/doc/dpkg.texi b/doc/dpkg.texi new file mode 100644 index 000000000..b9530d6a5 --- /dev/null +++ b/doc/dpkg.texi @@ -0,0 +1,101 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename dpkg.info +@settitle The @code{dpkg} Package Maintenance System +@c %**end of header + +@ifinfo +@format +START-INFO-DIR-ENTRY +* dpkg: (dpkg). The @code{dpkg} package maintenance system. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@setchapternewpage off + +@ifinfo +This file documents the @code{dpkg} package maintenance system. + +Copyright (C) 1994 Ian A. Murdock + +Permission is granted to make and distribute verbatim copies of this +document provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one, except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +document under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this document +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by The Debian Linux Association. +@end ifinfo + +@titlepage +@title The @code{dpkg} Package Maintenance System +@author Ian A. Murdock +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1994 Ian A. Murdock + +Permission is granted to make and distribute verbatim copies of this +document provided the copyright notice and this permission notice are +preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +document under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this document +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by The Debian Linux Association. +@end titlepage + +@node Top, Overview, (dir), (dir) + +@top Introduction +@menu +* Overview:: An overview of the @code{dpkg} package + maintenance system. +* Installation:: How to install a package with @code{dpkg}. +* Removal:: How to remove a package with @code{dpkg}. +* Information:: How to obtain information about both + installed and not-yet-installed packages. +* Extension:: How to extend @code{dpkg} to support new + package formats. +* Guidelines:: Guidelines for creating and maintaining + packages for Debian GNU/Linux. +@end menu + +@node Overview +@chapter Overview + +@node Installation +@chapter Package Installation + +@node Removal +@chapter Package Removal + +@node Information +@chapter Package Information + +@node Guidelines +@chapter Debian GNU/Linux Guidelines + +@node Extension +@chapter How to Extend @code{dpkg} to Support New Package Formats + +@bye diff --git a/doc/essential-flag.txt b/doc/essential-flag.txt new file mode 100644 index 000000000..34e821135 --- /dev/null +++ b/doc/essential-flag.txt @@ -0,0 +1,43 @@ +From ian Thu Jul 6 21:14:08 +0100 1995 +X-VM-v5-Data: ([nil nil nil nil nil nil nil nil nil] + [nil nil nil nil nil nil nil nil nil nil nil nil "^To:" nil nil nil nil nil nil nil] + nil) +In-Reply-To: <m0sTw2a-00063aC@mongo.pixar.com> +References: <m0sTw2a-00063aC@mongo.pixar.com> +To: debian-devel@pixar.com +Subject: Re: non-uninstallable packages + +Bruce Perens writes ("non-uninstallable packages"): +> Assume that a package, such as one in the base, is supposed to be +> non-uninstallable because it is a critical system component. We should +> specify that in an unambiguous form, rather than indicating it by +> specifying "Class: base" in the control file. +> +> I suggest yet another control file field, called "Flags: ". This is +> followed by a comma-delimited set of flags. An example might be: +> Flags: no-uninstall +> +> Another alternative would be to add control-file fields for each flag. +> In this case, the field would appear as: +> Allow-uninstall: no +> ...and the default would be "yes". + +I think you're right. Bill spotted that we were trying to overload +the `Class' field. + +I don't think there's any need for a generic `Flags:' field; a simple +extra field is fine, unless we're going to have an awful lot of +boolean flags applying to packages (any attribute with a value is +better handled using a field of its own anyway). + +I propose to call the new field `Essential', with allowable values +`yes' and `no' and a default of `no'. + +This will be clearer all round, I think, than attempting to describe +dpkg behaviour in the field name. + +If I don't have to make an emergency bugfix release of dpkg first this +will be in the next version. I'll modify dselect too. + +Ian. + diff --git a/doc/guidelines.info-1 b/doc/guidelines.info-1 new file mode 100644 index 000000000..ac9171445 --- /dev/null +++ b/doc/guidelines.info-1 @@ -0,0 +1,1039 @@ +This is Info file guidelines.info, produced by Makeinfo-1.63 from the +input file ./guidelines.texi. + +START-INFO-DIR-ENTRY +* Guidelines: (guidelines). How to make Debian packages. +END-INFO-DIR-ENTRY + + +File: guidelines.info, Node: Top, Next: Additional Information, Prev: (dir), Up: (dir) + +Debian GNU/Linux Packaging Guidelines +************************************* + + This file documents the steps that must be taken in the preparation +of a Debian GNU/Linux package. All submissions to be included in the +distribution proper and all packages to be considered for `contrib' or +`non-free' availability *must* conform to the guidelines and standards +described in this document or they cannot be included or made available +at the archive with the distribution. + + Please read the Guidelines carefully. If you have comments or +questions, please contact `debian-devel@pixar.com'. If you are +planning on going further than just contributing a package (i.e., if +you plan to maintain it for an extended period of time or if you are +generally interested in becoming more involved in the Project), you +should join the `debian-devel' mailing list. For more details, read +`info/mailing-lists.txt', available at any Debian GNU/Linux archive. + + (This file was last updated on 26th January 1996. Please check the +most recent `dpkg' package at any Debian GNU/Linux archive for a +potentially more up to date copy.) + +* Menu: + +* Additional Information:: Where other info is to be found. +* Package Copyright:: A few words about the importance of + understanding the package copyright. +* Package Content:: Requirements for the package content. +* Source Package:: Creating the source package. +* Binary Package:: Creating the binary package. +* Control Files:: The binary package control files. +* Appendix:: More specific details about some aspects. + + +File: guidelines.info, Node: Additional Information, Next: Package Copyright, Prev: Top, Up: Top + +Additional Information +********************** + + These Guidelines are intended to be fairly general. More specific +information is available about certain aspects of building packages, +such as how to use the features of Init under Debian GNU/Linux and how +to interact with some more technical details of dpkg's operation. This +information can be found in the directory `doc/package-developer' at +any Debian GNU/Linux archive. At the time of this writing, the +following documents are available: + +`virtual-package-names-list.text' + The list of virtual package names currently in use, together with + the procedure for getting new virtual package names allocated. + +`auto-deconfiguration.txt' + How dpkg can sometimes automatically deconfigure packages in order + to do bulk installations smoothly. + +`dpkg-essential-flag.txt' + How to tell dpkg a package is essential and should not be removed. + (This is for the use of base system packages only.) + +`dpkg-disappear-replace.txt' + What happens when a package appears to have been completely + replaced. + + In the future, we hope also to make available: + +`copyright.txt' + How to choose a good copyright notice to attach to new programs. + +`version-ordering.txt' + The algorithm with which packages' version numbers are compared. + + Also, you should download the sample files and the sample package +(GNU Hello) available in `standards/samples'. You may use any of this +material as a starting point for new packages. The following sample +files, incidentally, are available: + + * debian.README + + * debian.control + + * debian.postinst + + * debian.postrm + + * debian.rules + + Some more detailed information about certain topics is available in +the appendix to this document (*note Appendix::.). + + +File: guidelines.info, Node: Package Copyright, Next: Package Content, Prev: Additional Information, Up: Top + +Package Copyright +***************** + + Please study the copyright of your submission *carefully* and +*understand it* before proceeding! If you have doubts or questions, +please ask! + + In order to understand how we classify and distribute certain +packages, it is important to understand the distinction between being +freely available and being freely redistributable. + + Being "freely available", quite simply, means that the software can +be made available freely, at least for non-commercial purposes and in +its original, unmodified form. This includes packages made available +freely that have restrictions on non-commercial use, redistribution of +modifications, etc. Being freely available, therefore, has nothing to +do with being able to modify and redistribute the software. It only +means that you can get a copy of the software without having to pay +(and it does not necessarily mean that you can *use* the software +without having to pay--shareware is an example of freely available +software). + + "freely redistributable", while generally being freely available, +goes beyond just being freely available. Freely redistributable means +that that the software, in addition to being able to be made available +freely, must be able to be freely modified and redistributed without +restriction. + + All submissions to be included in the distribution proper *must* be +freely redistributable. + + In addition to the distribution, the Project maintains two separate +archives of software packages with the distribution: the `contrib' +archive and the `non-free' archive. + + `contrib' is an archive of user-contributed packages that are not +maintained by the Project, packages that were once maintained by the +Project but that are no longer actively maintained, and packages that +are maintained by the Project but that are not yet considered ready for +inclusion in the distribution proper (i.e., ALPHA and BETA packages). +As above, all submissions for inclusion in the `contrib' archive *must* +be freely redistributable. + + `non-free' is an archive of packages with either restrictive or +unclear terms of copying or modification. If a package has *any* +restrictions on modification or redistribution, it can not be included +in the distribution or `contrib' archive. It can only be included in +the `non-free' archive, and then only if it is freely available. + + In summary, in order to be included in the distribution proper or the +`contrib' archive, a package must be *freely redistributable*. Anyone +must be able to make copies of it, modify it, redistribute it with +their modifications in place, include it on a CD-ROM, or generally sell +it. To be included in the `non-free' archive, a package may have +restrictions, as long as the package remains *freely available*. We +must be available to make it available freely at the archive, and anyone +must be able to make copies of it and use it for at least +non-commercial, personal purposes. Software that will typically be +included in `non-free' are software that does not allow commercial +distribution, software that does not allow modification or +redistribution of modifications, commercial "demos", and "shareware". + + When in doubt, send mail to `iwj10@cus.cam.ac.uk' and +`imurdock@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". + + Every package submission *must* be accompanied by verbatim copy of +its copyright (with the exceptions of public domain packages and those +covered by the UCB BSD licence or the GNU GPL or LGPL; in these cases +simply indicate which is appropriate). This information must be +included in a file installed to the directory `/usr/doc/copyright'. +See below for details. + + +File: guidelines.info, Node: Package Content, Next: Source Package, Prev: Package Copyright, Up: Top + +Package Content +*************** + + The following requirements apply equally to both the binary and +source packages. In either case, when files have been installed, they +must conform to the requirements described in this section. + + The primary rule in Debian GNU/Linux is to follow the Linux "File +System Standard" ("FSSTND"). The location of installed files *must* +comply *fully* with the FSSTND. The latest version of this document +can be found alongside the Guidelines or at `tsx-11.mit.edu' in +`/pub/linux/docs/linux-standards/fsstnd'. Specific questions about +following the standard should be addressed to Daniel Quinlan, the +FSSTND coordinator, at `quinlan@yggdrasil.com'. + + In addition to the FSSTND, all Debian GNU/Linux packages must follow +the guidelines below. + + * Directories should be mode 755 or (for group-writability) mode + 2775, with the exception of special "system" directories that need + to be another mode. 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, of course. + Use common sense in assigning permissions and ownerships to + directories, and make sure that what is done is secure if it is + "non-standard". + + * Normal binaries should be mode 755 and owned by `root.root'. If + there is a good reason to use a different mode or ownership, you + may do so, but you must try to be as consistent as possible with + the rest of the system. If you need to use a different mode or + ownership, please discuss it with `imurdock@debian.org'. + + * Setuid binaries should normally be mode 4755 (not 4711!) and, of + course, owned by the appropriate user. + + * Setgid binaries should normally be mode 2755 (not 2711!) and, of + course, owned by the appropriate group. + + * Library files should generally be mode 644 and owned by + `root.root'. If the package requires different permissions or + ownerships to function correctly, they should be used instead. + + * Manual pages should be mode 644 and owned by `root.root'. The + `nroff' source must be installed. You should *not* install a + preformatted "cat page", and you should only use sections 1 to + 9--see the FSSTND for more details. 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 `undocumented'(7) manual page should + be provided. This symbolic link can be created from `debian.rules' + like this: + + ln -s ../man7/undocumented.7 debian-tmp/usr/man/man[1-9]/the_requested_manpage.[1-9] + + Do not close the bug report until a proper manpage is available. + You may forward the complaint to the upstream maintainers, and + mark the bug as forwarded in the Debian bug tracking system. The + GNU Project do not in general consider the lack of a manpage to be + a bug, but we do - if they tell you to go away leave the bug open + anyway. + + * Info documents should be mode 644, owned by `root.root', and + compressed with `gzip -9' when installed. The package must call + `install-info' to update the Info `dir' file. This should be done + in the post-installation script (`postinst'), like this: + + install-info --quiet /usr/info/foobar.info + + The entries should be removed by the pre-removal script (`prerm'), + like this: + + install-info --quiet --remove /usr/info/foobar.info + + It is also a good idea to specify a section for the Info `dir' + entry. This is done with the `--section' switch. To determine + which section to use, you should use look at `/usr/info/dir' on + your system and choose the most relevant (or create a new section + if none of the current sections are relevant). + + If `install-info' cannot find a description entry in the Info file + you will have to supply one. See `install-info'(8) for details. + + * If a package contains any shared libraries you will have to invoke + `ldconfig' in both the `postinst' and `prerm' scripts to correctly + update the library links. See `ldconfig'(8) for details. + + * Any additional documentation that comes with the package can be + installed at the discretion of the package maintainer. Text + documentation should be mode 644, owned by `root.root', installed + to `/usr/doc', and compressed with `gzip -9' unless it is small. + + If a subdirectory of `/usr/doc' is warranted, please do create one. + Please do not install DVI, PostScript, or large textual + documentation in the same package; upload such documentation as a + separate package (installing its files in `/usr/doc') so that it + can be made available with the distribution. If a user has the + need for the documentation, they can easily get it from the + archive, CD-ROM, etc., but it should not take up disk space on the + machines of the user who do not need or want it installed. + + * Create a file named `/usr/doc/copyright/<package>' which gives + details of the authorship and copyright of the package. If the + package is distributed under the GNU General Public Licence, the + GNU Library General Public Licence or the Regents of the + University of California at Berkeley (BSD) licence, please say so + instead of including a copy of the licence. The files `BSD', + `GPL', and `LGPL' will be available in the `/usr/doc/copyright' + directory for you to refer to. `/usr/doc/copyright/<package>' + should not be compressed. + + *All* authorship and copyright information from the original source + package must be included in the `/usr/doc/copyright/<package>' + file. + + * Any example files (for example, sample configuration files) should + be placed in the directory `/usr/doc/examples'. If the file is + normally a hidden file, such as `.emacs', then please call it + `dot.emacs', to avoid confusion. Again, you may create a + subdirectory if it is needed. + + * All symbolic links should be relative, not absolute. Absolute + links, in general, cause problems when a file system is not + mounted where it "normally" resides (for example, when mounted via + NFS). In certain cases, however, relative links may also cause + similar problems. I have generally made links into `/etc' and + `/var' absolute and all other links relative. There may be other + cases in which absolute links are necessary. + + Therefore, in the `Makefile' or `debian.rules', do not do: + install: all + [...] + ln -fs /usr/bin/gcc /usr/bin/cc + [...] + Instead, do: + ln -fs gcc /usr/bin/cc + or + ( cd /usr/bin ; ln -fs gcc cc ) + + Please do not create hard links in the manual page directories. In + these cases, you should use relative symbolic links or files that + `.so' (roff for `source') others instead. + + * All command scripts should have a `#!' line naming the shell to be + used to interpret them. + + * In the case of Perl scripts this should be `#!/usr/bin/perl' or + sometimes `#!/bin/perl', as follows: if the script is a critical + one that may be called when the `/usr' partition is unmounted or + broken it should use `/bin/perl'. Otherwise (especially if the + script is not specifically targetted at Debian) it should use + Perl's standard location, `/usr/bin/perl'. + + * Generally the following compilation parameters should be used: + + CC = gcc + CFLAGS = -O2 -g -Wall # sane warning options vary between programs + LDFLAGS = # none (or -N, if appropriate; see below) + install -s (or strip) + + Note that all installed binaries should be stripped, either by + using the `-s' flag to `install', or by calling `strip' on the + binaries after they have been copied into the `debian-tmp' but + before the tree is made into a package. + + Make sure that you do not link with `-g', as this makes a.out + compilers produce huge statically linked binaries. The `-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. + + `-N' should only be used on binaries that are very small (less than + 8K with the `-N' option, roughly) and are not likely to have + multiple instances in memory. Do not use `-N' on daemons, no + matter how small they are. + + 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 (`-O3', for example); feel free to use them. Please + use good judgment here. Don't add flags for the sake of adding + flags; only add flags if there is good reason to do so. + + * 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. + + * Logfiles should usually be named `/var/log/<package>', or + `/var/log/<package>.<something>' if you have several logfiles. It + may be appropriate to create a directory. Make sure that any + logfiles are rotated occasionally so that they don't grow + indefinitely; the best way to do this is to use `savelog' from the + cron package in an `/etc/cron.daily', `/etc/cron.weekly' or + `/etc/cron.monthly' script. + + * Please check with the base system maintainer (Ian Murdock) before + using users or groups other than `root' and others specified in + this document. + + +File: guidelines.info, Node: Source Package, Next: Binary Package, Prev: Package Content, Up: Top + +Source Package +************** + + The source package should contain a file called `debian.rules' which +contains at least the following targets, to be invoked in the top level +directory: + + build + binary + clean + + `debian.rules' should start with + + #!/usr/bin/make -f + +and be executable. It is a good idea to arrange for it not to fail +obscurely when invoked in the wrong directory, for example by testing +for the existence of a file in the source directory. + + * The `build' target should perform all non-interactive configuration + and compilation of the package. If a package has an interactive + pre-build configuration routine, the source package should be built + *after* this has taken place. + + For some packages, notably ones where the same source tree is + compiled in different ways to produce two binary packages, the + `build' target does not make much sense. For these packages it is + good enough to provide two (or more) targets (`build-a' and + `build-b' or whatever) for each of the ways of building the + package, and a `build' target that does nothing. The `binary' + target will have to build the package in each of the possible ways + and make the binary package out of each. + + * The `binary' target of `debian.rules' should be all that is + necessary for the user to build the binary package. The binary + package should be created using `dpkg' and placed in the parent of + the top level directory. The next section describes how to + construct binary packages from the `binary' target. + + * The `clean' target should undo the effects of the `build' target + and the `binary' target, except that it should leave alone any + `../<package>-<version>.deb' file created by a run of `binary'. + + * Additional targets may exist in `debian.rules'. We recommend using + `source' and `diff' targets to build the Debianised source package + and the Debianisation context diff, respectively. These files + should be placed in `../foo-<version>.tar.gz' and + `../foo-<version>.diff.gz'. The `install' target, for installing + into a running system direct from the Debianised source tree, is + no longer required. The sample `debian.rules' provides `source' + and `diff' targets that should work with little or no alteration, + providing that the package-specific variables at the top of the + script have been properly defined. + + * If you need to edit a `Makefile' where `configure' scripts are + used, you should edit the `.in' files rather than editing the + `Makefile' directly. This allows the user to reconfigure the + package if necessary. You should *not* configure the package and + edit the generated `Makefile'! This makes it impossible for + someone else to later reconfigure the package. + + * Please document your changes to the source package so that future + package maintainers know what has been changed. To do this, + include a description of your changes in the `debian.README' + (which, as described above, should already contain authorship and + copyright information!) and include relevant information such as + your name, electronic mail address, date, etc. The + `debian.README' file should also document any `unusual' packages + which must be installed for this one to compile. + + * If changes to the source code are made that are applicable to Linux + systems or systems in general 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. + + If changes to the source code are made, please use a `define'. If + they are changes required to compile or function under Linux in + general, use `LINUX'. If it is a cosmetic or functional change, + use `DEBIAN'. + + * Create the source package using `tar', and use `gzip -9' to + compress it. Source packages should be named in the form + <package>-<version>.tar.gz--for example, `fileutils-3.9-3.tar.gz'. + + NB, here `<version>' is the full Debian version number, in the + form `<original_version>-<debian_revision>' (see below), but the + tarfile should unpack into a directory named + `<package>-<original_version>' (again, see the section below on + version numbering). + + * Create the context diff against the original package using `diff + -cNr', and use `gzip -9' to compress it. Context diffs should be + named in the form <package>-<version>.diff.gz--for example, + `fileutils-3.9-3.diff.gz'. + + Please note that the package and patch filenames do *not* need to +fit in MS-DOS 8+3. They will be made available under an alternative +8+3 name in the archive by the archive maintainer, using a symlink. + + +File: guidelines.info, Node: Binary Package, Next: Control Files, Prev: Source Package, Up: Top + +Binary Package +************** + + The `binary' target of the source package `debian.rules' file should +do the following (see the sample `debian.rules' for an implementation +that you are free to modify and use in your own packages, of course): + + * Create an empty directory in the top-level directory of the source + package (deleting it first, if necessary), and install the files + belonging to this package in that directory. For example, the + directory could be called `debian-tmp' and would probably contain + directories `debian-tmp/usr/bin', `debian-tmp/usr/lib', etc. + (`debian-tmp' is the name traditionally used, and it is used in + the sample `debian.rules' file, so we will use that name in the + Guidelines.) + + * Make sure that all the files under `debian-tmp' have the correct + ownerships and permissions (*note Package Content::., for more + information about file locations, ownerships, and permissions.) + + * Create a subdirectory of `debian-tmp' called `DEBIAN'. This + directory contains the package control information, including at + the very least the master information file named `control'. The + next section describes the semantics and syntax of the files + required and allowed here. + + * Run `dpkg' to create the binary package, using something like + + dpkg --build debian-tmp + + This will create a file called `debian-tmp.deb', from the + `debian-tmp' directory. You should rename this file to + `../<package>-<version>.deb' after it is built. + + After the `binary' target has done all this, the + `<package>-<version>.deb' file in the parent directory is the + binary distribution. This file may be distributed and installed on + any Debian GNU/Linux system with `dpkg' in the same manner and + using the same methods as all packages are installed to the system. + + * If a single source package corresponds to several binary packages, + there should usually be a `debian.rules' file with a single + `binary' target that builds all the binary packages involved and + move all packages to the parent directory of that containing the + source package. + + In this case, you should choose binary package names which are + meant to make clear the close relationship between the binary + packages and which source package the binary packages came from + (for example, the `texinfo' source package build two binary + packages: `texidoc' and `texinfo'). You should place the + appropriate binary package name in the `Package' field of the + control file (not the source package name), and you should + consider whether the other binary packages that come from the same + source tree should be mentioned in the `Depends', `Recommends' or + `Suggests' fields. You should put the source package name in the + `Source' field. + + You should retain the source package version numbering in the + `Version' field, if possible--the version number should be the + same for the Debianised source tree and all the binary packages + generated from it. It is more important, though, that the version + numbers sort correctly. See below for details of version numbers. + + +File: guidelines.info, Node: Control Files, Next: Appendix, Prev: Binary Package, Up: Top + +Control Files +************* + + Each binary package contains, in addition to the files that comprise +the actual package, a set of text files that control how `dpkg' +installs, configures, upgrades, removes, etc. the package. These files +are called "control files". When creating the package, the control +files should placed in a directory called `DEBIAN', as described +earlier (*note Binary Package::., for further information). + + The control information files are: + +`control' + The master package control information file. + +`conffiles' + A list of package configuration files. + +`preinst' + The package pre-installation script. + +`postinst' + The package post-installation script. + +`prerm' + The package pre-removal script. + +`postrm' + The package post-removal script. + + Of these, only `control' is required. The various installation +scripts, and the configuration files list, will only be used if they are +present. + +* Menu: + +* control:: +* conffiles:: +* Installation and Removal Scripts:: +* Dependencies and Conflicts:: +* Package Classification Fields:: + + +File: guidelines.info, Node: control, Next: conffiles, Prev: Control Files, Up: Control Files + +control +======= + + The `control' file contains a number of fields. Each field begins +with a field name, such as `Package' or `Version' (case insensitive), +followed by a colon and optionally some spaces or tabs (a single space +is conventional). Then comes the body of the field, which may be +several lines long; each continuation line must start with at least one +space or tab. (These are the same rules as apply to RFC822 mail +headers.) Blank lines are not permitted in the control file. + + The required fields in the control file are the following: + +`Package' + The name of the package. + +`Description' + The description of the package. How to write an extended and more + usefull description field can be found in *note How to write the + Description control file field::.. + +`Maintainer' + The name and e-mail address of the maintainer of the package. + +`Version' + The version number in the format + `<original_version>-<debian_revision>'. + + Each field has a particular format and meaning for the package +installation tools. + + The value of `Package' should be the name of the package. Package +names must start with an alphanumeric, must be at least two characters, +and may contain only alphanumerics and the characters - + . @ : = % _ +(that is, hyphen, plus, stop, at, colon, equals, percent and +underscore). They are not case sensitive. + + The `Maintainer' field should be in the form + + Joe J. Bloggs <jbloggs@foo.com> + +Note that this will not be useable as an email address if the name +given contains full stop characters, because of a silly restriction in +the Internet mail standards. If you want to use this as an email +address in a program you should check for full stops and change the +string to the form `jbloggs@foo.com (Joe J. Bloggs)' if you find any. + + The `Version' field should be the version number of the package. +For most packages which are not written specifically for Debian, this +should be in the form + + Version: <original_version>-<debian_revision> + +where `<original_version>' is the original package version number in +whatever form the original package uses and `<debian_revision>' +indicates which "debianisation" this is (this should usually be a plain +number or perhaps a two numbers separated by a full stop, and should be +incremented each time the package is changed or updated). + + Packages which are written specifically for Debian do not have a +debian_revision, and their version number should simply be version +(which should not contain any hyphens, to avoid confusion). + + There is an ordering imposed on version numbers, described in +`version-ordering.txt'. This ordering is designed to `do the right +thing' in most circumstances; if your package has an version number in +an unusual format you may need to reformat it somewhat to get the +ordering right. This is important because `dpkg' is (for example) +reluctant to downgrade packages. + + The optional fields in the control file are the following: + +`Depends' + The names of prerequisite packages. + +`Recommends' + The names of related, recommended packages. + +`Suggests' + The names of related, optional packages. + +`Conflicts' + The names of packages which conflict with this package. + +`Provides' + The names of virtual packages which this package provides. + +`Priority' + The `priority' of the package, as shown and used by `dselect'. + +`Section' + The `section' of the package, as shown and used by `dselect', and + used as a location for the package in the distribution. + +`Essential' + A boolean field used by the base packages. + +`Pre-Depends' + Used by base packages to ensure that (for example) shared + libraries are present befoore they are upgraded. + +`Source' + Gives the name of the source package when several binary packages + are generated from a single source tree. + +See below for details of the semantics and syntax of these fields. +Most packages will need at least a `Depends' field. + + An example of a `control' file would be: + + 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. + + In this case, `mail-user-agent' is a virtual package representing +any user mailer program; the actual package names `pine' is quoted for +the reasons described in `dependency-ordering.txt', and the others +because older versions of those packages do not have the appropriate +`Provides' field. + + +File: guidelines.info, Node: conffiles, Next: Installation and Removal Scripts, Prev: control, Up: Control Files + +conffiles +========= + + The contents of `conffiles' is simply a list of configuration files +in the package. When installing the package, `dpkg' uses an +intelligent method to update these files. This will ensure that +package-specific configuration files are not overwritten when a package +is upgraded, unless the user wishes the installation tools to do so. + + Typically, files listed in conffiles are package-specific +configuration files, which (according to the Linux Filesystem Standard) +are stored in `/etc'. For example, the `sendmail' package may contain +the file `/etc/sendmail.cf', which we do not wish to overwrite +automatically when the user upgrades the sendmail package. Only those +files listed in `DEBIAN/conffiles' will be updated intelligently when a +package is upgraded; all other files in the package will be overwritten +by the upgrade process. + + Configuration files which will be functional as shipped and will +probably need little or no local editing should simply be listed the +`conffiles' file; in this case you need read no further. + + For packages whose configuration files will need modification on +most systems there are two sensible approaches. Which one is chosen +depends on how hard the configuration problem is and how much time the +package maintainer has available. + + One option is for you to ship a minimal `best-effort' file in +`/etc', and list the file in `conffiles'. This will mean that the user +will have to go and edit the file themselves to get the package to work +properly, of course. The next time they upgrade the package, if you +haven't changed the file version, their old file will be left in place. +If you have modified your version then the user will get a prompt +asking them which version of the file they want, theirs or yours. They +will then usually have to resolve the discrepancies manually. + + The other option is to be preferred, if you can do it: do not put a +copy of the configuration file in the package at all. Instead, you +check in the postinst whether the file exists, and if it doesn't you +prompt the user for the information you need to create a good one. This +is obviously harder work. + + You also have to remember that you will have to keep up with your +package's changes: 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. + + 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 +`/usr/sbin', by convention called package`config', and then run that if +appropriate from the post-installation script. The 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 `--force' flag to overwrite it. + + `conffiles' should almost certainly list all the files contained in +your package in the `/etc' directory. There may also be other files +somewhere that the user is expected to edit, which should also be +included. Note, however, that the FSSTND specifies that configuration +files must be in `/etc'. No Debian package should contain +configuration files in `/usr/etc', and all programs should refer to +configuration files in `/etc'. + +For example, the TCP/IP package might use a conffiles which contains + + /etc/init.d/netbase + /etc/gateways + /etc/protocols + /etc/services + /etc/hosts.allow + /etc/hosts.deny + /etc/rpc + +and so on; the files + + /etc/hosts + /etc/inetd.conf + /etc/host.conf + /etc/networks + /etc/resolv.conf + +might be generated by an interactive configuration program, and would +then not be included in the package or listed in the `conffiles'. + + +File: guidelines.info, Node: Installation and Removal Scripts, Next: Dependencies and Conflicts, Prev: conffiles, Up: Control Files + +Installation and Removal Scripts +================================ + + The scripts `preinst', `postinst', `prerm', and `postrm' are +optional (Bash or Perl) scripts. As the names would indicate, if these +scripts exist, they will be executed before installing the package, +after installation, before package removal, and after removal, +respectively. + + They are given arguments which indicate the precise situation and +action being performed--see `maintainer-script-args.txt' for details of +exactly when each of the scripts is invoked and what its arguments are. +Extra arguments and situations may be added later, so you should not +test the number of arguments to your script to determine the situation, +and you should choose the sense of your `if it is this then do this +otherwise do that' tests carefully. + + These scripts can be used to perform any site-specific package +configuration. + + Because the scripts will be exectued by the dpkg front-end, it is +guaranteed that the scripts will be executed interactively. User input +from the scripts should be read from standard input, not the user's +terminal. Similarly, output should be sent to standard output. + + If your maintainer scripts need to prompt for passwords and/or do +full-screen interaction should do these things to and from `/dev/tty', +since `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 `$|=1' so that the output is printed immediately rather than +being buffered. + + The scripts must be idempotent, and they must clean up after +themselves properly. Ie, they must do the right thing if run multiple +times, even if previous runs failed halfway through. This is so that if +any errors occur, or if the `dpkg' run is interrupted, the user can +recover by rerunning `dpkg', and/or by upgrading to a new version and +then rerunning the failed operation. + + These scripts should avoid producing output which it is unnecessary +for the user to see and should rely on `dpkg' to stave off boredom on +the part of a user installing many packages. This means, amongst other +things, using the `--quiet' option on `install-info'. + + Packages should try to minimise the amount of prompting they need to +do, and they should ensure that the user will only every be asked each +question once. This means that packages should try to use appropriate +shared configuration files (such as `/etc/papersize' and +`/etc/news/server'), rather than each prompting for their own list of +required pieces of information. + + It also means that an upgrade should not ask the same questions +again, unless the user has used `dpkg --purge' to remove the package's +configuration. The answers to configuration questions should be stored +in an appropriate place in `/etc' so that the user can modify them, and +how this has been done should be documented. + + 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 `postinst' +script and prompt the user to hit Return to acknowledge the message. +Copyright messages do not count as vitally important (they belong in +`/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). + + They should return a zero exit status for success, or a nonzero one +for failure. Note that if a script is a `#!/bin/sh' script it should +probably start with `set -e', to avoid continuing after errors--see +`bash'(1) for details. Perl scripts should check for errors when +making calls such as `open', `print', `close', `rename' and `system'. + + If these scripts exist they should be left in the `DEBIAN' directory +with execute permission enabled and should contain an appropriate `#!' +line, such as `#!/bin/bash' for a `bash' script or `#!/bin/perl' for a +Perl script (see above). + + +File: guidelines.info, Node: Dependencies and Conflicts, Next: Package Classification Fields, Prev: Installation and Removal Scripts, Up: Control Files + +Conflicts, Depends, Suggests, Recommends and Provides +===================================================== + + The `Depends' field lists packages that are required for this +package to provide a significant amount of functionality. The package +maintenance software will not allow a package to be installed without +also installing packages listed in its `Depends' field, and will run +the `postinst' scripts of packages listed in `Depends' fields before +those of the packages which depend on them, and run the `prerm' scripts +before. + + Packages containing dynamically-linked executable binaries (this +includes almost all C programs) should include a `Depends' field which +mentions the shared C library required for the program to run. For +a.out binaries linked against `libc.so.4' the relevant package name is +`libc' (for the a.out stable 0.93 tree) or `libc4' (for the unstable +development 1.1 tree); for ELF binaries linked against `libc.so.5' the +relevant package name is `libc5'. + + The `Recommends' field lists packages that would be found together +with this one in all but unusual installations. The user-level package +maintenance program `dselect' will warn the user if they select a +package without those listed in its `Recommends' field. Note that +`Recommends' fields do not currently have any implications for the +order in which the maintainer scripts are run. + + The `Suggests' field lists packages that are related to this one and +can perhaps enhance its usefulness, but without which installing this +package is perfectly reasonable. The package maintenance software will +not moan at the user for not selecting `Suggests' related packages, but +may use the information in the `Suggests' field to assist the user +during package selection. + + The syntax of `Depends', `Recommends' and `Suggests' is a list of +groups of alternative packages. Each group is a list of packages +separated by vertical bar (or `pipe') symbols, `|'. The groups are +separated by commas. Each package is a package name optionally +followed by a version number specification in parentheses. A version +number may start with a `>=', in which case that version or any later +will match, or `<=' for that version or any earlier version. A version +number starting with a `>>' or `<<' will respectively match any later +or earlier version. If a version number or a version number starting +with `=' is specified an exact match is required. Commas are to be read +as `AND', and pipes as `OR', with pipes binding more tightly. + + Versions of dpkg before 1.0.9 used `<' and `>' for `<=' and `>=' +(these are still supported for backward compatibility), and did not +support `<<' and `>>'. + + The `Conflicts' field lists packages that conflict with this one, +for example by containing files with the same names (an example would +be Smail vs. Sendmail). The package maintenance software will not +allow conflicting packages to be installed. Two conflicting packages +should each include a `Conflicts' line mentioning the other. + + The syntax of `Conflicts' is a list of package names (with optional +version numbers), separated by commas (and optional whitespace). In +the `Conflicts' field the comma should be read as `OR'. + + The `Provides' field lists the names of any `virtual packages' of +which this packages is to be considered an instantiation. Virtual +packages are used to allow packages to refer to a service they require +(such as the availability of `/usr/sbin/sendmail') without having to +know the names of all the relevant packages. The virtual package names +defined in `Provides' fields may be used in other packages' `Depends', +`Recommends', `Suggests' and `Conflicts' fields. For more information +about how to use virtual packages and which virtual package names to +use read *note Virtual dependencies::. and +`doc/package-developer/virtual-package-names-list.text'. + + The syntax of `Provides' is a list of package names separated by +commas (and optional whitespace). + + +File: guidelines.info, Node: Package Classification Fields, Prev: Dependencies and Conflicts, Up: Control Files + +Priority, Section and Essential +=============================== + + The `Priority' and `Section' fields are used by `dselect' when +displaying the list of packages to the user. There is no need to put +them into a package, since these are usually set by the distribution +maintainers in the `Packages' file. + + However, if a user installs a package which is not part of the +standard distribution, or without downloading and updating from a new +`Packages' file, the information about the priority and section of a +package will be absent, and the `dselect' package listing will have the +package listed under `unclassified'. It is permissible for a package +to include `Section' or `Priority' fields to improve this; however, if +you do this you should make sure you keep the information up to date so +that users are not shown conflicting information. The `Section' field +can also be used by the distribution maintainers as a suggestion about +which section you think is most appropriate for your package. + + The values for the `Section' and `Priority' fields should be +determined by the distribution maintainers; if you don't know what to +put in them just leave them out. You can add them later, if you like, +but remember that you'll then have to reissue your package if the +distribution maintainers change the classification of your package. + + The `Essential' field should only appear in packages in the +installation's base system. If it is set to `yes' then `dpkg' will not +remove the package even if asked to, and will make certain minor +modifications to its installation procedures. The only other legal +value is `no', which is equivalent to the absence of the field. + + + + +File: guidelines.info, Node: Appendix, Prev: Control Files, Up: Top + +Appendix +******** + +* Menu: + +* configuration files - /etc/skel vs /usr/doc/examples:: +* How to write the Description control file field:: +* Configuration of init:: +* Maintainer script arguments and how `dpkg' does things:: +* Mail processing packages:: +* Virtual dependencies:: + diff --git a/doc/guidelines.info-2 b/doc/guidelines.info-2 new file mode 100644 index 000000000..8018f09fc --- /dev/null +++ b/doc/guidelines.info-2 @@ -0,0 +1,744 @@ +This is Info file guidelines.info, produced by Makeinfo-1.63 from the +input file ./guidelines.texi. + +START-INFO-DIR-ENTRY +* Guidelines: (guidelines). How to make Debian packages. +END-INFO-DIR-ENTRY + + +File: guidelines.info, Node: configuration files - /etc/skel vs /usr/doc/examples, Next: How to write the Description control file field, Prev: Appendix, Up: Appendix + +configuration files - /etc/skel vs /usr/doc/examples +==================================================== + + There seems to be a certain amount of confusion about `/etc/skel' +and `/usr/doc/examples'. The most important thing to remember is the +following: + + Files in `/etc/skel' will *automatically* be copied into *new* user +accounts by `adduser'. They should not be referenced there by any +program. Files in `/usr/doc/examples' should not be installed +automatically. + + Therefore, if the program in question need a dotfile to exist in +advance in `$HOME' to work *sensibly* that dotfile should be installed +in `/etc/skel' (and listed in conffiles; *note conffiles::.). + + 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 that programs should be configured by the Debian +default installation as close to normal as possible. + + 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 `/etc' (and that +file should be listed in conffiles). Only if the program doesn't +support a site-wide default configuration should a default per-user file +be placed in `/etc/skel' (and listed in conffiles; *note conffiles::.). + + The idea is as follows: + + The sysadmin should ideally not have to do any configuration other +than that done (semi-)automatically by the postinst script. + + However, if they wish to change their configuration themselves +(because the configuration they want is beyond the scope of the +autoconfiguration, or because the autoconfiguration doesn't exist yet, +or because they just want to do it themselves for any reason) then +`/usr/doc/examples' exists as *documentation* for their benefit. + + The only time these files should be read are by the sysadmin using +their favourite editor or pager, or *perhaps* (in very complex packages) +by the postinst as a template to build on or modify. + + `/etc/skel' is part of the *implementation* of this configuration. +It contains the files that are copied into new user accounts. It +should probably be as empty as we can make it. + + Examples: +`.profile' + `/etc/skel' should not contain a `.profile' file. Anything that + needs to be done there should be done in `/etc/profile'. Anything + that should not go in `/etc/profile' (users can't avoid running + `/etc/profile') probably should not be in the default + configuration. bash has generally good default behaviour. + +`.bash_logout' + Likewise, bash functions perfectly happily without a + `.bash_logout', so none should be provided, since anything in it is + a deviation from the sensible default behaviour. + +`.xsession' + `/etc/skel' should not contain a `.xsession'. `xdm''s system-wide + startup file `/usr/lib/X11/xdm/Xsession' supports a system-wide + default user configuration (which should probably be + `/etc/X11/Xsession' or some such) which may be overridden by + `.xsession' in the user's home directory. Therefore there is no + need for a `.xsession' to be installed by default and none should + be provided. + + Instead, a sensible `/etc/X11/Xsession' should be provided, and if + desired this can be used as a template by users who wish to install + their own configuration, or alternatively a more comprehensive + example with much commented-out interesting stuff could be put in + `/usr/doc/examples'. + + If the sysadmin wishes to change the system-wide default they + should probably do this by editing `/etc/X11/Xsession' rather than + creating the file in `/etc/skel', because the former will affect + all user accounts that haven't explicitly overridden things by + creating their own file while the latter will only affect new + accounts. + + All the configuration necessary for a program to function should be + provided. Therefore sysadmins will not need to go through + `/usr/doc/examples' while editing configuration files in `/etc' + except in extreme cases (like INN) where the configuration was too + difficult to do automatically. + +`site-wide defaults' + Site-wide defaults should not go in `/etc/skel'. In the case of + twm, for example, the system-wide default should be in + `/etc/X11/system.twmrc'. (The default location for this in X11R5, + btw, is in `/usr/lib/X11' somewhere, but we can't put it on `/usr' + because of CDROM distributions, etc - hence the FSSTND's mandate + to put configuration files in `/etc'.) + +`.twmrc' + There should be no `.twmrc' file in `/etc/skel'. You can have one + in `/usr/doc/examples' if you *like*, but why bother if + `system.twmrc' is a good example (and indeed is the one the user is + using before they create their own)? + +`m4' + `/usr/doc/examples' isn't mainly for example *configuration + files*. It's for any kind of example file distributed with a + package. For example, GNU m4 comes with a whole pile of example + m4 macro scripts, which is exactly what `/usr/doc/examples' is for. + + Summary + + Files that should be installed in new user accounts should be in +`/etc/skel', as that will ensure that they *are* installed in new user +accounts! However, we should try to avoid the need for this. + + `/usr/doc/examples' is just what it says: documentation in the form +of examples. If a sysadmin is required to go and read these files for +their system to work they should be told about it. For example, here +is what the Smail postinst script says right at the start: + + I can do certain kinds of automatic configuration of your + mail system, by asking you a number of questions. Later you + may to confirm and/or correct your answers. In any case, + comprehensive information on configuring Smail is in + smail(5) and in /usr/doc/examples/smail and + /usr/doc/smail-admin-guide. + + +File: guidelines.info, Node: How to write the Description control file field, Next: Configuration of init, Prev: configuration files - /etc/skel vs /usr/doc/examples, Up: Appendix + +How to write the Description control file field +=============================================== + + The format of the `Description' field is as follows: + + Description: <single line synopsis> + <extended description over several lines> + + The extended description has several kinds of line: + + * 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. + + * 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). + + * Those containing a single space followed by a single full stop + character. These are rendered as blank lines. This is the *only* + way to get a blank line - see below. + + * Those containing a space, a full stop and some more characters. + These are for future expansion. *Do not* use them. + + IMPORTANT and not so important TIPS: + + * *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 in RFC822. Forgetting the whitespace will cause + `dpkg-deb' (>=0.93.23) to produce a syntax error when trying to + build the package. If you force it to build anyway `dpkg' will + refuse to install the resulting mess. + + * *Do not* include any completely *empty* lines. These separate + different records in the Packages file, and are forbidden in + control files. See the previous paragraph for what happens if you + get this wrong. + + * The single line synopsis should be kept brief - certainly under 80 + characters. `dselect' displays the *first 49* characters if + you're using an 80-column terminal. + + * 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. + + * 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). + + * 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. + + * You may include information about dependencies and so forth in the + extended description, if you wish. + + * Do not use tab characters. Their effect is not predictable. + + Example control file for Smail: + + 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. + + +File: guidelines.info, Node: Configuration of init, Next: Maintainer script arguments and how `dpkg' does things, Prev: How to write the Description control file field, Up: Appendix + +Configuration of init +===================== + + The `/etc/init.d' directory contains the scripts executed by init(8) +when init state (or "runlevel") is changed. This includes the boot +process, when the multi-user state begins. Several of these scripts +are included with init and are intended to be executed *once*, usually +at boot time. An example is `/etc/init.d/boot', which is executed at +boot time to check and mount file systems, activate swap, load kernel +modules, etc.-everything that needs to be done before the multi-user +state begins. `/etc/init.d' also contains the scripts that are +executed when entering runlevel 0 (halt), runlevel 1 (single-user) and +runlevel 6 (reboot). + + Packages can (and should) place scripts in `/etc/init.d' to start or +stop services at boot time or during a change of runlevel. These +scripts should be named `/etc/init.d/'<package>, and they should accept +one of two arguments: "start", which starts the services, or "stop", +which stops the services. These scripts should ensure that they will +behave sensibly if invoked with "start" when the service is already +running, or with "stop2 when it isn't--the best way to achieve this is +often to use `start-stop-daemon'. + + This script should not fail obscurely when the configuration files +remain but the package has been removed, as the default in dpkg is to +leave configuration files on the system after the package has been +removed. Only when it is executed with the `-purge' option will dpkg +remove configuration files. Therefore, you should include a `test' +statement at the top of the script, like this: + + test -f <program-executed-later-in-script> || exit 0 + + These scripts should be referenced, when appropriate, by symbolic +links in the `/etc/rc?.d' directories, as below. + + When changing runlevels, init looks in the directory `/etc/rc<n>.d' +for the scripts it should execute, where <n> is the runlevel that is +being changed to. Please note that the "scripts" in `/etc/rc?.d' are +not actually scripts; they are symbolic links, referencing actual +scripts in `/etc/init.d'. For simplicity, we refer to them as +"scripts". + + First, the scripts prefixed with a "K" are executed, followed by the +scripts prefixed with an "S". The "K" scripts are responsible for +killing certain services and the "S" scripts for starting certain +services upon *entering* the runlevel. For example, if we are changing +from runlevel 2 to runlevel 3, init will first execute all of the "K" +prefixed scripts it finds in `/etc/rc3.d' (to kill services), and then +all of the "S" prefixed scripts it finds in `/etc/rc3.d' (to start +services). The "K" scripts will execute the file it references with an +argument of "stop", and the "S" scripts will execute this file with an +argument of "start". + + After the "K" or "S" prefix, there should be a number specified, and +this number should be between 00 and 99. The number determines the +order in which the scripts are run. For example, the "K20" scripts will +be executed before the "K30" scripts. You can use this number to make +sure that a certain service is started before another. For example, on +some machines, the program `setserial' may need to properly set an IRQ +before the `ppp' program uses a modem to connect to a network. In this +case, the script that runs `setserial' should have a lower number than +the script that starts `ppp' so that it runs first: + + `/etc/rc2.d/S10setserial' + `/etc/rc2.d/S20ppp' + + If it does not matter when or in which order the script is run, use +the number "20". If it does, then you should talk to the maintainer of +the `sysvinit' package or post to `debian-devel', and they will help +you choose a number. + + In Debian GNU/Linux, we try to ship our software in as much of a +"default" state as possible. Therefore, unless there is a good reason +for doing differently, we ask that you start and stop the services in +each of the multi-user state runlevels (2, 3, 4, and 5). If a service +needs to be stopped before a file system can be unmounted (an example is +process accounting or quota services), then be sure to 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 +`/etc/rc?.d'. This is why we default to running everything in the +multi-user state-a reasonable default-and the administrator can easily +customize init to be as complex and sophisticated as he or she wants it +to be beyond this. + + We provide a script, `update-rc.d', to make it easier for package +maintainers to arrange for the proper creation and removal of +`/etc/rc?.d' symbolic links from their postinst and postrm scripts. +You should use this script to make changes to `/etc/rc?.d' and *never* +include any `/etc/rc.?.d' symbolic links in the actual archive. + + * In the postinst script, you need only do the following to setup + `/etc/rc?.d'. You should redirect standard output to `/dev/null', + as `update-rc.d' produces insignificant output: + + update-rc.d <package> default >/dev/null + + where <package> is the name of the file as it appears in + `/etc/init.d'. It will use the default number of "20", as + mentioned above. If you need to use a different number, you can + specify it after "default": + + update-rc.d <package> default 30 >/dev/null + + * In the postrm script, you need only do the following *if and only + if* it is called with the `purge' argument: + + if [ purge = "$1" ] + then + update-rc.d <package> remove >/dev/null + fi + +Important Note: +--------------- + + *Do not* include the `/etc/rc?.d/*' symbolic links in the archive! +*This will cause problems!* You should create them with update-rc.d, +as above. + + *Do not* include the `/etc/rc?.d/*' symbolic links in conffiles! +*This will cause problems!* *Do*, however, include the `/etc/init.d' +scripts in conffiles. + +Example: +-------- + + The process accounting package wants to make sure that process +accounting is started at boot time and that it is stopped before the +system is halted, enters the single-user state, or is rebooted (so that +the `/var' file system can be properly unmounted). It puts a script +that does this in `/etc/init.d', naming the script appropriately +"acct". This script accepts one of two arguments: either "start", +which starts process accounting, or "stop", which stops it. To ensure +that it does not fail obscurely when the configuration files remain but +the package has been removed, we include a `test' statement at the top +of the script: + + #! /bin/sh + # + # Start process accounting. + . /etc/init.d/functions + test -f /usr/sbin/accton || exit 0 + case "$1" in + start) + echo "Starting process accounting" + /usr/sbin/accton /var/account/pacct + ;; + stop) + echo "Stopping process accounting" + /usr/sbin/accton + ;; + *) + echo "Usage: /etc/init.d/acct {start|stop}" + exit 1 + esac + exit 0 + + You may find a skeletal script from which to base your `/etc/init.d' +scripts in `/etc/init.d/skeleton'. + + We want to stop then (re)start process accounting when entering a +multi-user state-runlevels 2, 3, 4, and 5-and we want to stop it when +leaving such a state-runlevels 0 (halt), 1 (single) and 6 (reboot). +These are good defaults, and we accomplish this by including the +following in the postinst: + + update-rc.d acct default >/dev/null + + When the user removes the acct packages with the `-purge' option, we +want to make sure the `/etc/rc?.d' symbolic links are properly removed, +so we include the following in the postrm: + + update-rc.d acct remove >/dev/null + + Otherwise, the `/etc/rc?.d' symbolic links will remain on the system +along with `/etc/init.d/acct' script. + + +File: guidelines.info, Node: Maintainer script arguments and how `dpkg' does things, Next: Mail processing packages, Prev: Configuration of init, Up: Appendix + +Maintainer script arguments and how `dpkg' does things +====================================================== + + This appendix describes exactly how maintainer scripts are called, +with what arguments, in what order, and what `dpkg' does in between. + + In all cases version numbers are <version>-<revision>, if the package +has both, or just <version>. `upgrade' is used even when the new +version number looks lower than the old. + +Summary +------- + + <new preinst> install + <new preinst> install <old-version> + <new preinst> upgrade <old-version> + <old preinst> abort-upgrade <new-version> + + <postinst> configure + <old postinst> abort-upgrade <new version> + <conflictor's postinst> abort-remove in-favour <package> <new version> + <deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> + + <prerm> remove + <old prerm> upgrade <new version> + <new prerm> failed-upgrade <old-vppersion> + <conflictor's prerm> remove in-favour <package> <new version> + <deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> + + <postrm> remove + <postrm> purge + <old postrm> upgrade <new-version> + <new postrm> failed-upgrade <old-version> + <new postrm> abort-install + <new postrm> abort-install <old-version> + <new postrm> abort-upgrade <old-version> + <disappearer's postrm> disappear <overwriter> <new version> + +Details of unpack phase of installation or upgrade +-------------------------------------------------- + + The procedure on installation/upgrade/overwrite/disappear (ie, when +running `dpkg --unpack', or the unpack stage of `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. + + 1. + a. If a version the package is already installed, call + <old prerm> upgrade <new version> + + b. If this gives an error (ie, a non-zero exit status), dpkg will + attempt instead: + <new prerm> failed-upgrade <old-version> + error unwind, for both the above cases: + <old postinst> abort-upgrade <new version> + + 2. If a `conflicting' package is being removed at the same time: + a. If any packages depended on that conflicting package and + `--auto-deconfigure' is specified, call, for each such + package: + <deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> + error unwind: + <deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> + The deconfigured packages are marked as requiring + configuration, so that if -install is used they will be + configured again if possible. + + b. To prepare for removal of the conflicting package, call: + <conflictor's prerm> remove in-favour <package> <new version> + error unwind: + <conflictor's postinst> abort-remove in-favour <package> <new version> + + 3. + a. If the package is being upgraded, call + <new preinst> upgrade <old-version> + + b. otherwise, if the package had some configuration files from a + previous version installed (ie, it is in the conffiles-only + state): + <new preinst> install <old-version> + + c. otherwise (ie, the package was completely purged): + <new preinst> install + error unwind versions, respectively: + <new postrm> abort-upgrade <old-version> + <new postrm> abort-install <old-version> + <new postrm> abort-install + + 4. The new package's files are unpacked, overwriting any that may be + on the system already, for example any from the old 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). + + 5. + a. If the package is being upgraded, call + <old postrm> upgrade <new-version> + + b. If this fails, dpkg will attempt: + <new postrm> failed-upgrade <old-version> + error unwind, for both cases: + <old preinst> abort-upgrade <new-version> + This is the point of no return - if 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 dpkg starts + doing things that are irreversible. + + 6. Any files which were in the old version of the package but not in + the new are removed. + + 7. The new file list replaces the old. + + 8. The new maintainer scripts replace the old. + + 9. 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, + a. dpkg calls: + <disappearer's postrm> disappear <overwriter> <new version> + + b. The package's maintainer scripts are removed. + + c. It is noted in the status database as being in a sane state, + namely not installed (any conffiles it may have are ignored). + Note that disappearing packages do not have their prerm + called, because dpkg doesn't know in advance that the package + is going to vanish. + + 10. 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.) + + 11. The backup files made at 4. are deleted. + + 12. 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. + + 13. If there was a conflicting package we go and do the removal + actions, starting from point 2. of the removal, below. + +Details of configuration +------------------------ + + When we configure a package (this happens with `dpkg --install', or +with `--configure'), we first update the conffiles and then call: + <postinst> configure <most-recently-configured-version> + + No attempt is made to unwind after errors during configuration. + +Details of removal and/or configration purging +---------------------------------------------- + + 1. <prerm> remove + + 2. The package's files are removed (except conffiles). + + 3. <postrm> remove + + 4. All the maintainer scripts except the postrm are removed. + + 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 dpkg status. + + 5. The conffiles and any backup files (`~'-files, `#*#' files, + `%'-files, .dpkg-{old,new,tmp}, etc.) are removed. + + 6. <postrm> purge + + 7. The package's file list is removed. + No attempt is made to unwind after errors during removal. + + +File: guidelines.info, Node: Mail processing packages, Next: Virtual dependencies, Prev: Maintainer script arguments and how `dpkg' does things, Up: Appendix + +Mail processing packages +======================== + + Debian packages which process electronic mail (whether +mail-user-agents (MUA) or alternative mail-transport-agents (MTA)) +*must* make sure that they are compatible with the configuration +decisions below. Failure to do this may result in lost mail, broken +`From:' lines, and other serious brain damage! + + * The mail spool is `/var/spool/mail' and the interface to send a + mail message is `/usr/sbin/sendmail' (as per the FSSTND). The mail + spool is part of the base and not part of the MTA package. + + * Mailboxes are locked using the `.lock' lockfile convention, rather + than fcntl, flock or lockf. + + * Mailboxes are generally 660 `<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 writeable by group mail. + + * The mail spool is 2775 mail.mail, and MUA's need to be setgid mail + to do the locking mentioned above (and obviously need to avoid + accessing other users' mailboxes using this privilege). + + * `/etc/aliases' is the source file for the system mail aliases (e.g. + postmaster, usenet, etc.) - it is the one which the sysadmin and + postinst scripts may edit. + + * The convention of writing `forward to <address>' in the mailbox + itself is not supported. Use a `.forward' file instead. + + * The location for the `rmail' program used by UUCP for incoming mail + is `/usr/sbin/rmail', as per the FSSTND. Likewise, `rsmtp', for + receiving batch-SMTP-over-UUCP, is in `/usr/sbin/rsmtp' if it is + supported. + + * Smail is not using HoneyDanBer UUCP, whose uux apparently accepts + -a and -g options. + + * 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 `/etc/mailname'. It will contain the portion after the + username and `@' sign for email addresses of users on the machine + (followed by a newline). + + A package should check for the existence of this file. If it exists +it should use it without comment (1). If it does not exist it should +prompt the user for the value and store it in `/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. E.g., in +the same situation the INN package says: + + 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 `$syshostname', your system's host name. + Mail name [`$syshostname']: + ($syshostname is the output of `hostname -fqdn'). + + ---------- Footnotes ---------- + + (1) An MTA's prompting configuration script may wish to prompt the +user even if it finds this file exists. + + +File: guidelines.info, Node: Virtual dependencies, Prev: Mail processing packages, Up: Appendix + +Virtual dependencies +==================== + + Virtual packages are in the same namespace as real packages, and may +have the same name. The meaning of a virtual package in a +dependency/conflicts list is exactly that of listing all the real +packages which state that they are an instantiation of that virtual +package. + + This is done with a new Provides field in the control file, with a +syntax much like the Conflicts field. + + The idea is that we can have something like: + Package: elm + Depends: mta + + Package: smail + Provides: mta + Conflicts: mta + + Package: sendmail + Provides: mta + Conflicts: mta + The result is equivalent to elm having said + Package: elm + Depends: smail | sendmail + + (There'll be a special case to say that a package may conflict with a +virtual package which it provides - clearly ...) + + 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 + Package: lout + Optional: ghostview + (this is a fictional example - the Lout package should not mention +ghostview), and someone else comes up with a nice PostScript previewer, +then they can just say + Package: marvelpostview + Provides: ghostview + and all will work in the interim (until, say, the Lout maintainer +changes things). + + 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 prohibited, for a conflict) - it is assumed that a real +package which provides virtual package is not of the `right' version. +If there is demand it can be arranged that a package which provides a +virtual package may mention a version number, though this is unlikely to +be helpful: + Provides: mta (2.0) + + 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 can +simply list the real package as alternative before the virtual one: + Package: xbaseR6 + Recommended: xsvga | x-server + Provides: x-base, xr6shlib + + Package: xsvga + Recommended: x-base + Provides: x-server + + Package: x8514 + Recommended: x-base + Provides: x-server + + Virtual package names should generally not be used in the names of +`/etc/init.d' scripts, configuration files, logfiles, and so on, so +that several programs providing the same virtual package name can be +installed. + + diff --git a/doc/guidelines.texi b/doc/guidelines.texi new file mode 100644 index 000000000..78662e4d4 --- /dev/null +++ b/doc/guidelines.texi @@ -0,0 +1,1936 @@ +\input texinfo @c -*-texinfo-*- +@setfilename guidelines.info + +@set DATE 26th January 1996 + +@setchapternewpage off + +@iftex +@center @titlefont{Debian GNU/Linux Packaging Guidelines} +@tex +\vskip2pt \hrule height 2pt width \hsize \vskip2pt +@end tex +@sp 0.5 +@center @value{DATE} +@end iftex + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Guidelines: (guidelines). How to make Debian packages. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@node Top, Additional Information, (dir), (dir) + +@ifinfo +@top Debian GNU/Linux Packaging Guidelines +@end ifinfo + + This file documents the steps that must be taken in the preparation +of a Debian GNU/Linux package. All submissions to be included in the +distribution proper and all packages to be considered for @file{contrib} +or @file{non-free} availability @emph{must} conform to the guidelines +and standards described in this document or they cannot be included or +made available at the archive with the distribution. + + Please read the Guidelines carefully. If you have comments or +questions, please contact @code{debian-devel@@pixar.com}. If you are +planning on going further than just contributing a package (i.e., if +you plan to maintain it for an extended period of time or if you are +generally interested in becoming more involved in the Project), you +should join the @code{debian-devel} mailing list. For more details, +read @file{info/mailing-lists.txt}, available at any Debian GNU/Linux +archive. + + (This file was last updated on @value{DATE}. Please check the most +recent @file{dpkg} package at any Debian GNU/Linux archive for a +potentially more up to date copy.) + +@menu +* Additional Information:: Where other info is to be found. +* Package Copyright:: A few words about the importance of + understanding the package copyright. +* Package Content:: Requirements for the package content. +* Source Package:: Creating the source package. +* Binary Package:: Creating the binary package. +* Control Files:: The binary package control files. +* Appendix:: More specific details about some aspects. +@end menu + + + +@node Additional Information, Package Copyright, Top, Top +@unnumbered Additional Information + + These Guidelines are intended to be fairly general. More specific +information is available about certain aspects of building packages, +such as how to use the features of Init under Debian GNU/Linux and how +to interact with some more technical details of dpkg's operation. This +information can be found in the directory @file{doc/package-developer} +at any Debian GNU/Linux archive. At the time of this writing, the +following documents are available: + +@table @file +@item virtual-package-names-list.text +The list of virtual package names currently in use, together with the +procedure for getting new virtual package names allocated. +@item auto-deconfiguration.txt +How dpkg can sometimes automatically deconfigure packages in order to +do bulk installations smoothly. +@item dpkg-essential-flag.txt +How to tell dpkg a package is essential and should not be removed. +(This is for the use of base system packages only.) +@item dpkg-disappear-replace.txt +What happens when a package appears to have been completely replaced. +@end table + + In the future, we hope also to make available: + +@table @file +@item copyright.txt +How to choose a good copyright notice to attach to new programs. +@item version-ordering.txt +The algorithm with which packages' version numbers are compared. +@end table + + Also, you should download the sample files and the sample package +(GNU Hello) available in @file{standards/samples}. You may use any +of this material as a starting point for new packages. The following +sample files, incidentally, are available: + +@itemize @bullet +@item debian.README +@item debian.control +@item debian.postinst +@item debian.postrm +@item debian.rules +@end itemize + +Some more detailed information about certain topics is available in the +appendix to this document (@pxref{Appendix}). + + +@node Package Copyright, Package Content, Additional Information, Top +@unnumbered Package Copyright + + Please study the copyright of your submission @emph{carefully} +and @emph{understand it} before proceeding! If you have doubts or +questions, please ask! + + In order to understand how we classify and distribute certain +packages, it is important to understand the distinction between being +freely available and being freely redistributable. + + Being @dfn{freely available}, quite simply, means that the software +can be made available freely, at least for non-commercial purposes and +in its original, unmodified form. This includes packages made available +freely that have restrictions on non-commercial use, redistribution of +modifications, etc. Being freely available, therefore, has nothing to +do with being able to modify and redistribute the software. It only +means that you can get a copy of the software without having to pay +(and it does not necessarily mean that you can @emph{use} the software +without having to pay---shareware is an example of freely available +software). + + @dfn{freely redistributable}, while generally being freely available, +goes beyond just being freely available. Freely redistributable means +that that the software, in addition to being able to be made available +freely, must be able to be freely modified and redistributed without +restriction. + + All submissions to be included in the distribution proper @emph{must} +be freely redistributable. + + In addition to the distribution, the Project maintains two separate +archives of software packages with the distribution: the @file{contrib} +archive and the @file{non-free} archive. + + @file{contrib} is an archive of user-contributed packages that are +not maintained by the Project, packages that were once maintained by the +Project but that are no longer actively maintained, and packages that +are maintained by the Project but that are not yet considered ready for +inclusion in the distribution proper (i.e., ALPHA and BETA packages). +As above, all submissions for inclusion in the @file{contrib} archive +@emph{must} be freely redistributable. + + @file{non-free} is an archive of packages with either restrictive or +unclear terms of copying or modification. If a package has @emph{any} +restrictions on modification or redistribution, it can not be included +in the distribution or @file{contrib} archive. It can only be included +in the @file{non-free} archive, and then only if it is freely available. + + In summary, in order to be included in the distribution proper or the +@file{contrib} archive, a package must be @emph{freely redistributable}. +Anyone must be able to make copies of it, modify it, redistribute it with +their modifications in place, include it on a CD-ROM, or generally sell +it. To be included in the @file{non-free} archive, a package may have +restrictions, as long as the package remains @emph{freely available}. We +must be available to make it available freely at the archive, and anyone +must be able to make copies of it and use it for at least non-commercial, +personal purposes. Software that will typically be included in +@file{non-free} are software that does not allow commercial distribution, +software that does not allow modification or redistribution of +modifications, commercial ``demos'', and ``shareware''. + + When in doubt, send mail to @file{iwj10@@cus.cam.ac.uk} and +@file{imurdock@@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''. + + Every package submission @emph{must} be accompanied by verbatim copy +of its copyright (with the exceptions of public domain packages and +those covered by the UCB BSD licence or the GNU GPL or LGPL; in these +cases simply indicate which is appropriate). This information must be +included in a file installed to the directory @file{/usr/doc/copyright}. +See below for details. + + + +@node Package Content, Source Package, Package Copyright, Top +@unnumbered Package Content + + The following requirements apply equally to both the binary and +source packages. In either case, when files have been installed, +they must conform to the requirements described in this section. + + The primary rule in Debian GNU/Linux is to follow the Linux @dfn{File +System Standard} (@dfn{FSSTND}). The location of installed files +@emph{must} comply @emph{fully} with the FSSTND. The latest version of +this document can be found alongside the Guidelines or at +@file{tsx-11.mit.edu} in @file{/pub/linux/docs/linux-standards/fsstnd}. +Specific questions about following the standard should be addressed to +Daniel Quinlan, the FSSTND coordinator, at @code{quinlan@@yggdrasil.com}. + + In addition to the FSSTND, all Debian GNU/Linux packages must follow +the guidelines below. + +@itemize @bullet +@item +Directories should be mode 755 or (for group-writability) mode 2775, +with the exception of special ``system'' directories that need to be +another mode. 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, of course. Use common sense in assigning +permissions and ownerships to directories, and make sure that what is +done is secure if it is ``non-standard''. + +@item +Normal binaries should be mode 755 and owned by @code{root.root}. If +there is a good reason to use a different mode or ownership, you may do +so, but you must try to be as consistent as possible with the rest of +the system. If you need to use a different mode or ownership, please +discuss it with @code{imurdock@@debian.org}. + +@item +Setuid binaries should normally be mode 4755 (not 4711!) and, of course, +owned by the appropriate user. + +@item +Setgid binaries should normally be mode 2755 (not 2711!) and, of course, +owned by the appropriate group. + +@item +Library files should generally be mode 644 and owned by +@code{root.root}. If the package requires different permissions +or ownerships to function correctly, they should be used instead. + +@item +Manual pages should be mode 644 and owned by @code{root.root}. The +@file{nroff} source must be installed. You should @emph{not} install a +preformatted ``cat page'', and you should only use sections 1 to 9---see +the FSSTND for more details. 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 +@file{undocumented}(7) manual page should be provided. This symbolic +link can be created from @file{debian.rules} like this: + +@smallexample +ln -s ../man7/undocumented.7 debian-tmp/usr/man/man[1-9]/the_requested_manpage.[1-9] +@end smallexample + +Do not close the bug report until a proper manpage is available. You +may forward the complaint to the upstream maintainers, and mark the bug +as forwarded in the Debian bug tracking system. The GNU Project do not +in general consider the lack of a manpage to be a bug, but we do - if +they tell you to go away leave the bug open anyway. + +@item +Info documents should be mode 644, owned by @code{root.root}, and +compressed with @file{gzip -9} when installed. The package must call +@file{install-info} to update the Info @file{dir} file. This should +be done in the post-installation script (@file{postinst}), like this: + +@smallexample +install-info --quiet /usr/info/foobar.info +@end smallexample + +The entries should be removed by the pre-removal script (@file{prerm}), +like this: + +@smallexample +install-info --quiet --remove /usr/info/foobar.info +@end smallexample + +It is also a good idea to specify a section for the Info @file{dir} +entry. This is done with the @file{--section} switch. To determine +which section to use, you should use look at @file{/usr/info/dir} on +your system and choose the most relevant (or create a new section if +none of the current sections are relevant). + +If @file{install-info} cannot find a description entry in the Info file +you will have to supply one. See @file{install-info}(8) for details. + +@item +If a package contains any shared libraries you will have to invoke +@file{ldconfig} in both the @file{postinst} and @file{prerm} scripts +to correctly update the library links. See @file{ldconfig}(8) for +details. + +@item +Any additional documentation that comes with the package can be +installed at the discretion of the package maintainer. Text +documentation should be mode 644, owned by @code{root.root}, installed +to @file{/usr/doc}, and compressed with @file{gzip -9} unless it is small. + +If a subdirectory of @file{/usr/doc} is warranted, please do create one. +Please do not install DVI, PostScript, or large textual documentation in +the same package; upload such documentation as a separate package +(installing its files in @file{/usr/doc}) so that it can be made +available with the distribution. If a user has the need for the +documentation, they can easily get it from the archive, CD-ROM, etc., +but it should not take up disk space on the machines of the user who do +not need or want it installed. + +@item +Create a file named @file{/usr/doc/copyright/<@i{package}>} which gives +details of the authorship and copyright of the package. If the package +is distributed under the GNU General Public Licence, the GNU Library +General Public Licence or the Regents of the University of California at +Berkeley (BSD) licence, please say so instead of including a copy of the +licence. The files @file{BSD}, @file{GPL}, and @file{LGPL} will be +available in the @file{/usr/doc/copyright} directory for you to refer +to. @file{/usr/doc/copyright/<@i{package}>} should not be compressed. + +@emph{All} authorship and copyright information from the original source +package must be included in the @file{/usr/doc/copyright/<@i{package}>} +file. + +@item +Any example files (for example, sample configuration files) should +be placed in the directory @file{/usr/doc/examples}. If the file is +normally a hidden file, such as @file{.emacs}, then please call it +@file{dot.emacs}, to avoid confusion. Again, you may create a +subdirectory if it is needed. + +@item +All symbolic links should be relative, not absolute. Absolute links, +in general, cause problems when a file system is not mounted where it +``normally'' resides (for example, when mounted via NFS). In certain +cases, however, relative links may also cause similar problems. I +have generally made links into @file{/etc} and @file{/var} absolute +and all other links relative. There may be other cases in which +absolute links are necessary. + +Therefore, in the @file{Makefile} or @file{debian.rules}, do not do: +@smallexample +install: all + [...] + ln -fs /usr/bin/gcc /usr/bin/cc + [...] +@end smallexample +Instead, do: +@smallexample +ln -fs gcc /usr/bin/cc +@end smallexample +or +@smallexample +( cd /usr/bin ; ln -fs gcc cc ) +@end smallexample + +Please do not create hard links in the manual page directories. In +these cases, you should use relative symbolic links or files that +@file{.so} (roff for `source') others instead. + +@item +All command scripts should have a @code{#!} line naming the shell to be +used to interpret them. + +@item +In the case of Perl scripts this should be @code{#!/usr/bin/perl} or +sometimes @code{#!/bin/perl}, as follows: if the script is a critical +one that may be called when the @file{/usr} partition is unmounted or +broken it should use @file{/bin/perl}. Otherwise (especially if the +script is not specifically targetted at Debian) it should use Perl's +standard location, @file{/usr/bin/perl}. + +@item +Generally the following compilation parameters should be used: + +@display + CC = gcc + CFLAGS = -O2 -g -Wall # sane warning options vary between programs + LDFLAGS = # none (or -N, if appropriate; see below) + install -s (or strip) +@end display + +Note that all installed binaries should be stripped, either by using the +@code{-s} flag to @file{install}, or by calling @file{strip} on the +binaries after they have been copied into the @file{debian-tmp} but +before the tree is made into a package. + +Make sure that you do not link with @code{-g}, as this makes a.out +compilers produce huge statically linked binaries. The @code{-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. + +@code{-N} should only be used on binaries that are very small (less than +8K with the @code{-N} option, roughly) and are not likely to have +multiple instances in memory. Do not use @code{-N} on daemons, no +matter how small they are. + +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 (@code{-O3}, for example); feel free to use them. Please use good +judgment here. Don't add flags for the sake of adding flags; only add +flags if there is good reason to do so. + +@item +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. + +@item +Logfiles should usually be named @file{/var/log/<package>}, or +@file{/var/log/<package>.<something>} if you have several logfiles. It +may be appropriate to create a directory. Make sure that any logfiles +are rotated occasionally so that they don't grow indefinitely; the best +way to do this is to use @file{savelog} from the cron package in an +@file{/etc/cron.daily}, @file{/etc/cron.weekly} or +@file{/etc/cron.monthly} script. + + +@item +Please check with the base system maintainer (Ian Murdock) before using +users or groups other than @code{root} and others specified in this +document. +@end itemize + + + +@node Source Package, Binary Package, Package Content, Top +@unnumbered Source Package + + The source package should contain a file called @file{debian.rules} +which contains at least the following targets, to be invoked in the top +level directory: + +@smallexample +build +binary +clean +@end smallexample + +@file{debian.rules} should start with + +@smallexample +#!/usr/bin/make -f +@end smallexample + +@noindent and be executable. It is a good idea to arrange for it not +to fail obscurely when invoked in the wrong directory, for example by +testing for the existence of a file in the source directory. + +@itemize @bullet +@item +The @file{build} target should perform all non-interactive configuration +and compilation of the package. If a package has an interactive +pre-build configuration routine, the source package should be built +@emph{after} this has taken place. + + For some packages, notably ones where the same source tree is +compiled in different ways to produce two binary packages, the +@file{build} target does not make much sense. For these packages it is +good enough to provide two (or more) targets (@file{build-a} and +@file{build-b} or whatever) for each of the ways of building the +package, and a @file{build} target that does nothing. The @file{binary} +target will have to build the package in each of the possible ways and +make the binary package out of each. + +@item +The @file{binary} target of @file{debian.rules} should be all that is +necessary for the user to build the binary package. The binary package +should be created using @file{dpkg} and placed in the parent of the top +level directory. The next section describes how to construct binary +packages from the @file{binary} target. + +@item +The @file{clean} target should undo the effects of the @file{build} +target and the @file{binary} target, except that it should leave alone +any @file{../<@i{package}>-<@i{version}>.deb} file created by a run of +@file{binary}. + +@item +Additional targets may exist in @file{debian.rules}. We recommend using +@file{source} and @file{diff} targets to build the Debianised source +package and the Debianisation context diff, respectively. These files +should be placed in @file{../foo-<@i{version}>.tar.gz} and +@file{../foo-<@i{version}>.diff.gz}. The @file{install} target, for +installing into a running system direct from the Debianised source +tree, is no longer required. The sample @file{debian.rules} provides +@file{source} and @file{diff} targets that should work with little or +no alteration, providing that the package-specific variables at the top +of the script have been properly defined. + +@item +If you need to edit a @file{Makefile} where @file{configure} scripts +are used, you should edit the @file{.in} files rather than editing +the @file{Makefile} directly. This allows the user to reconfigure +the package if necessary. You should @emph{not} configure the package +and edit the generated @file{Makefile}! This makes it impossible for +someone else to later reconfigure the package. + +@item +Please document your changes to the source package so that future +package maintainers know what has been changed. To do this, include +a description of your changes in the @file{debian.README} (which, as +described above, should already contain authorship and copyright +information!) and include relevant information such as your name, +electronic mail address, date, etc. The @file{debian.README} file +should also document any `unusual' packages which must be installed for +this one to compile. + +@item +If changes to the source code are made that are applicable to Linux +systems or systems in general 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. + +If changes to the source code are made, please use a @file{define}. If +they are changes required to compile or function under Linux in general, +use @file{LINUX}. If it is a cosmetic or functional change, use +@file{DEBIAN}. + +@item +Create the source package using @file{tar}, and use @file{gzip -9} to +compress it. Source packages should be named in the form +<@i{package}>-<@i{version}>.tar.gz---for example, +@file{fileutils-3.9-3.tar.gz}. + +NB, here @code{<@i{version}>} is the full Debian version number, in the +form @code{<@i{original_version}>-<@i{debian_revision}>} (see below), +but the tarfile should unpack into a directory named +@code{<@i{package}>-<@i{original_version}>} (again, see the section +below on version numbering). + +@item +Create the context diff against the original package using @file{diff +-cNr}, and use @file{gzip -9} to compress it. Context diffs should be +named in the form <@i{package}>-<@i{version}>.diff.gz---for example, +@file{fileutils-3.9-3.diff.gz}. +@end itemize + + Please note that the package and patch filenames do @emph{not} need +to fit in MS-DOS 8+3. They will be made available under an alternative +8+3 name in the archive by the archive maintainer, using a symlink. + + + +@node Binary Package, Control Files, Source Package, Top +@unnumbered Binary Package + + The @file{binary} target of the source package @file{debian.rules} +file should do the following (see the sample @file{debian.rules} +for an implementation that you are free to modify and use in your own +packages, of course): + +@itemize @bullet +@item +Create an empty directory in the top-level directory of the source +package (deleting it first, if necessary), and install the files +belonging to this package in that directory. For example, the directory +could be called @file{debian-tmp} and would probably contain directories +@file{debian-tmp/usr/bin}, @file{debian-tmp/usr/lib}, etc. +(@file{debian-tmp} is the name traditionally used, and it is used in +the sample @file{debian.rules} file, so we will use that name in the +Guidelines.) + +@item +Make sure that all the files under @file{debian-tmp} have the correct +ownerships and permissions (@pxref{Package Content}, for more information +about file locations, ownerships, and permissions.) + +@item +Create a subdirectory of @file{debian-tmp} called @file{DEBIAN}. This +directory contains the package control information, including at the +very least the master information file named @file{control}. The next +section describes the semantics and syntax of the files required and +allowed here. + +@item +Run @file{dpkg} to create the binary package, using something like + +@smallexample +dpkg --build debian-tmp +@end smallexample + +This will create a file called @file{debian-tmp.deb}, from the +@file{debian-tmp} directory. You should rename this file to +@file{../<@i{package}>-<@i{version}>.deb} after it is built. + +After the @file{binary} target has done all this, the +@file{<@i{package}>-<@i{version}>.deb} file in the parent directory is +the binary distribution. This file may be distributed and installed on +any Debian GNU/Linux system with @file{dpkg} in the same manner and +using the same methods as all packages are installed to the system. + +@item +If a single source package corresponds to several binary packages, there +should usually be a @file{debian.rules} file with a single @file{binary} +target that builds all the binary packages involved and move all packages +to the parent directory of that containing the source package. + +In this case, you should choose binary package names which are meant to +make clear the close relationship between the binary packages and which +source package the binary packages came from (for example, the +@file{texinfo} source package build two binary packages: @file{texidoc} +and @file{texinfo}). You should place the appropriate binary package +name in the @file{Package} field of the control file (not the source +package name), and you should consider whether the other binary packages +that come from the same source tree should be mentioned in the +@file{Depends}, @file{Recommends} or @file{Suggests} fields. You +should put the source package name in the @file{Source} field. + +You should retain the source package version numbering in the +@file{Version} field, if possible---the version number should be the +same for the Debianised source tree and all the binary packages +generated from it. It is more important, though, that the version +numbers sort correctly. See below for details of version numbers. +@end itemize + + + +@node Control Files, Appendix, Binary Package, Top +@unnumbered Control Files + + Each binary package contains, in addition to the files that comprise +the actual package, a set of text files that control how @file{dpkg} +installs, configures, upgrades, removes, etc. the package. These files +are called @dfn{control files}. When creating the package, the control +files should placed in a directory called @file{DEBIAN}, as described +earlier (@pxref{Binary Package}, for further information). + +The control information files are: + +@table @code +@item control +The master package control information file. +@item conffiles +A list of package configuration files. +@item preinst +The package pre-installation script. +@item postinst +The package post-installation script. +@item prerm +The package pre-removal script. +@item postrm +The package post-removal script. +@end table + + Of these, only @file{control} is required. The various installation +scripts, and the configuration files list, will only be used if they are +present. + +@menu +* control:: +* conffiles:: +* Installation and Removal Scripts:: +* Dependencies and Conflicts:: +* Package Classification Fields:: +@end menu + +@node control, conffiles, Control Files, Control Files +@unnumberedsec control + + The @file{control} file contains a number of fields. Each field +begins with a field name, such as @file{Package} or @file{Version} +(case insensitive), followed by a colon and optionally some spaces or +tabs (a single space is conventional). Then comes the body of the +field, which may be several lines long; each continuation line must +start with at least one space or tab. (These are the same rules as +apply to RFC822 mail headers.) Blank lines are not permitted in the +control file. + + The required fields in the control file are the following: + +@table @code +@item Package +The name of the package. +@item Description +The description of the package. How to write an extended and more +usefull description field can be found in @pxref{How to write the Description control file field}. +@item Maintainer +The name and e-mail address of the maintainer of the package. +@item Version +The version number in the format +@code{<@i{original_version}>-<@i{debian_revision}>}. +@end table + + Each field has a particular format and meaning for the package +installation tools. + +The value of @file{Package} should be the name of the package. +Package names must start with an alphanumeric, must be at least two +characters, and may contain only alphanumerics and the characters +- + . @@ : = % _ (that is, hyphen, plus, stop, at, colon, equals, +percent and underscore). They are not case sensitive. + + The @code{Maintainer} field should be in the form + +@smallexample +Joe J. Bloggs <jbloggs@@foo.com> +@end smallexample + +@noindent Note that this will not be useable as an email address if +the name given contains full stop characters, because of a silly +restriction in the Internet mail standards. If you want to use this +as an email address in a program you should check for full stops and +change the string to the form @code{jbloggs@@foo.com (Joe J. Bloggs)} +if you find any. + + The @code{Version} field should be the version number of the +package. For most packages which are not written specifically for +Debian, this should be in the form + +@smallexample +Version: <@i{original_version}>-<@i{debian_revision}> +@end smallexample + +@noindent where @file{<@i{original_version}>} is the original package +version number in whatever form the original package uses and +@file{<@i{debian_revision}>} indicates which ``debianisation'' this is +(this should usually be a plain number or perhaps a two numbers +separated by a full stop, and should be incremented each time the +package is changed or updated). + + Packages which are written specifically for Debian do not have a +@i{debian_revision}, and their version number should simply be +@i{version} (which should not contain any hyphens, to avoid +confusion). + + There is an ordering imposed on version numbers, described in +@file{version-ordering.txt}. This ordering is designed to `do the right +thing' in most circumstances; if your package has an version number in +an unusual format you may need to reformat it somewhat to get the +ordering right. This is important because @file{dpkg} is (for example) +reluctant to downgrade packages. + + The optional fields in the control file are the following: + +@table @code +@item Depends +The names of prerequisite packages. +@item Recommends +The names of related, recommended packages. +@item Suggests +The names of related, optional packages. +@item Conflicts +The names of packages which conflict with this package. +@item Provides +The names of virtual packages which this package provides. +@item Priority +The `priority' of the package, as shown and used by @file{dselect}. +@item Section +The `section' of the package, as shown and used by @file{dselect}, and +used as a location for the package in the distribution. +@item Essential +A boolean field used by the base packages. +@item Pre-Depends +Used by base packages to ensure that (for example) shared libraries are +present befoore they are upgraded. +@item Source +Gives the name of the source package when several binary packages are +generated from a single source tree. +@end table + +@noindent See below for details of the semantics and syntax of these +fields. Most packages will need at least a @code{Depends} field. + + An example of a @file{control} file would be: + +@smallexample +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. +@end smallexample + + In this case, @file{mail-user-agent} is a virtual package +representing any user mailer program; the actual package names +@file{pine} is quoted for the reasons described in +@file{dependency-ordering.txt}, and the others because older versions +of those packages do not have the appropriate @file{Provides} field. + +@node conffiles, Installation and Removal Scripts, control, Control Files +@unnumberedsec conffiles + + The contents of @file{conffiles} is simply a list of configuration +files in the package. When installing the package, @file{dpkg} uses +an intelligent method to update these files. This will ensure that +package-specific configuration files are not overwritten when a package +is upgraded, unless the user wishes the installation tools to do so. + + Typically, files listed in conffiles are package-specific +configuration files, which (according to the Linux Filesystem Standard) +are stored in @file{/etc}. For example, the @code{sendmail} package may +contain the file @file{/etc/sendmail.cf}, which we do not wish to +overwrite automatically when the user upgrades the sendmail package. +Only those files listed in @file{DEBIAN/conffiles} will be updated +intelligently when a package is upgraded; all other files in the package +will be overwritten by the upgrade process. + + Configuration files which will be functional as shipped and will +probably need little or no local editing should simply be listed the +@file{conffiles} file; in this case you need read no further. + + For packages whose configuration files will need modification on +most systems there are two sensible approaches. Which one is chosen +depends on how hard the configuration problem is and how much time the +package maintainer has available. + + One option is for you to ship a minimal `best-effort' file in +@file{/etc}, and list the file in @file{conffiles}. This will mean that +the user will have to go and edit the file themselves to get the package +to work properly, of course. The next time they upgrade the package, if +you haven't changed the file version, their old file will be left in +place. If you have modified your version then the user will get a +prompt asking them which version of the file they want, theirs or yours. +They will then usually have to resolve the discrepancies manually. + + The other option is to be preferred, if you can do it: do not put a +copy of the configuration file in the package at all. Instead, you +check in the postinst whether the file exists, and if it doesn't you +prompt the user for the information you need to create a good one. This +is obviously harder work. + + You also have to remember that you will have to keep up with your +package's changes: 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. + + If you do go down this route it's probably a good idea to make the +program that generates the configuration file(s) a separate program in +@file{/usr/sbin}, by convention called @i{package}@code{config}, and +then run that if appropriate from the post-installation script. The +@i{package}@code{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 @code{--force} flag to +overwrite it. + + @file{conffiles} should almost certainly list all the files contained +in your package in the @file{/etc} directory. There may also be other +files somewhere that the user is expected to edit, which should also be +included. Note, however, that the FSSTND specifies that configuration +files must be in @file{/etc}. No Debian package should contain +configuration files in @file{/usr/etc}, and all programs should refer to +configuration files in @file{/etc}. + +@noindent For example, the TCP/IP package might use a conffiles which contains + +@smallexample +/etc/init.d/netbase +/etc/gateways +/etc/protocols +/etc/services +/etc/hosts.allow +/etc/hosts.deny +/etc/rpc +@end smallexample + +@noindent and so on; the files + +@smallexample +/etc/hosts +/etc/inetd.conf +/etc/host.conf +/etc/networks +/etc/resolv.conf +@end smallexample + +@noindent might be generated by an interactive configuration program, +and would then not be included in the package or listed in the +@file{conffiles}. + +@node Installation and Removal Scripts, Dependencies and Conflicts, conffiles, Control Files +@unnumberedsec Installation and Removal Scripts + + The scripts @file{preinst}, @file{postinst}, @file{prerm}, and +@file{postrm} are optional (Bash or Perl) scripts. As the names +would indicate, if these scripts exist, they will be executed before +installing the package, after installation, before package removal, +and after removal, respectively. + + They are given arguments which indicate the precise situation and +action being performed---see @file{maintainer-script-args.txt} for +details of exactly when each of the scripts is invoked and what its +arguments are. Extra arguments and situations may be added later, so +you should not test the number of arguments to your script to determine +the situation, and you should choose the sense of your `if it is this +then do this otherwise do that' tests carefully. + + These scripts can be used to perform any site-specific package +configuration. + + Because the scripts will be exectued by the dpkg front-end, it is +guaranteed that the scripts will be executed interactively. User input +from the scripts should be read from standard input, not the user's +terminal. Similarly, output should be sent to standard output. + + If your maintainer scripts need to prompt for passwords and/or do +@i{full-screen} interaction should do these things to and from +@file{/dev/tty}, since @file{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 @code{$|=1} so that the output is printed +immediately rather than being buffered. + + The scripts must be idempotent, and they must clean up after +themselves properly. Ie, they must do the right thing if run multiple +times, even if previous runs failed halfway through. This is so that if +any errors occur, or if the @file{dpkg} run is interrupted, the user can +recover by rerunning @file{dpkg}, and/or by upgrading to a new version +and then rerunning the failed operation. + + These scripts should avoid producing output which it is unnecessary +for the user to see and should rely on @file{dpkg} to stave off boredom +on the part of a user installing many packages. This means, amongst +other things, using the @file{--quiet} option on @file{install-info}. + + Packages should try to minimise the amount of prompting they need to +do, and they should ensure that the user will only every be asked each +question once. This means that packages should try to use appropriate +shared configuration files (such as @file{/etc/papersize} and +@file{/etc/news/server}), rather than each prompting for their own list +of required pieces of information. + + It also means that an upgrade should not ask the same questions +again, unless the user has used @code{dpkg --purge} to remove the +package's configuration. The answers to configuration questions should +be stored in an appropriate place in @file{/etc} so that the user can +modify them, and how this has been done should be documented. + + 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 +@file{postinst} script and prompt the user to hit Return to acknowledge +the message. Copyright messages do not count as vitally important (they +belong in @file{/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). + + They should return a zero exit status for success, or a nonzero one +for failure. Note that if a script is a @code{#!/bin/sh} script it +should probably start with @code{set -e}, to avoid continuing after +errors---see @file{bash}(1) for details. Perl scripts should check for +errors when making calls such as @code{open}, @code{print}, +@code{close}, @code{rename} and @code{system}. + + If these scripts exist they should be left in the @file{DEBIAN} +directory with execute permission enabled and should contain an +appropriate @code{#!} line, such as @code{#!/bin/bash} for a +@code{bash} script or @code{#!/bin/perl} for a Perl script (see +above). + +@node Dependencies and Conflicts, Package Classification Fields, Installation and Removal Scripts, Control Files +@unnumberedsec Conflicts, Depends, Suggests, Recommends and Provides + + The @file{Depends} field lists packages that are required for this +package to provide a significant amount of functionality. The package +maintenance software will not allow a package to be installed without +also installing packages listed in its @code{Depends} field, and will +run the @code{postinst} scripts of packages listed in @code{Depends} +fields before those of the packages which depend on them, and run the +@code{prerm} scripts before. + + Packages containing dynamically-linked executable binaries (this +includes almost all C programs) should include a @file{Depends} field +which mentions the shared C library required for the program to run. +For a.out binaries linked against @file{libc.so.4} the relevant package +name is @file{libc} (for the a.out stable 0.93 tree) or @file{libc4} +(for the unstable development 1.1 tree); for ELF binaries linked against +@file{libc.so.5} the relevant package name is @file{libc5}. + + The @code{Recommends} field lists packages that would be found +together with this one in all but unusual installations. The user-level +package maintenance program @file{dselect} will warn the user if they +select a package without those listed in its @code{Recommends} field. +Note that @code{Recommends} fields do not currently have any implications +for the order in which the maintainer scripts are run. + + The @code{Suggests} field lists packages that are related to this one +and can perhaps enhance its usefulness, but without which installing +this package is perfectly reasonable. The package maintenance software +will not moan at the user for not selecting @code{Suggests} related +packages, but may use the information in the @code{Suggests} field to +assist the user during package selection. + + The syntax of @code{Depends}, @code{Recommends} and @code{Suggests} +is a list of groups of alternative packages. Each group is a list of +packages separated by vertical bar (or `pipe') symbols, @code{|}. The +groups are separated by commas. Each package is a package name +optionally followed by a version number specification in parentheses. A +version number may start with a @code{>=}, in which case that version or +any later will match, or @code{<=} for that version or any earlier +version. A version number starting with a @code{>>} or @code{<<} will +respectively match any later or earlier version. If a version number or +a version number starting with @code{=} is specified an exact match is +required. Commas are to be read as `AND', and pipes as `OR', with pipes +binding more tightly. + + Versions of dpkg before 1.0.9 used @code{<} and @code{>} for +@code{<=} and @code{>=} (these are still supported for backward +compatibility), and did not support @code{<<} and @code{>>}. + + The @code{Conflicts} field lists packages that conflict with this +one, for example by containing files with the same names (an example +would be Smail vs. Sendmail). The package maintenance software will not +allow conflicting packages to be installed. Two conflicting packages +should each include a @code{Conflicts} line mentioning the other. + + The syntax of @code{Conflicts} is a list of package names (with +optional version numbers), separated by commas (and optional +whitespace). In the @code{Conflicts} field the comma should be read as +`OR'. + + The @code{Provides} field lists the names of any `virtual packages' +of which this packages is to be considered an instantiation. Virtual +packages are used to allow packages to refer to a service they require +(such as the availability of @file{/usr/sbin/sendmail}) without having +to know the names of all the relevant packages. The virtual package +names defined in @code{Provides} fields may be used in other packages' +@code{Depends}, @code{Recommends}, @code{Suggests} and @code{Conflicts} +fields. For more information about how to use virtual packages and +which virtual package names to use read @pxref{Virtual dependencies} and +@file{doc/package-developer/virtual-package-names-list.text}. + + The syntax of @code{Provides} is a list of package names separated by +commas (and optional whitespace). + +@node Package Classification Fields, , Dependencies and Conflicts, Control Files +@unnumberedsec Priority, Section and Essential + + The @code{Priority} and @code{Section} fields are used by +@file{dselect} when displaying the list of packages to the user. There +is no need to put them into a package, since these are usually set by +the distribution maintainers in the @file{Packages} file. + + However, if a user installs a package which is not part of the +standard distribution, or without downloading and updating from a new +@file{Packages} file, the information about the priority and section of +a package will be absent, and the @file{dselect} package listing will +have the package listed under `unclassified'. It is permissible for a +package to include @code{Section} or @code{Priority} fields to improve +this; however, if you do this you should make sure you keep the +information up to date so that users are not shown conflicting +information. The @code{Section} field can also be used by the +distribution maintainers as a suggestion about which section you think +is most appropriate for your package. + + The values for the @code{Section} and @code{Priority} fields should be +determined by the distribution maintainers; if you don't know what to +put in them just leave them out. You can add them later, if you like, +but remember that you'll then have to reissue your package if the +distribution maintainers change the classification of your package. + + The @code{Essential} field should only appear in packages in the +installation's base system. If it is set to @code{yes} then @file{dpkg} +will not remove the package even if asked to, and will make certain +minor modifications to its installation procedures. The only other +legal value is @code{no}, which is equivalent to the absence of the +field. + +@appendix +@node Appendix, , Control Files, Top +@unnumbered Appendix +@comment node-name, next, previous, up +@menu +* configuration files -- /etc/skel vs /usr/doc/examples:: +* How to write the Description control file field:: +* Configuration of init:: +* Maintainer script arguments and how @file{dpkg} does things:: +* Mail processing packages:: +* Virtual dependencies:: +@end menu + +@node configuration files -- /etc/skel vs /usr/doc/examples, How to write the Description control file field, Appendix, Appendix +@comment node-name, next, previous, up +@unnumberedsec configuration files -- /etc/skel vs /usr/doc/examples + +There seems to be a certain amount of confusion about @file{/etc/skel} +and @file{/usr/doc/examples}. The most important thing to remember is +the following: + +Files in @file{/etc/skel} will @emph{automatically} be copied into +@emph{new} user accounts by @file{adduser}. They should not +be referenced there by any program. Files in @file{/usr/doc/examples} +should not be installed automatically. + +Therefore, if the program in question need a dotfile to exist in advance +in @file{$HOME} to work @emph{sensibly} that dotfile should be installed +in @file{/etc/skel} (and listed in conffiles; @pxref{conffiles}). + +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 that programs should be configured by the Debian +default installation as close to normal as possible. + +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 @file{/etc} (and +that file should be listed in conffiles). Only if the program doesn't +support a site-wide default configuration should a default per-user file +be placed in @file{/etc/skel} (and listed in conffiles; +@pxref{conffiles}). + +The idea is as follows: + +The sysadmin should ideally not have to do any configuration other than +that done @w{(semi-)}automatically by the postinst script. + +However, if they wish to change their configuration themselves +(because the configuration they want is beyond the scope of the +autoconfiguration, or because the autoconfiguration doesn't exist yet, +or because they just want to do it themselves for any reason) then +@file{/usr/doc/examples} exists as @emph{documentation} for their benefit. + +The only time these files should be read are by the sysadmin using their +favourite editor or pager, or @emph{perhaps} (in very complex packages) +by the postinst as a template to build on or modify. + +@file{/etc/skel} is part of the @emph{implementation} of this +configuration. It contains the files that are copied into new user +accounts. It should probably be as empty as we can make it. + +Examples: +@table @code +@item .profile +@file{/etc/skel} should not contain a @file{.profile} file. Anything +that needs to be done there should be done in @file{/etc/profile}. +Anything that should not go in @file{/etc/profile} (users can't avoid +running @file{/etc/profile}) probably should not be in the default +configuration. bash has generally good default behaviour. + +@item .bash_logout +Likewise, bash functions perfectly happily without a +@file{.bash_logout}, so none should be provided, since anything in it is +a deviation from the sensible default behaviour. + +@item .xsession +@file{/etc/skel} should not contain a @file{.xsession}. @file{xdm}'s +system-wide startup file @file{/usr/lib/X11/xdm/Xsession} supports a +system-wide default user configuration (which should probably be +@file{/etc/X11/Xsession} or some such) which may be overridden by +@file{.xsession} in the user's home directory. Therefore there is no +need for a @file{.xsession} to be installed by default and none should +be provided. + +Instead, a sensible @file{/etc/X11/Xsession} should be provided, and if +desired this can be used as a template by users who wish to install +their own configuration, or alternatively a more comprehensive example +with much commented-out interesting stuff could be put in +@file{/usr/doc/examples}. + +If the sysadmin wishes to change the system-wide default they should +probably do this by editing @file{/etc/X11/Xsession} rather than +creating the file in @file{/etc/skel}, because the former will affect +all user accounts that haven't explicitly overridden things by creating +their own file while the latter will only affect new accounts. + +All the configuration necessary for a program to function should be +provided. Therefore sysadmins will not need to go through +@file{/usr/doc/examples} while editing configuration files in +@file{/etc} except in extreme cases (like INN) where the configuration +was too difficult to do automatically. + +@item site-wide defaults +Site-wide defaults should not go in @file{/etc/skel}. In the case of +twm, for example, the system-wide default should be in +@file{/etc/X11/system.twmrc}. (The default location for this in X11R5, +btw, is in @file{/usr/lib/X11} somewhere, but we can't put it on +@file{/usr} because of CDROM distributions, etc - hence the FSSTND's +mandate to put configuration files in @file{/etc}.) + +@item .twmrc +There should be no @file{.twmrc} file in @file{/etc/skel}. You can have +one in @file{/usr/doc/examples} if you @emph{like}, but why bother if +@file{system.twmrc} is a good example (and indeed is the one the user is +using before they create their own)? + +@item m4 +@file{/usr/doc/examples} isn't mainly for example @emph{configuration +files}. It's for any kind of example file distributed with a package. +For example, GNU m4 comes with a whole pile of example m4 macro scripts, +which is exactly what @file{/usr/doc/examples} is for. +@end table + +Summary + +Files that should be installed in new user accounts should be in +@file{/etc/skel}, as that will ensure that they @emph{are} installed in +new user accounts! However, we should try to avoid the need for this. + +@file{/usr/doc/examples} is just what it says: documentation in the form +of examples. If a sysadmin is required to go and read these files for +their system to work they should be told about it. For example, here +is what the Smail postinst script says right at the start: + +@smallexample +I can do certain kinds of automatic configuration of your +mail system, by asking you a number of questions. Later you +may to confirm and/or correct your answers. In any case, +comprehensive information on configuring Smail is in +smail(5) and in /usr/doc/examples/smail and +/usr/doc/smail-admin-guide. +@end smallexample + +@node How to write the Description control file field, Configuration of init, configuration files -- /etc/skel vs /usr/doc/examples, Appendix +@unnumberedsec How to write the Description control file field + +The format of the @code{Description} field is as follows: + +@smallexample +Description: <single line synopsis> + <extended description over several lines> +@end smallexample + +The extended description has several kinds of line: + +@itemize @bullet +@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 @emph{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. @emph{Do not} use them. +@end itemize + +IMPORTANT and not so important TIPS: + +@itemize @bullet +@item +@emph{Always} start extended description lines with at least @emph{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 +in RFC822. Forgetting the whitespace will cause @file{dpkg-deb} +(>=0.93.23) to produce a syntax error when trying to build the package. +If you force it to build anyway @file{dpkg} will refuse to install the +resulting mess. + +@item +@emph{Do not} include any completely @emph{empty} lines. These separate +different records in the Packages file, and are forbidden in control +files. See the previous paragraph for what happens if you get this +wrong. + +@item +The single line synopsis should be kept brief - certainly under 80 +characters. @file{dselect} displays the @emph{first 49} characters if +you're using an 80-column terminal. + +@item +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. + +@item +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). + +@item +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. + +@item +You may include information about dependencies and so forth in the +extended description, if you wish. + +@item +Do not use tab characters. Their effect is not predictable. +@end itemize + +Example control file for Smail: + +@smallexample +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. +@end smallexample + +@node Configuration of init, Maintainer script arguments and how @file{dpkg} does things, How to write the Description control file field, Appendix +@unnumberedsec Configuration of init + +The @file{/etc/init.d} directory contains the scripts executed by +init(8) when init state (or "runlevel") is changed. This includes the +boot process, when the multi-user state begins. Several of these +scripts are included with init and are intended to be executed +@emph{once}, usually at boot time. An example is +@file{/etc/init.d/boot}, which is executed at boot time to check and +mount file systems, activate swap, load kernel modules, etc.--everything +that needs to be done before the multi-user state begins. +@file{/etc/init.d} also contains the scripts that are executed when +entering runlevel 0 (halt), runlevel 1 (single-user) and runlevel 6 +(reboot). + +Packages can (and should) place scripts in @file{/etc/init.d} to start +or stop services at boot time or during a change of runlevel. These +scripts should be named @file{/etc/init.d/}<package>, and they should +accept one of two arguments: "start", which starts the services, or +"stop", which stops the services. These scripts should ensure that they +will behave sensibly if invoked with "start" when the service is already +running, or with "stop2 when it isn't---the best way to achieve this is +often to use @file{start-stop-daemon}. + +This script should not fail obscurely when the configuration files +remain but the package has been removed, as the default in dpkg is to +leave configuration files on the system after the package has been +removed. Only when it is executed with the `--purge' option will dpkg +remove configuration files. Therefore, you should include a `test' +statement at the top of the script, like this: + +@smallexample +test -f <program-executed-later-in-script> || exit 0 +@end smallexample + +These scripts should be referenced, when appropriate, by symbolic links +in the @file{/etc/rc?.d} directories, as below. + +When changing runlevels, init looks in the directory @file{/etc/rc<n>.d} +for the scripts it should execute, where <n> is the runlevel that is +being changed to. Please note that the "scripts" in @file{/etc/rc?.d} +are not actually scripts; they are symbolic links, referencing actual +scripts in @file{/etc/init.d}. For simplicity, we refer to them as +"scripts". + +First, the scripts prefixed with a "K" are executed, followed by the +scripts prefixed with an "S". The "K" scripts are responsible for +killing certain services and the "S" scripts for starting certain +services upon @emph{entering} the runlevel. For example, if we are +changing from runlevel 2 to runlevel 3, init will first execute all of +the "K" prefixed scripts it finds in @file{/etc/rc3.d} (to kill +services), and then all of the "S" prefixed scripts it finds in +@file{/etc/rc3.d} (to start services). The "K" scripts will execute the +file it references with an argument of "stop", and the "S" scripts will +execute this file with an argument of "start". + +After the "K" or "S" prefix, there should be a number specified, and +this number should be between 00 and 99. The number determines the +order in which the scripts are run. For example, the "K20" scripts will +be executed before the "K30" scripts. You can use this number to make +sure that a certain service is started before another. For example, on +some machines, the program @file{setserial} may need to properly set an +IRQ before the @file{ppp} program uses a modem to connect to a network. +In this case, the script that runs @file{setserial} should have a lower +number than the script that starts @file{ppp} so that it runs first: + +@smallexample +@file{/etc/rc2.d/S10setserial} +@file{/etc/rc2.d/S20ppp} +@end smallexample + +If it does not matter when or in which order the script is run, use the +number "20". If it does, then you should talk to the maintainer of the +@code{sysvinit} package or post to @code{debian-devel}, and they will +help you choose a number. + +In Debian GNU/Linux, we try to ship our software in as much of a +"default" state as possible. Therefore, unless there is a good reason +for doing differently, we ask that you start and stop the services in +each of the multi-user state runlevels (2, 3, 4, and 5). If a service +needs to be stopped before a file system can be unmounted (an example is +process accounting or quota services), then be sure to 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 +@file{/etc/rc?.d}. This is why we default to running everything in the +multi-user state--a reasonable default--and the administrator can easily +customize init to be as complex and sophisticated as he or she wants it +to be beyond this. + +We provide a script, @file{update-rc.d}, to make it easier for package +maintainers to arrange for the proper creation and removal of +@file{/etc/rc?.d} symbolic links from their postinst and postrm scripts. +You should use this script to make changes to @file{/etc/rc?.d} and +@emph{never} include any @file{/etc/rc.?.d} symbolic links in the actual +archive. + +@itemize @bullet +@item +In the postinst script, you need only do the following to setup +@file{/etc/rc?.d}. You should redirect standard output to +@file{/dev/null}, as @file{update-rc.d} produces insignificant output: + +@smallexample +update-rc.d <package> default >/dev/null +@end smallexample + +where <package> is the name of the file as it appears in +@file{/etc/init.d}. It will use the default number of "20", as +mentioned above. If you need to use a different number, you can specify +it after "default": + +@smallexample +update-rc.d <package> default 30 >/dev/null +@end smallexample + +@item +In the postrm script, you need only do the following @emph{if and only +if} it is called with the `purge' argument: + +@smallexample +if [ purge = "$1" ] +then + update-rc.d <package> remove >/dev/null +fi +@end smallexample +@end itemize + +@unnumberedsubsec Important Note: + +@emph{Do not} include the @file{/etc/rc?.d/*} symbolic links in the +archive! @emph{This will cause problems!} You should create them with +update-rc.d, as above. + +@emph{Do not} include the @file{/etc/rc?.d/*} symbolic links in +conffiles! @emph{This will cause problems!} @emph{Do}, however, +include the @file{/etc/init.d} scripts in conffiles. + + +@unnumberedsubsec Example: + +The process accounting package wants to make sure that process +accounting is started at boot time and that it is stopped before the +system is halted, enters the single-user state, or is rebooted (so +that the @file{/var} file system can be properly unmounted). It puts +a script that does this in @file{/etc/init.d}, naming the script +appropriately "acct". This script accepts one of two arguments: +either "start", which starts process accounting, or "stop", which +stops it. To ensure that it does not fail obscurely when the +configuration files remain but the package has been removed, we +include a `test' statement at the top of the script: + +@smallexample +#! /bin/sh +# +# Start process accounting. +. /etc/init.d/functions +test -f /usr/sbin/accton || exit 0 +case "$1" in + start) + echo "Starting process accounting" + /usr/sbin/accton /var/account/pacct + ;; + stop) + echo "Stopping process accounting" + /usr/sbin/accton + ;; + *) + echo "Usage: /etc/init.d/acct @{start|stop@}" + exit 1 +esac +exit 0 +@end smallexample + +You may find a skeletal script from which to base your @file{/etc/init.d} +scripts in @file{/etc/init.d/skeleton}. + +We want to stop then (re)start process accounting when entering a +multi-user state--runlevels 2, 3, 4, and 5--and we want to stop it when +leaving such a state--runlevels 0 (halt), 1 (single) and 6 (reboot). +These are good defaults, and we accomplish this by including the +following in the postinst: + +@smallexample +update-rc.d acct default >/dev/null +@end smallexample + +When the user removes the acct packages with the `--purge' option, we +want to make sure the @file{/etc/rc?.d} symbolic links are properly +removed, so we include the following in the postrm: + +@smallexample +update-rc.d acct remove >/dev/null +@end smallexample + +Otherwise, the @file{/etc/rc?.d} symbolic links will remain on the system +along with @file{/etc/init.d/acct} script. + +@node Maintainer script arguments and how @file{dpkg} does things, Mail processing packages, Configuration of init, Appendix +@unnumberedsec Maintainer script arguments and how @file{dpkg} does things + +This appendix describes exactly how maintainer scripts are called, with +what arguments, in what order, and what @file{dpkg} does in between. + +In all cases version numbers are <version>-<revision>, if the package +has both, or just <version>. @code{upgrade} is used even when the new +version number looks lower than the old. + + +@unnumberedsubsec Summary + +@smallexample +<new preinst> install +<new preinst> install <old-version> +<new preinst> upgrade <old-version> +<old preinst> abort-upgrade <new-version> + +<postinst> configure +<old postinst> abort-upgrade <new version> +<conflictor's postinst> abort-remove in-favour <package> <new version> +<deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> + +<prerm> remove +<old prerm> upgrade <new version> +<new prerm> failed-upgrade <old-vppersion> +<conflictor's prerm> remove in-favour <package> <new version> +<deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> + +<postrm> remove +<postrm> purge +<old postrm> upgrade <new-version> +<new postrm> failed-upgrade <old-version> +<new postrm> abort-install +<new postrm> abort-install <old-version> +<new postrm> abort-upgrade <old-version> +<disappearer's postrm> disappear <overwriter> <new version> +@end smallexample + + +@unnumberedsubsec Details of unpack phase of installation or upgrade + +The procedure on installation/upgrade/overwrite/disappear (ie, when +running @code{dpkg --unpack}, or the unpack stage of @code{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. + +@enumerate +@item +@noindent @enumerate a +@item +If a version the package is already +installed, call +@smallexample +<old prerm> upgrade <new version> +@end smallexample +@item +If this gives an error (ie, a non-zero exit status), dpkg will +attempt instead: +@smallexample +<new prerm> failed-upgrade <old-version> +@end smallexample +@noindent error unwind, for both the above cases: +@smallexample +<old postinst> abort-upgrade <new version> +@end smallexample +@end enumerate +@item +If a `conflicting' package is being removed at the same time: +@noindent @enumerate a +@item +If any packages depended on that conflicting package and +@code{--auto-deconfigure} is specified, call, for each such package: +@smallexample +<deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> +@end smallexample +@noindent error unwind: +@smallexample +<deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> +@end smallexample +The deconfigured packages are marked as requiring configuration, so +that if --install is used they will be configured again if possible. +@item +To prepare for removal of the conflicting package, call: +@smallexample +<conflictor's prerm> remove in-favour <package> <new version> +@end smallexample +@noindent error unwind: +@smallexample +<conflictor's postinst> abort-remove in-favour <package> <new version> +@end smallexample +@end enumerate +@item +@noindent @enumerate a +@item +If the package is being upgraded, call +@smallexample +<new preinst> upgrade <old-version> +@end smallexample +@item +otherwise, if the package had some configuration files from a previous +version installed (ie, it is in the conffiles-only state): +@smallexample +<new preinst> install <old-version> +@end smallexample +@item +otherwise (ie, the package was completely purged): +@smallexample +<new preinst> install +@end smallexample +@noindent error unwind versions, respectively: +@smallexample +<new postrm> abort-upgrade <old-version> +<new postrm> abort-install <old-version> +<new postrm> abort-install +@end smallexample +@end enumerate +@item +The new package's files are unpacked, overwriting any that may be on the +system already, for example any from the old 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). +@item +@noindent @enumerate a +@item +If the package is being upgraded, call +@smallexample +<old postrm> upgrade <new-version> +@end smallexample +@item +If this fails, dpkg will attempt: +@smallexample +<new postrm> failed-upgrade <old-version> +@end smallexample +@noindent error unwind, for both cases: +@smallexample +<old preinst> abort-upgrade <new-version> +@end smallexample +@end enumerate +This is the point of no return - if 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 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, +@noindent @enumerate a +@item +dpkg calls: +@smallexample +<disappearer's postrm> disappear <overwriter> <new version> +@end smallexample +@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). Note that +disappearing packages do not have their prerm called, because dpkg +doesn't know in advance that the package is going to vanish. +@end enumerate +@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 at 4. 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, +starting from point 2. of the removal, below. +@end enumerate + + +@unnumberedsubsec Details of configuration + +When we configure a package (this happens with @code{dpkg --install}, or with +@code{--configure}), we first update the conffiles and then call: +@smallexample +<postinst> configure <most-recently-configured-version> +@end smallexample + +No attempt is made to unwind after errors during configuration. + + +@unnumberedsubsec Details of removal and/or configration purging + +@enumerate +@item +@smallexample +<prerm> remove +@end smallexample +@item +The package's files are removed (except conffiles). +@item +@smallexample +<postrm> remove +@end smallexample +@item +All the maintainer scripts except the postrm are removed. + +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 dpkg status. + +@item +The conffiles and any backup files (@samp{~}-files, @samp{#*#} files, +@samp{%}-files, .dpkg-@{old,new,tmp@}, etc.) are removed. +@item +@smallexample +<postrm> purge +@end smallexample +@item +The package's file list is removed. +@end enumerate +No attempt is made to unwind after errors during removal. + +@node Mail processing packages, Virtual dependencies, Maintainer script arguments and how @file{dpkg} does things, Appendix +@unnumberedsec Mail processing packages + +Debian packages which process electronic mail (whether mail-user-agents +(MUA) or alternative mail-transport-agents (MTA)) @emph{must} make sure +that they are compatible with the configuration decisions below. +Failure to do this may result in lost mail, broken @code{From:} lines, +and other serious brain damage! + +@itemize @bullet +@item +The mail spool is @file{/var/spool/mail} and the interface to send a +mail message is @file{/usr/sbin/sendmail} (as per the FSSTND). The mail +spool is part of the base and not part of the MTA package. + +@item +Mailboxes are locked using the @file{.lock} lockfile convention, rather +than fcntl, flock or lockf. + +@item +Mailboxes are generally 660 @file{<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 writeable by group mail. + +@item +The mail spool is 2775 mail.mail, and MUA's need to be setgid mail to do +the locking mentioned above (and obviously need to avoid accessing other +users' mailboxes using this privilege). + +@item +@file{/etc/aliases} is the source file for the system mail aliases (e.g. +postmaster, usenet, etc.) - it is the one which the sysadmin and +postinst scripts may edit. + +@item +The convention of writing `forward to <address>' in the mailbox itself +is not supported. Use a @file{.forward} file instead. + +@item +The location for the @file{rmail} program used by UUCP for incoming mail +is @file{/usr/sbin/rmail}, as per the FSSTND. Likewise, @file{rsmtp}, +for receiving batch-SMTP-over-UUCP, is in @file{/usr/sbin/rsmtp} if it +is supported. + +@item +Smail is not using HoneyDanBer UUCP, whose uux apparently accepts -a and +-g options. + +@item +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 +@file{/etc/mailname}. It will contain the portion after the username +and @samp{@@} sign for email addresses of users on the machine (followed +by a newline). +@end itemize + +A package should check for the existence of this file. If it exists it +should use it without comment @footnote{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 @file{/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. E.g., in the same situation the INN +package says: + +@smallexample +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 `$syshostname', your system's host name. +Mail name [`$syshostname']: +@end smallexample +($syshostname is the output of `hostname --fqdn'). + +@node Virtual dependencies, , Mail processing packages, Appendix +@comment node-name, next, previous, up +@unnumberedsec Virtual dependencies + +Virtual packages are in the same namespace as real packages, and may +have the same name. The meaning of a virtual package in a +dependency/conflicts list is exactly that of listing all the real +packages which state that they are an instantiation of that virtual +package. + +This is done with a new Provides field in the control file, with a +syntax much like the Conflicts field. + +The idea is that we can have something like: +@smallexample +Package: elm +Depends: mta + +Package: smail +Provides: mta +Conflicts: mta + +Package: sendmail +Provides: mta +Conflicts: mta +@end smallexample +@noindent The result is equivalent to elm having said +@smallexample +Package: elm +Depends: smail | sendmail +@end smallexample + +(There'll be a special case to say that a package may conflict with a +virtual package which it provides - clearly ...) + +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 +@smallexample +Package: lout +Optional: ghostview +@end smallexample +(this is a fictional example - the Lout package should not mention +ghostview), and someone else comes up with a nice PostScript +previewer, then they can just say +@smallexample +Package: marvelpostview +Provides: ghostview +@end smallexample +and all will work in the interim (until, say, the Lout maintainer +changes things). + +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 prohibited, for a conflict) - it is assumed that a real +package which provides virtual package is not of the `right' version. +If there is demand it can be arranged that a package which provides a +virtual package may mention a version number, though this is unlikely to +be helpful: +@smallexample +Provides: mta (2.0) +@end smallexample + +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 can +simply list the real package as alternative before the virtual one: +@smallexample +Package: xbaseR6 +Recommended: xsvga | x-server +Provides: x-base, xr6shlib + +Package: xsvga +Recommended: x-base +Provides: x-server + +Package: x8514 +Recommended: x-base +Provides: x-server +@end smallexample + +Virtual package names should generally not be used in the names of +@file{/etc/init.d} scripts, configuration files, logfiles, and so on, so +that several programs providing the same virtual package name can be +installed. + +@bye diff --git a/doc/guidelines.texi.beforeeric b/doc/guidelines.texi.beforeeric new file mode 100644 index 000000000..fb2f2953c --- /dev/null +++ b/doc/guidelines.texi.beforeeric @@ -0,0 +1,1056 @@ +\input texinfo @c -*-texinfo-*- +@setfilename guidelines.info + +@set DATE 26th January 1996 + +@setchapternewpage off + +@iftex +@center @titlefont{Debian GNU/Linux Packaging Guidelines} +@tex +\vskip2pt \hrule height 2pt width \hsize \vskip2pt +@end tex +@sp 0.5 +@center @value{DATE} +@end iftex + +@ifinfo +@format +START-INFO-DIR-ENTRY +* debian-guidelines: (debian-guidelines). How to make Debian packages. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@node Top, Additional Information, (dir), (dir) + +@ifinfo +@top Debian GNU/Linux Packaging Guidelines +@end ifinfo + + This file documents the steps that must be taken in the preparation +of a Debian GNU/Linux package. All submissions to be included in the +distribution proper and all packages to be considered for @file{contrib} +or @file{non-free} availability @emph{must} conform to the guidelines +and standards described in this document or they cannot be included or +made available at the archive with the distribution. + + Please read the Guidelines carefully. If you have comments or +questions, please contact @code{debian-devel@@pixar.com}. If you are +planning on going further than just contributing a package (i.e., if +you plan to maintain it for an extended period of time or if you are +generally interested in becoming more involved in the Project), you +should join the @code{debian-devel} mailing list. For more details, +read @file{info/mailing-lists.txt}, available at any Debian GNU/Linux +archive. + + (This file was last updated on @value{DATE}. Please check the most +recent @file{dpkg} package at any Debian GNU/Linux archive for a +potentially more up to date copy.) + +@menu +* Additional Information:: +* Package Copyright:: A few words about the importance of + understanding the package copyright. +* Package Content:: Requirements for the package content. +* Source Package:: Creating the source package. +* Binary Package:: Creating the binary package. +* Control Files:: The binary package control files. +@end menu + + + +@node Additional Information, Package Copyright, Top, Top +@unnumbered Additional Information + + These Guidelines are intended to be fairly general. More specific +information is available about certain aspects of building packages, +such as how to use the features of Init under Debian GNU/Linux. This +information can be found in the directory @file{project/standards} +at any Debian GNU/Linux archive. At the time of this writing, the +following documents are available: + +@table @file +@item README.etc-skel +A description of @file{/etc/skel} and @file{/usr/doc/examples}. +@item descriptions.txt +How to write an extended (and more useful) @file{DESCRIPTION} field. +@item README.init +How to use the features of Init under Debian GNU/Linux in packages. +@item mailers.txt +How to properly configure packages to use the Debian GNU/Linux mail +system. +@item maintainer-script-args.txt +All the ways that the package maintainer scripts inside a package can +be called by dpkg. +@item dpkg-upgrades+errors.txt +What order things happen in during a package upgrade. +@item virtual-dependencies.txt +How to use ``virtual dependencies'' in packages. +@item virtual-package-names-list.text +The list of virtual package names currently in use, together with the +procedure for getting new virtual package names allocated. +@item dependency-ordering.txt +How to properly order package names in the @file{DEPENDS} field. +@end table + + There are a number of documents that describe more technical +details of dpkg's operation, that will probably only be of minority +interest. Please read them if you're doing anything complicated. + +@table @file +@item auto-deconfiguration.txt +How dpkg can sometimes automatically deconfigure packages in order to +do bulk installations smoothly. +@item dpkg-essential-flag.txt +How to tell dpkg a package is essential and should not be removed. +(This is for the use of base system packages only.) +@item dpkg-disappear-replace.txt +What happens when a package appears to have been completely replaced. +@end table + + In the future, we hope also to make available: + +@table @file +@item copyright.txt +How to choose a good copyright notice to attach to new programs. +@item version-ordering.txt +The algorithm with which packages' version numbers are compared. +@end table + + Also, you should download the sample files and the sample package +(GNU Hello) available in @file{standards/samples}. You may use any +of this material as a starting point for new packages. The following +sample files, incidentally, are available: + +@itemize @bullet +@item debian.README +@item debian.control +@item debian.postinst +@item debian.postrm +@item debian.rules +@end itemize + + + +@node Package Copyright, Package Content, Additional Information, Top +@unnumbered Package Copyright + + Please study the copyright of your submission @emph{carefully} +and @emph{understand it} before proceeding! If you have doubts or +questions, please ask! + + In order to understand how we classify and distribute certain +packages, it is important to understand the distinction between being +freely available and being freely redistributable. + + Being @dfn{freely available}, quite simply, means that the software +can be made available freely, at least for non-commercial purposes and +in its original, unmodified form. This includes packages made available +freely that have restrictions on non-commercial use, redistribution of +modifications, etc. Being freely available, therefore, has nothing to +do with being able to modify and redistribute the software. It only +means that you can get a copy of the software without having to pay +(and it does not necessarily mean that you can @emph{use} the software +without having to pay---shareware is an example of freely available +software). + + @dfn{freely redistributable}, while generally being freely available, +goes beyond just being freely available. Freely redistributable means +that that the software, in addition to being able to be made available +freely, must be able to be freely modified and redistributed without +restriction. + + All submissions to be included in the distribution proper @emph{must} +be freely redistributable. + + In addition to the distribution, the Project maintains two separate +archives of software packages with the distribution: the @file{contrib} +archive and the @file{non-free} archive. + + @file{contrib} is an archive of user-contributed packages that are +not maintained by the Project, packages that were once maintained by the +Project but that are no longer actively maintained, and packages that +are maintained by the Project but that are not yet considered ready for +inclusion in the distribution proper (i.e., ALPHA and BETA packages). +As above, all submissions for inclusion in the @file{contrib} archive +@emph{must} be freely redistributable. + + @file{non-free} is an archive of packages with either restrictive or +unclear terms of copying or modification. If a package has @emph{any} +restrictions on modification or redistribution, it can not be included +in the distribution or @file{contrib} archive. It can only be included +in the @file{non-free} archive, and then only if it is freely available. + + In summary, in order to be included in the distribution proper or the +@file{contrib} archive, a package must be @emph{freely redistributable}. +Anyone must be able to make copies of it, modify it, redistribute it with +their modifications in place, include it on a CD-ROM, or generally sell +it. To be included in the @file{non-free} archive, a package may have +restrictions, as long as the package remains @emph{freely available}. We +must be available to make it available freely at the archive, and anyone +must be able to make copies of it and use it for at least non-commercial, +personal purposes. Software that will typically be included in +@file{non-free} are software that does not allow commercial distribution, +software that does not allow modification or redistribution of +modifications, commercial ``demos'', and ``shareware''. + + When in doubt, send mail to @file{iwj10@@cus.cam.ac.uk} and +@file{imurdock@@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''. + + Every package submission @emph{must} be accompanied by verbatim copy +of its copyright (with the exceptions of public domain packages and +those covered by the UCB BSD licence or the GNU GPL or LGPL; in these +cases simply indicate which is appropriate). This information must be +included in a file installed to the directory @file{/usr/doc/copyright}. +See below for details. + + + +@node Package Content, Source Package, Package Copyright, Top +@unnumbered Package Content + + The following requirements apply equally to both the binary and +source packages. In either case, when files have been installed, +they must conform to the requirements described in this section. + + The primary rule in Debian GNU/Linux is to follow the Linux @dfn{File +System Standard} (@dfn{FSSTND}). The location of installed files +@emph{must} comply @emph{fully} with the FSSTND. The latest version of +this document can be found alongside the Guidelines or at +@file{tsx-11.mit.edu} in @file{/pub/linux/docs/linux-standards/fsstnd}. +Specific questions about following the standard should be addressed to +Daniel Quinlan, the FSSTND coordinator, at @code{quinlan@@yggdrasil.com}. + + In addition to the FSSTND, all Debian GNU/Linux packages must follow +the guidelines below. + +@itemize @bullet +@item +Directories should be mode 755 or (for group-writability) mode 2775, +with the exception of special ``system'' directories that need to be +another mode. 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, of course. Use common sense in assigning +permissions and ownerships to directories, and make sure that what is +done is secure if it is ``non-standard''. + +@item +Normal binaries should be mode 755 and owned by @code{root.root}. If +there is a good reason to use a different mode or ownership, you may do +so, but you must try to be as consistent as possible with the rest of +the system. If you need to use a different mode or ownership, please +discuss it with @code{imurdock@@debian.org}. + +@item +Setuid binaries should normally be mode 4755 (not 4711!) and, of course, +owned by the appropriate user. + +@item +Setgid binaries should normally be mode 2755 (not 2711!) and, of course, +owned by the appropriate group. + +@item +Library files should generally be mode 644 and owned by +@code{root.root}. If the package requires different permissions +or ownerships to function correctly, they should be used instead. + +@item +Manual pages should be mode 644 and owned by @code{root.root}. The +@file{nroff} source must be installed. You should @emph{not} install +a preformatted ``cat page'', and you should only use sections 1 to +9---see the FSSTND for more details. + +@item +Info documents should be mode 644, owned by @code{root.root}, and +compressed with @file{gzip -9} when installed. The package must call +@file{install-info} to update the Info @file{dir} file. This should +be done in the post-installation script (@file{postinst}), like this: + +@smallexample + install-info --quiet /usr/info/foobar.info +@end smallexample + +The entries should be removed by the pre-removal script (@file{prerm}), +like this: + +@example + install-info --quiet --remove /usr/info/foobar.info +@end example + +It is also a good idea to specify a section for the Info @file{dir} +entry. This is done with the @file{--section} switch. To determine +which section to use, you should use look at @file{/usr/info/dir} on +your system and choose the most relevant (or create a new section if +none of the current sections are relevant). + +If @file{install-info} cannot find a description entry in the Info file +you will have to supply one. See @file{install-info}(8) for details. + +@item +If a package contains any shared libraries you will have to invoke +@file{ldconfig} in both the @file{postinst} and @file{prerm} scripts +to correctly update the library links. See @file{ldconfig}(8) for +details. + +@item +Any additional documentation that comes with the package can be +installed at the discretion of the package maintainer. Text +documentation should be mode 644, owned by @code{root.root}, installed +to @file{/usr/doc}, and compressed with @file{gzip -9} unless it is small. + +If a subdirectory of @file{/usr/doc} is warranted, please do create one. +Please do not install DVI, PostScript, or large textual documentation to +@file{/usr/doc}. However, please do upload such documentation as a +separate package so that it can be made available with the distribution. +If a user has the need for the documentation, they can easily get it +from the archive, CD-ROM, etc., but it should not take up disk space +on the machines of the user who do not need or want it installed. + +@item +Create a file named @file{/usr/doc/copyright/<@i{package}>} which gives +details of the authorship and copyright of the package. If the package +is distributed under the GNU General Public Licence, the GNU Library +General Public Licence or the Regents of the University of California at +Berkeley (BSD) licence, please say so instead of including a copy of the +licence. The files @file{BSD}, @file{GPL}, and @file{LGPL} will be +available in the @file{/usr/doc/copyright} directory for you to refer +to. @file{/usr/doc/copyright/<@i{package}>} should not be compressed. + +@emph{All} authorship and copyright information from the original source +package must be included in the @file{/usr/doc/copyright/<@i{package}>} +file. + +@item +Any example files (for example, sample configuration files) should +be placed in the directory @file{/usr/doc/examples}. If the file is +normally a hidden file, such as @file{.emacs}, then please call it +@file{dot.emacs}, to avoid confusion. Again, you may create a +subdirectory if it is needed. + +@item +All symbolic links should be relative, not absolute. Absolute links, +in general, cause problems when a file system is not mounted where it +``normally'' resides (for example, when mounted via NFS). In certain +cases, however, relative links may also cause similar problems. I +have generally made links into @file{/etc} and @file{/var} absolute +and all other links relative. There may be other cases in which +absolute links are necessary. + +Therefore, in the Makefile, do not do (even though it is easier): +@smallexample + install: all + [...] + ln -fs /usr/bin/gcc /usr/bin/cc + [...] +@end smallexample +Instead, do: +@smallexample + ln -fs gcc /usr/bin/cc +@end smallexample + or +@smallexample + ( cd /usr/bin ; ln -fs gcc cc ) +@end smallexample + +Please do not create hard links in the manual page directories. In +these cases, you should use relative symbolic links or files that +@file{.so} (roff for `source') others instead. + +@item +All command scripts should have a @code{#!} line naming the shell to be +used to interpret them. + +@item +In the case of Perl scripts this should be @code{#!/usr/bin/perl} or +sometimes @code{#!/bin/perl}, as follows: if the script is a critical +one that may be called when the @file{/usr} partition is unmounted or +broken it should use @file{/bin/perl}. Otherwise (especially if the +script is not specifically targetted at Debian) it should use Perl's +standard location, @file{/usr/bin/perl}. + +@item +Generally the following compilation parameters should be used: + +@display + CC = gcc + CFLAGS = -O2 -g -Wall # sane warning options vary between programs + LDFLAGS = # none (or -N, if appropriate; see below) + install -s (or strip) +@end display + +Note that all installed binaries should be stripped, either by using the +@code{-s} flag to @file{install}, or by calling @file{strip} on the +binaries after they have been copied into the @file{debian-tmp} but +before the tree is made into a package. + +Make sure that you do not link with @code{-g}, as this makes a.out +compilers produce huge statically linked binaries. The @code{-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. + +@code{-N} should only be used on binaries that are very small (less than +8K with the @code{-N} option, roughly) and are not likely to have +multiple instances in memory. Do not use @code{-N} on daemons, no +matter how small they are. + +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 (@code{-O3}, for example); feel free to use them. Please use good +judgment here. Don't add flags for the sake of adding flags; only add +flags if there is good reason to do so. + +@item +Please check with the base system maintainer (Ian Murdock) before using +users or groups other than @code{root} and others specified in this +document. +@end itemize + + + +@node Source Package, Binary Package, Package Content, Top +@unnumbered Source Package + + The source package should contain a file called @file{debian.rules} +which contains at least the following targets, to be invoked in the top +level directory: + +@smallexample +build +binary +clean +@end smallexample + +@file{debian.rules} should start with + +@example + #!/usr/bin/make -f +@end example + +@noindent and be executable. It is a good idea to arrange for it not +to fail obscurely when invoked in the wrong directory, for example by +testing for the existence of a file in the source directory. + +@itemize @bullet +@item +The @file{build} target should perform all non-interactive configuration +and compilation of the package. If a package has an interactive +pre-build configuration routine, the source package should be built +@emph{after} this has taken place. + + For some packages, notably ones where the same source tree is +compiled in different ways to produce two binary packages, the +@file{build} target does not make much sense. For these packages it is +good enough to provide two (or more) targets (@file{build-a} and +@file{build-b} or whatever) for each of the ways of building the +package, and a @file{build} target that does nothing. The @file{binary} +target will have to build the package in each of the possible ways and +make the binary package out of each. + +@item +The @file{binary} target of @file{debian.rules} should be all that is +necessary for the user to build the binary package. The binary package +should be created using @file{dpkg} and placed in the parent of the top +level directory. The next section describes how to construct binary +packages from the @file{binary} target. + +@item +The @file{clean} target should undo the effects of the @file{build} +target and the @file{binary} target, except that it should leave alone +any @file{../<@i{package}>-<@i{version}>.deb} file created by a run of +@file{binary}. + +@item +Additional targets may exist in @file{debian.rules}. We recommend using +@file{source} and @file{diff} targets to build the Debianised source +package and the Debianisation context diff, respectively. These files +should be placed in @file{../foo-<@i{version}>.tar.gz} and +@file{../foo-<@i{version}>.diff.gz}. The @file{install} target, for +installing into a running system direct from the Debianised source +tree, is no longer required. The sample @file{debian.rules} provides +@file{source} and @file{diff} targets that should work with little or +no alteration, providing that the package-specific variables at the top +of the script have been properly defined. + +@item +If you need to edit a @file{Makefile} where @file{configure} scripts +are used, you should edit the @file{.in} files rather than editing +the @file{Makefile} directly. This allows the user to reconfigure +the package if necessary. You should @emph{not} configure the package +and edit the generated @file{Makefile}! This makes it impossible for +someone else to later reconfigure the package. + +@item +Please document your changes to the source package so that future +package maintainers know what has been changed. To do this, include +a description of your changes in the @file{debian.README} (which, as +described above, should already contain authorship and copyright +information!) and include relevant information such as your name, +electronic mail address, date, etc. + +@item +If changes to the source code are made, please use a @file{define}. If +they are changes required to compile or function under Linux in general, +use @file{LINUX}. If it is a cosmetic or functional change, use +@file{DEBIAN}. + +@item +Create the source package using @file{tar}, and use @file{gzip -9} to +compress it. Source packages should be named in the form +<@i{package}>-<@i{version}>.tar.gz---for example, +@file{fileutils-3.9-3.tar.gz}. + +NB, here @code{<@i{version}>} is the full Debian version number, in the +form @code{<@i{original_version}>-<@i{debian_revision}>} (see below), +but the tarfile should unpack into a directory named +@code{<@i{package}>-<@i{original_version}>} (again, see the section +below on version numbering). + +@item +Create the context diff against the original package using @file{diff +-cNr}, and use @file{gzip -9} to compress it. Context diffs should be +named in the form <@i{package}>-<@i{version}>.diff.gz---for example, +@file{fileutils-3.9-3.diff.gz}. +@end itemize + + Please note that the package and patch filenames do @emph{not} need +to fit in MS-DOS 8+3. They will be made available under an alternative +8+3 name in the archive by the archive maintainer, using a symlink. + + + +@node Binary Package, Control Files, Source Package, Top +@unnumbered Binary Package + + The @file{binary} target of the source package @file{debian.rules} +file should do the following (see the sample @file{debian.rules} +for an implementation that you are free to modify and use in your own +packages, of course): + +@itemize @bullet +@item +Create an empty directory in the top-level directory of the source +package (deleting it first, if necessary), and install the files +belonging to this package in that directory. For example, the directory +could be called @file{debian-tmp} and would probably contain directories +@file{debian-tmp/usr/bin}, @file{debian-tmp/usr/lib}, etc. +(@file{debian-tmp} is the name traditionally used, and it is used in +the sample @file{debian.rules} file, so we will use that name in the +Guidelines.) + +@item +Make sure that all the files under @file{debian-tmp} have the correct +ownerships and permissions (@pxref{Package Content}, for more information +about file locations, ownerships, and permissions.) + +@item +Create a subdirectory of @file{debian-tmp} called @file{DEBIAN}. This +directory contains the package control information, including at the +very least the master information file named @file{control}. The next +section describes the semantics and syntax of the files required and +allowed here. + +@item +Run @file{dpkg} to create the binary package, using something like + +@smallexample + dpkg --build debian-tmp +@end smallexample + +This will create a file called @file{debian-tmp.deb}, from the +@file{debian-tmp} directory. You should rename this file to +@file{../<@i{package}>-<@i{version}>.deb} after it is built. + +After the @file{binary} target has done all this, the +@file{<@i{package}>-<@i{version}>.deb} file in the parent directory is +the binary distribution. This file may be distributed and installed on +any Debian GNU/Linux system with @file{dpkg} in the same manner and +using the same methods as all packages are installed to the system. + +@item +If a single source package corresponds to several binary packages, there +should usually be a @file{debian.rules} file with a single @file{binary} +target that builds all the binary packages involved and move all packages +to the parent directory of that containing the source package. + +In this case, you should choose binary package names which are meant to +make clear the close relationship between the binary packages and which +source package the binary packages came from (for example, the +@file{texinfo} source package build two binary packages: @file{texidoc} +and @file{texinfo}). You should place the appropriate binary package +name in the @file{Package} field of the control file (not the source +package name), and you should consider whether the other binary packages +that come from the same source tree should be mentioned in the +@file{Depends}, @file{Recommends} or @file{Suggests} fields. You +should put the source package name in the @file{Source} field. + +You should retain the source package version numbering in the +@file{Version} field---the version number should be the same for the +Debianised source tree and all the binary packages generated from it. +See below for details of version numbers. +@end itemize + + + +@node Control Files, , Binary Package, Top +@unnumbered Control Files + + Each binary package contains, in addition to the files that comprise +the actual package, a set of text files that control how @file{dpkg} +installs, configures, upgrades, removes, etc. the package. These files +are called @dfn{control files}. When creating the package, the control +files should placed in a directory called @file{DEBIAN}, as described +earlier (@pxref{Binary Package}, for further information). + +The control information files are: + +@table @code +@item control +The master package control information file. +@item conffiles +A list of package configuration files. +@item preinst +The package pre-installation script. +@item postinst +The package post-installation script. +@item prerm +The package pre-removal script. +@item postrm +The package post-removal script. +@end table + + Of these, only @file{control} is required. The various installation +scripts, and the configuration files list, will only be used if they are +present. + +@menu +* control:: +* conffiles:: +* Installation and Removal Scripts:: +* Dependencies and Conflicts:: +* Package Classification Fields:: +@end menu + +@node control, conffiles, Control Files, Control Files +@unnumberedsec control + + The @file{control} file contains a number of fields. Each field +begins with a field name, such as @file{Package} or @file{Version} +(case insensitive), followed by a colon and optionally some spaces or +tabs (a single space is conventional). Then comes the body of the +field, which may be several lines long; each continuation line must +start with at least one space or tab. (These are the same rules as +apply to RFC822 mail headers.) Blank lines are not permitted in the +control file. + + The required fields in the control file are the following: + +@table @code +@item Package +The name of the package. +@item Description +The description of the package. +@item Maintainer +The name and e-mail address of the maintainer of the package. +@item Version +The version number in the format +@code{<@i{original_version}>-<@i{debian_revision}>}. +@end table + + Each field has a particular format and meaning for the package +installation tools. + +The value of @file{Package} should be the name of the package. +Package names must start with an alphanumeric, must be at least two +characters, and may contain only alphanumerics and the characters +- + . @@ : = % _ (that is, hyphen, plus, stop, at, colon, equals, +percent and underscore). They are not case sensitive. + + The @code{Maintainer} field should be in the form + +@smallexample +Joe J. Bloggs <jbloggs@@foo.com> +@end smallexample + +@noindent Note that this will not be useable as an email address if +the name given contains full stop characters, because of a silly +restriction in the Internet mail standards. If you want to use this +as an email address in a program you should check for full stops and +change the string to the form @code{jbloggs@@foo.com (Joe J. Bloggs)} +if you find any. + + The @code{Version} field should be the version number of the +package. For most packages which are not written specifically for +Debian, this should be in the form + +@smallexample +Version: <@i{original_version}>-<@i{debian_revision}> +@end smallexample + +@noindent where @file{<@i{original_version}>} is the original package +version number in whatever form the original package uses and +@file{<@i{debian_revision}>} indicates which ``debianisation'' this is +(this should usually be a plain number or perhaps a two numbers +separated by a full stop, and should be incremented each time the +package is changed or updated). + + Packages which are written specifically for Debian do not have a +@i{debian_revision}, and their version number should simply be +@i{version} (which should not contain any hyphens, to avoid +confusion). + + There is an ordering imposed on version numbers, described in +@file{version-ordering.txt}. This ordering is designed to `do the right +thing' in most circumstances; if your package has an version number in +an unusual format you may need to reformat it somewhat to get the +ordering right. This is important because @file{dpkg} is (for example) +reluctant to downgrade packages. + + The optional fields in the control file are the following: + +@table @code +@item Depends +The names of prerequisite packages. +@item Recommends +The names of related, recommended packages. +@item Suggests +The names of related, optional packages. +@item Conflicts +The names of packages which conflict with this package. +@item Provides +The names of virtual packages which this package provides. +@item Priority +The `priority' of the package, as shown and used by @file{dselect}. +@item Section +The `section' of the package, as shown and used by @file{dselect}, and +used as a location for the package in the distribution. +@item Essential +A boolean field used by the base packages. +@end table + +@noindent See below for details of the semantics and syntax of these +fields. Most packages will need at least a @code{Depends} field. + + An example of a @file{control} file would be: + +@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. +@end example + + In this case, @file{mail-user-agent} is a virtual package +representing any user mailer program; the actual package names +@file{pine} is quoted for the reasons described in +@file{dependency-ordering.txt}, and the others because older versions +of those packages do not have the appropriate @file{Provides} field. + +@node conffiles, Installation and Removal Scripts, control, Control Files +@unnumberedsec conffiles + + The contents of @file{conffiles} is simply a list of configuration +files in the package. When installing the package, @file{dpkg} uses +an intelligent method to update these files. This will ensure that +package-specific configuration files are not overwritten when a package +is upgraded, unless the user wishes the installation tools to do so. + + Typically, files listed in conffiles are package-specific +configuration files, which (according to the Linux Filesystem Standard) +are stored in @file{/etc}. For example, the @code{sendmail} package may +contain the file @file{/etc/sendmail.cf}, which we do not wish to +overwrite automatically when the user upgrades the sendmail package. +Only those files listed in @file{DEBIAN/conffiles} will be updated +intelligently when a package is upgraded; all other files in the package +will be overwritten by the upgrade process. + + Configuration files which will be functional as shipped and will +probably need little or no local editing should simply be listed the +@file{conffiles} file; in this case you need read no further. + + For packages whose configuration files will need modification on +most systems there are two sensible approaches. Which one is chosen +depends on how hard the configuration problem is and how much time the +package maintainer has available. + + One option is for you to ship a minimal `best-effort' file in +@file{/etc}, and list the file in @file{conffiles}. This will mean that +the user will have to go and edit the file themselves to get the package +to work properly, of course. The next time they upgrade the package, if +you haven't changed the file version, their old file will be left in +place. If you have modified your version then the user will get a +prompt asking them which version of the file they want, theirs or yours. +They will then usually have to resolve the discrepancies manually. + + The other option is to be preferred, if you can do it: don't put a +copy of the configuration file in the package at all. Instead, you +check in the postinst whether the file exists, and if it doesn't you +prompt the user for the information you need to create a good one. This +is obviously harder work. + + You also have to remember that you will have to keep up with your +package's changes: 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. + + If you do go down this route it's probably a good idea to make the +program that generates the configuration file(s) a separate program in +@file{/usr/sbin}, by convention called @i{package}@code{config}, and +then run that if appropriate from the post-installation script. The +@i{package}@code{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 @code{--force} flag to +overwrite it. + + @file{conffiles} should almost certainly list all the files contained +in your package in the @file{/etc} directory. There may also be other +files somewhere that the user is expected to edit, which should also be +included. Note, however, that the FSSTND specifies that configuration +files must be in @file{/etc}. No Debian package should contain +configuration files in @file{/usr/etc}, and all programs should refer to +configuration files in @file{/etc}. + +@noindent For example, the TCP/IP package might use a conffiles which contains + +@example + /etc/init.d/netbase + /etc/gateways + /etc/protocols + /etc/services + /etc/hosts.allow + /etc/hosts.deny + /etc/rpc +@end example + +@noindent and so on; the files + +@example + /etc/hosts + /etc/inetd.conf + /etc/host.conf + /etc/networks + /etc/resolv.conf +@end example + +@noindent might be generated by an interactive configuration program, +and would then not be included in the package or listed in the +@file{conffiles}. + +@node Installation and Removal Scripts, Dependencies and Conflicts, conffiles, Control Files +@unnumberedsec Installation and Removal Scripts + + The scripts @file{preinst}, @file{postinst}, @file{prerm}, and +@file{postrm} are optional (Bash or Perl) scripts. As the names +would indicate, if these scripts exist, they will be executed before +installing the package, after installation, before package removal, +and after removal, respectively. + + They are given arguments which indicate the precise situation and +action being performed---see @file{maintainer-script-args.txt} for +details of exactly when each of the scripts is invoked and what its +arguments are. Extra arguments and situations may be added later, so +you should not test the number of arguments to your script to determine +the situation, and you should choose the sense of your `if it is this +then do this otherwise do that' tests carefully. + + These scripts can be used to perform any site-specific package +configuration. + + Because the scripts will be exectued by the dpkg front-end, it is +guaranteed that the scripts will be executed interactively. User input +from the scripts should be read from standard input, not the user's +terminal. Similarly, output should be sent to standard output. + + If your maintainer scripts need to prompt for passwords and/or do +@i{full-screen} interaction should do these things to and from +@file{/dev/tty}, since @file{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 @code{$|=1} so that the output is printed +immediately rather than being buffered. + + The scripts must be idempotent, and they must clean up after +themselves properly. Ie, they must do the right thing if run multiple +times, even if previous runs failed halfway through. This is so that if +any errors occur, or if the @file{dpkg} run is interrupted, the user can +recover by rerunning @file{dpkg}, and/or by upgrading to a new version +and then rerunning the failed operation. + + These scripts should avoid producing output which it is unnecessary +for the user to see and should rely on @file{dpkg} to stave off boredom +on the part of a user installing many packages. This means, amongst +other things, using the @file{--quiet} option on @file{install-info}. + + Packages should try to minimise the amount of prompting they need to +do, and they should ensure that the user will only every be asked each +question once. This means that packages should try to use appropriate +shared configuration files (such as @file{/etc/papersize} and +@file{/etc/news/server}), rather than each prompting for their own list +of required pieces of information. + + It also means that an upgrade should not ask the same questions +again, unless the user has used @code{dpkg --purge} to remove the +package's configuration. The answers to configuration questions should +be stored in an appropriate place in @file{/etc} so that the user can +modify them, and how this has been done should be documented. + + 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 +@file{postinst} script and prompt the user to hit Return to acknowledge +the message. Copyright messages do not count as vitally important (they +belong in @file{/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). + + They should return a zero exit status for success, or a nonzero one +for failure. Note that if a script is a @code{#!/bin/sh} script it +should probably start with @code{set -e}, to avoid continuing after +errors---see @file{bash}(1) for details. Perl scripts should check for +errors when making calls such as @code{open}, @code{print}, +@code{close}, @code{rename} and @code{system}. + + If these scripts exist they should be left in the @file{DEBIAN} +directory with execute permission enabled and should contain an +appropriate @code{#!} line, such as @code{#!/bin/bash} for a +@code{bash} script or @code{#!/bin/perl} for a Perl script (see +above). + +@node Dependencies and Conflicts, Package Classification Fields, Installation and Removal Scripts, Control Files +@unnumberedsec Conflicts, Depends, Suggests, Recommends and Provides + + The @file{Depends} field lists packages that are required for this +package to provide a significant amount of functionality. The package +maintenance software will not allow a package to be installed without +also installing packages listed in its @code{Depends} field, and will +run the @code{postinst} scripts of packages listed in @code{Depends} +fields before those of the packages which depend on them, and run the +@code{prerm} scripts before. + + Packages containing dynamically-linked executable binaries (this +includes almost all C programs) should include a @file{Depends} field +which mentions the shared C library required for the program to run. +For a.out binaries linked against @file{libc.so.4} the relevant package +name is @file{libc}; for ELF binaries linked against @file{libc.so.5} +the relevant package name is @file{libc5}. + + The @code{Recommends} field lists packages that would be found +together with this one in all but unusual installations. The user-level +package maintenance program @file{dselect} will warn the user if they +select a package without those listed in its @code{Recommends} field. +Note that @code{Recommends} fields don't currently have any implications +for the order in which the maintainer scripts are run. + + The @code{Suggests} field lists packages that are related to this one +and can perhaps enhance its usefulness, but without which installing +this package is perfectly reasonable. The package maintenance software +will not moan at the user for not selecting @code{Suggests} related +packages, but may use the information in the @code{Suggests} field to +assist the user during package selection. + + The syntax of @code{Depends}, @code{Recommends} and @code{Suggests} +is a list of groups of alternative packages. Each group is a list of +packages separated by vertical bar (or `pipe') symbols, @code{|}. The +groups are separated by commas. Each package is a package name +optionally followed by a version number specification in parentheses. A +version number may start with a @code{>=}, in which case that version or +any later will match, or @code{<=} for that version or any earlier +version. A version number starting with a @code{>>} or @code{<<} will +respectively match any later or earlier version. If a version number or +a version number starting with @code{=} is specified an exact match is +required. Commas are to be read as `AND', and pipes as `OR', with pipes +binding more tightly. + + Versions of dpkg before 1.0.9 used @code{<} and @code{>} for +@code{<=} and @code{>=} (these are still supported for backward +compatibility), and did not support @code{<<} and @code{>>}. + + The @code{Conflicts} field lists packages that conflict with this +one, for example by containing files with the same names (an example +would be Smail vs. Sendmail). The package maintenance software will not +allow conflicting packages to be installed. Two conflicting packages +should each include a @code{Conflicts} line mentioning the other. + + The syntax of @code{Conflicts} is a list of package names (with +optional version numbers), separated by commas (and optional +whitespace). In the @code{Conflicts} field the comma should be read as +`OR'. + + The @code{Provides} field lists the names of any `virtual packages' +of which this packages is to be considered an instantiation. Virtual +packages are used to allow packages to refer to a service they require +(such as the availability of @file{/usr/sbin/sendmail}) without having +to know the names of all the relevant packages. The virtual package +names defined in @code{Provides} fields may be used in other packages' +@code{Depends}, @code{Recommends}, @code{Suggests} and @code{Conflicts} +fields. For more information about how to use virtual packages and +which virtual package names to use read @file{virtual-dependencies.txt} +and @file{virtual-package-names-list.text}. + + The syntax of @code{Provides} is a list of package names separated by +commas (and optional whitespace). + +@node Package Classification Fields, , Dependencies and Conflicts, Control Files +@unnumberedsec Priority, Section and Essential + + The @code{Priority} and @code{Section} fields are used by +@file{dselect} when displaying the list of packages to the user. There +is no need to put them into a package, since these are usually set by +the distribution maintainers in the @file{Packages} file. + + However, if a user installs a package which is not part of the +standard distribution, or without downloading and updating from a new +@file{Packages} file, the information about the priority and section of +a package will be absent, and the @file{dselect} package listing will +have the package listed under `unclassified'. It is permissible for a +package to include @code{Section} or @code{Priority} fields to improve +this; however, if you do this you should make sure you keep the +information up to date so that users are not shown conflicting +information. The @code{Section} field can also be used by the +distribution maintainers as a suggestion about which section you think +is most appropriate for your package. + + The @code{Essential} field should only appear in packages in the +installation's base system. If it is set to @code{yes} then @file{dpkg} +will not remove the package even if asked to, and will make certain +minor modifications to its installation procedures. The only other +legal value is @code{no}, which is equivalent to the absence of the +field. + +@bye + +@c local variables: +@c kept-new-versions: 100 +@c version-control: t +@c end: diff --git a/doc/guidelines.texi.rej b/doc/guidelines.texi.rej new file mode 100644 index 000000000..15354007c --- /dev/null +++ b/doc/guidelines.texi.rej @@ -0,0 +1,33 @@ +*************** +*** 376,390 **** + Generally the following compilation parameters should be used: + + @display +- CC = gcc +- CFLAGS = -O2 +- LDFLAGS = -s (and -N, if appropriate; see below) + @end display + + All installed binaries should be stripped, hence @code{-s}. @code{-N} + should only be used on binaries that are very small (less than 8K with + the @code{-N} option, roughly) and are not likely to have multiple +- instances in memory. Do not use @code{-N} on daemons, no matter how + small they are. + + It is up to the package maintainer to decide what compilation options +--- 383,397 ---- + Generally the following compilation parameters should be used: + + @display ++ CC = gcc ++ CFLAGS = -O2 ++ LDFLAGS = -s (and -N, if appropriate; see below) + @end display + + All installed binaries should be stripped, hence @code{-s}. @code{-N} + should only be used on binaries that are very small (less than 8K with + the @code{-N} option, roughly) and are not likely to have multiple ++ instances in memory. Don't use @code{-N} on daemons, no matter how + small they are. + + It is up to the package maintainer to decide what compilation options diff --git a/doc/junk b/doc/junk new file mode 100644 index 000000000..46c358738 --- /dev/null +++ b/doc/junk @@ -0,0 +1,29 @@ + +@table @file +@item virtual-package-names-list.text +The list of virtual package names currently in use, together with the +procedure for getting new virtual package names allocated. +@item (obsolete) README.etc-skel +A description of @file{/etc/skel} and @file{/usr/doc/examples} +(@pxref{Skeleton and examples}). +@item (obsolete) descriptions.txt +The description of the package. How to write an extended and more useful +description field (@pxref{Package description}). +@item (obsolete) README.init +How to use the features of Init under Debian GNU/Linux in packages +(@pxref{Configuration of init}). +@item (obsolete) mailers.txt +How to properly configure packages to use the Debian GNU/Linux mail +nnsystem (@pxref{Mail processing packages}). +@item (obsolete) maintainer-script-args.txt +All the ways that the package maintainer scripts inside a package can be +called by dpkg (@pxref{Maintainer script arguments}). +@item (obsolete) dpkg-upgrades+errors.txt +What order things happen in during a package upgrade (@pxref{What +happends during a package upgrade?}). +@item (obsolete) virtual-dependencies.txt +How to use ``virtual dependencies'' in packages (@pxref{Virtual +dependencies}). +@item (obsolete) dependency-ordering.txt +How to properly order package names in the @file{DEPENDS} field. +@end table diff --git a/doc/maintainer-script-args.txt b/doc/maintainer-script-args.txt new file mode 100644 index 000000000..a1cd3c75c --- /dev/null +++ b/doc/maintainer-script-args.txt @@ -0,0 +1,173 @@ +Richard Kettlewell has asked me to document this, so here is a brief +summary. More documentation will probably have to wait until someone +has time ... + +... hmm, it has turned out not to be so brief, and I've spent the last +hour or so writing it. Perhaps someone can use it as the basis for a +spec or a manpage or something. + +In all cases version numbers are <version>-<revision>, if the package +has both, or just <version>. `upgrade' is used even when the new +version number looks lower than the old. + +*** SUMMARY - listing of possible scripts with arguments: + + <new preinst> install + <new preinst> install <old-version> + <new preinst> upgrade <old-version> + <old preinst> abort-upgrade <new-version> + + <postinst> configure + <old postinst> abort-upgrade <new version> + <conflictor's postinst> abort-remove in-favour <package> <new version> + <deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> + + <prerm> remove + <old prerm> upgrade <new version> + <new prerm> failed-upgrade <old-vppersion> + <conflictor's prerm> remove in-favour <package> <new version> + <deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> + + <postrm> remove + <postrm> purge + <old postrm> upgrade <new-version> + <new postrm> failed-upgrade <old-version> + <new postrm> abort-install + <new postrm> abort-install <old-version> + <new postrm> abort-upgrade <old-version> + <disappearer's postrm> disappear <overwriter> <new version> + +*** INSTALLATION (unpack): + +The procedure on installation/upgrade/overwrite/disappear (ie, when +running dpkg --unpack, or the unpack stage of 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. + +1a. If a version the package is already installed, call + <old prerm> upgrade <new version> +1b. If this gives an error (ie, a non-zero exit status), dpkg will +attempt instead: + <new prerm> failed-upgrade <old-version> + ... error unwind, for both the above cases: + <old postinst> abort-upgrade <new version> + +2. If a `conflicting' package is being removed at the same time: +2a. If any packages depended on that conflicting package and +--auto-deconfigure is specified, call, for each such package: + <deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> + ... error unwind: + <deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> +The deconfigured packages are marked as requiring configuration, so +that if --install is used they will be configured again if possible. +2b. To prepare for removal of the conflicting package, call: + <conflictor's prerm> remove in-favour <package> <new version> + ... error unwind: + <conflictor's postinst> abort-remove in-favour <package> <new version> + +3a. If the package is being upgraded, call + <new preinst> upgrade <old-version> +3b. otherwise, if the package had some configuration files from a +previous version installed (ie, it is in the conffiles-only state): + <new preinst> install <old-version> +3c. otherwise (ie, the package was completely purged): + <new preinst> install + ... error unwind versions, respectively: + <new postrm> abort-upgrade <old-version> + <new postrm> abort-install <old-version> + <new postrm> abort-install + +4. The new package's files are unpacked, overwriting any that may be +on the system already, for example any from the old 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). + +5a. If the package is being upgraded, call + <old postrm> upgrade <new-version> +5b. If this fails, dpkg will attempt: + <new postrm> failed-upgrade <old-version> + ... error unwind, for both cases: + <old preinst> abort-upgrade <new-version> + +This is the point of no return - if 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 dpkg starts doing things that are +irreversible. + +6. Any files which were in the old version of the package but not in + the new are removed. +7. The new file list replaces the old. +8. The new maintainer scripts replace the old. + +9. 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, +9a. dpkg calls: + <disappearer's postrm> disappear <overwriter> <new version> +9b. The package's maintainer scripts are removed. +9c. It is noted in the status database as being in a sane state, +namely not installed (any conffiles it may have are ignored). +Note that disappearing packages don't have their prerm called, because +dpkg doesn't know in advance that the package is going to vanish. + +10. 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.) + +11. The backup files made at 4. are deleted. +12. 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 don't unwind the rest of the installation; the +conflicting package is left in a half-removed limbo. + +13. If there was a conflicting package we go and do the removal +actions, starting from point 2. of the removal, below. + + +*** CONFIGURATION: + +When we configure a package (this happens with dpkg --install, or with +--configure), we first update the conffiles and then call: + <postinst> configure +(I'm planning to make available as an argument the version of the most +recent successfully-configured version of the package.) + +No attempt is made to unwind after errors during configuration. + + +*** REMOVAL: + +1. <prerm> remove + +2. The package's files are removed (except conffiles). + +3. <postrm> remove + +4. All the maintainer scripts except the postrm are removed. + +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 dpkg status. + +5. The conffiles and any backup files (~-files, #*# files, %-files, +.dpkg-{old,new,tmp}, &c &c &c) are removed. + +6. <postrm> purge + +7. The package's file list is removed. + +No attempt is made to unwind after errors during removal. diff --git a/doc/upgrades+errors.txt b/doc/upgrades+errors.txt new file mode 100644 index 000000000..09b5bd5ee --- /dev/null +++ b/doc/upgrades+errors.txt @@ -0,0 +1,220 @@ +From ian Wed Nov 16 15:12:56 1994 +X-VM-v5-Data: ([nil nil nil nil t nil nil nil nil] + [nil "Wed" "16" "November" "1994" "15:12:56" nil "ian" "ian" "" nil "dpkg - upgrades and error handling, take 2" "^To:" nil nil "11" nil nil nil nil] + nil) +To: Debian dpkg list <debian-dpkg@pixar.com> +Subject: dpkg - upgrades and error handling, take 2 + +Here is a revised scheme for upgrade procedure and error handling. + +If you can see any serious problems with this please say so; if there +are no compelling reasons not to I intend to implement the following. + + +Procedure for new unpack: + * Run the preinst script (argument: `install'). + * Back up the conffiles. + * Unpack the files in the package. +This leaves the package in the `unpacked but not configured' +state. + +If the preinst fails the installation is aborted immediately, leaving +the package in whatever state it was originally. The preinst should +clean up after its own failure. + +If the conffiles can't be backed up then any which have been are +restored to their original names, if possible, and the postrm script +is run if there is one (argument: `abort-install'). This leaves the +package in its original state. + +If the unpack fails any files already unpacked are removed, the +conffiles are restored to their original names, and the postrm is run +(argument: `abort-install'). Again, the package remains in its +original state. + +Errors found when running the postrm are ignored. + + +Procedure for configuration: + * Do the conffile updating, including prompting, as in the spec. + * Run the postinst (argument: `configure'). + +If the conffile updating fails anything that has been done is undone +if possible and the package is left in the `unpacked but not +configured' state. + +If the postinst fails dpkg gives up and leaves the package in the +`postinst failed' state. Next time it will just rerun the +postinst; if the postinst has a bug a new *.deb can be provided. In +that case installation of the new *.deb will proceed almost as if it +were a normal upgrade. + + +Procedure for removal: + * Run the prerm (argument: `remove'). + * Delete the files in the package and any resulting empty + directories. + * Run the postrm (argument: `remove'). + +If the prerm fails dpkg leaves the package in the original state; if +the user asks again to remove the package the prerm will be run again. + +If the deletion fails the removal is aborted, and the package left in +the `removal failed' state. + +If the postrm fails dpkg leaves the package in the `removal failed' +state. + +If the package is in the `removal failed' state to start with it will +start again with deleting the files and empty directories and rerun +the postrm. + +If the postrm has a bug a new *.deb must be installed first (using the +upgrade procedure) and then removed. This is so that a working postrm +script is provided. + + +Procedure for upgrade: + * Run the old prerm script (arguments: `upgrade <new-version>'). + * Move aside all existing files (not directories) for the + package being overwritten. + * Run the old postrm script (arguments: `upgrade <new-version>'). + * Run the new preinst script (arguments: `upgrade <old-version>'). + * Back up the conffiles. + * Unpack the files in the package. + * Remove the files which were moved aside. +This leaves the package in the `unpacked but not configured' +state. + +Errors during the removal of the files which were moved aside are +flagged, but don't cause dpkg to attempt to abort the upgrade. + +If the old prerm or postrm script fails the corresponding script from +the new package is run instead (arguments: `failed-upgrade +<old-version>'). If there is no corresponding script in the new +package the error is ignored. + +If any other stage fails, or if we try to use the script in the new +package because the old prerm/postrm script failed but the new script +fails too, we attempt to undo everything in reverse order, as follows: + +Unpacking the files in the package is undone by removing the files we +unpacked and any empty directories, in reverse order. Errors are +ignored. + +The conffiles backup is undone as much as possible, ignoring errors. + +The new preinst is undone by running the new postrm (arguments: +`abort-upgrade <old-version>'); errors are ignored. + +The old postrm is undone by running the old preinst (arguments: +`abort-upgrade <new-version>'); errors are ignored. + +Files we backed up are restored if possible; errors here leave the +package in the `removal failed' state. + +The old prerm is undone by running the old postinst (arguments: +`abort-upgrade <new-version>'). Errors here leave the package in the +`postinst failed' state. + + +Ian. + +From ian Wed May 17 02:14:09 +0100 1995 +X-VM-v5-Data: ([nil nil nil nil nil nil nil nil nil] + [nil nil nil nil nil nil nil nil nil nil nil nil "^To:" nil nil nil nil nil nil nil] + nil) +To: Debian developers list <debian-devel@pixar.com> +Subject: New dpkg overwriting handling + +Here is a comment that describes how I plan to have the new C dpkg act +with respect to overwriting, upgrades, &c. + +The sequence of events during upgrade will change, because the removal +of the old package and the installation of the new will take place +together. So we have, + + (noninteractive, during `dpkg --unpack' ...) + old prerm + new preinst + unpack new archive, possibly overwriting old files + delete any files in the old but not the new package + old postrm + run `postrm disappear' for any vanished packages, then forget them + + (interactive, during `dpkg --configure' ...) + conffile updates + new postinst + +Furthermore, conffiles will not be backed up before unpack and have +the user's old version hang around as `.dpkg-tmp'; instead, the old +file will be left in place and the new one extracted into `.dpkg-new'. +It will only be installed (if desired) at a conffile update. + +Thanks to Bruce for providing nice tar-in-a-function code that will +allow me to handle each file individually rather than having tar splat +them all out (and often do it buggily anyway). + +Ian. + + /* + * Now we unpack the archive, backing things up as we go. + * For each file, we check to see if it already exists. + * There are several possibilities: + * + We are trying to install a non-directory ... + * - It doesn't exist. In this case we simply extract it. + * - It is a plain file, device, symlink, &c. We do an `atomic + * overwrite' using link() and rename(), but leave a backup copy. + * Later, when we delete the backup, we remove it from any other + * packages' lists. + * - It is a directory. We move it aside and extract the file. + * Later, when we delete the backed-up directory, we remove it + * from any other packages' lists. + * + We are trying to install a directory ... + * - It doesn't exist. We create it with the appropriate modes. + * - It is a plain file or a symlink. We move it aside and create + * the directory. Later, when we delete the backup, we remove it + * from any other packages' lists. + * - It exists as a directory. We do nothing. + * + * Install non-dir Install dir + * Exists not X C + * File/node/symlink LXR BCR + * Directory BXR - + * + * C: create directory + * X: extract file/node/link + * LX: atomic overwrite leaving backup + * B: ordinary backup + * R: later remove from other packages' lists + * -: do nothing + * + * After we've done this we go through the remaining things in the + * lists of packages we're trying to remove (including the old + * version of the current package). This happens in reverse order, + * so that we process files before the directories (or symlinks-to- + * directories) containing them. + * + If the thing is a conffile then we leave it alone for the purge + * operation. + * + Otherwise, there are several possibilities too: + * - The listed thing does not exist. We ignore it. + * - The listed thing is a directory or a symlink to a directory. + * We delete it only if it isn't listed in any other package. + * - The listed thing is not a directory or a symlink to one (ie, + * it's a plain file, device, pipe, &c, or a symlink to one, or a + * dangling symlink). We delete it. + * The removed packages' list becomes empty (of course, the new + * version of the package we're installing will have a new list, + * which replaces the old version's list). + * + * If at any stage we remove a file from a package's list, and the + * package isn't one we're already processing, and the package's + * list becomes empty as a result, we `vanish' the package. This + * means that we run its postrm with the `disappear' argument, and + * put the package in the `not-installed' state. Its conffiles are + * ignored and forgotten about. + * + * NOTE THAT THE OLD POSTRM IS RUN AFTER THE NEW PREINST, since the + * files get replaced `as we go'. + */ + diff --git a/doc/version-ordering.txt b/doc/version-ordering.txt new file mode 100644 index 000000000..7bbda6304 --- /dev/null +++ b/doc/version-ordering.txt @@ -0,0 +1,59 @@ +(This has been edited to conform to the intent in dpkg 1.0.16. + When recent versions of dpkg compare versions they break the Version + into an upstream version and debian revision first, by splitting the + Version at the last hyphen. The revisions are only considered if the + upstream versions compare equal.) + +To: debian-devel@pixar.com +Subject: Re: dpkg 0.93.8 released + +[...] +Well, here is what I came up with after a bit of thought and testing. +I propose the following algorithm for comparing version numbers: + + forever { + remove initial non-digit substring from string a + remove initial non-digit substring from string b + compare initial non-digit substrings lexically, + counting letters as coming before punctuation + if (they differ) return the answer + remove initial digit substring from string a + remove initial digit substring from string b + compare initial digit substrings numerically + if (they differ) return the answer + if (both strings are now empty) + the version numbers are the same, stop + if (one string is now empty) + it is the `lesser', return the answer + } + +This will have the desired results: + 2.1 < 2.7 < 2.7a < 2.7a-2 < 2.15 + +An implementation in Perl is attached below. + +Ian. + +#!/usr/bin/perl -- + +if (@ARGV) { + print &compare(@ARGV),"\n"; +} else { + while(<>) { chop; chop($x=<>); print &compare($_,$x),"\n"; } +} + +sub compare { + local ($a,$b) = @_; + do { + $a =~ s/^\D*//; $ad= $&; $ad =~ s/\W/ /g; + $b =~ s/^\D*//; $bd= $&; $bd =~ s/\W/ /g; +print "\t[$ad|$a] [$bd|$b]\n"; + $cm = $ad cmp $bd; return $cm if $cm; + $a =~ s/^\d*//; $ad= $&; + $b =~ s/^\d*//; $bd= $&; +print "\t<$ad|$a> <$bd|$b>\n"; + $cm = $ad <=> $bd; return $cm if $cm; + } while (length($a) && length($b)); +print "\t{$a} {$b}\n"; + return length($a) cmp length($b); +} diff --git a/doc/virtual-dependencies.txt b/doc/virtual-dependencies.txt new file mode 100644 index 000000000..1f45eb7a0 --- /dev/null +++ b/doc/virtual-dependencies.txt @@ -0,0 +1,105 @@ +To: Debian users list <debian-user@pixar.com> +Subject: dpkg 0.93.36: dselect does virtual packages + +This release contains virtual package support in the C parts of the +system, which at the moment includes dselect and dpkg-deb. + +It works as I outlined in a mail to debian-devel a little while ago. + +Package maintainers: please start adding `Provides:' fields to your +packages. dselect will use and understand them; dpkg-deb will check +the syntax of the Provides field instead of warning you about it. +dpkg will not understand the new field and will ignore it. + +When almost all the packages have Provides: fields in place we can +start replacing old-style Recommended: fields. + +Note that we can't change Depends: fields since they're also +interpreted by dpkg, which doesn't know about Provides (yet). + +[...] +-------------------- + +From: iwj10@cus.cam.ac.uk (Ian Jackson) +To: debian-devel@pixar.com +Subject: `virtual' packages in Depends, Conflicts &c +Date: Fri, 31 Mar 95 15:44 BST + +We're starting to have a problem with package name changes and +multiple packages providing the same service. + +I liked the idea (put forward by [Bruce Perens]) of having `virtual' +packages; it seems that it would solve many of these problems straight +away. + +What I'm proposing to do is as follows: + +Depends, Conflicts, Recommended and Optional lines will now be able to +contain `virtual' package names as well as real package names. + +Virtual packages are in the same namespace as real packages, and may +have the same name. The meaning of a virtual package in a +dependency/conflicts list is exactly that of listing all the real +packages which state that they are an instantiation of that virtual +package. + +This is done with a new Provides field in the control file, with a +syntax much like the Conflicts field. + +The idea is that we can have something like: + Package: elm + Depends: mta + + Package: smail + Provides: mta + Conflicts: mta + + Package: sendmail + Provides: mta + Conflicts: mta +&c. The result is equivalent to elm having said + Depends: smail | sendmail + +(There'll be a special case to say that a package may conflict with a +virtual package which it provides - clearly ...) + +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 + Package: lout + Optional: ghostview +(this is a fictional example - the Lout package shouldn't mention +ghostview), and someone else comes up with a nice PostScript +previewer, then they can just say + Package: marvelpostview + Provides: ghostview +and all will work in the interim (until, say, the Lout maintainer +changes things). + +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 prohibited, for a conflict) - it is assumed that a real +package which provides virtual package is not of the `right' version. +If there is demand I could arrange that a package which provides a +virtual package may mention a version number, eg. + Provides: mta (2.0) +though I tbink this is unlikely to be helpful. + +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 +can simply list the real package as alternative before the virtual +one. E.g.: + Package: xbaseR6 + Recommended: xsvga | x-server + Provides: x-base, xr6shlib + + Package: xsvga + Recommended: x-base + Provides: x-server + + Package: x8514 + Recommended: x-base + Provides: x-server + +Ian. |