From: Ian Jackson Date: Sat, 10 Aug 1996 22:35:51 +0000 (+0100) Subject: dpkg (1.3.3) experimental; urgency=low X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f50dc4ae0a76894d2446bbc59144ed72beb380ff;p=dpkg dpkg (1.3.3) experimental; urgency=low * Programmers' & policy manuals in source tree; HTML in /usr/doc/dpkg. * Old guidelines.info and text files in /usr/doc/dpkg removed. * dpkg-source sets permissions on extracted debianised source tree and does not copy ownerships out of archive even if running as root. * Emacs mode `dpkg changelog' renamed to `Debian changelog'. * Default changelog format renamed from `dpkg' to `debian'. * debian-changelog-mode sets fill-prefix correctly. * debian-changelog-mode urgencies except HIGH lowercase by default. * debian-changelog-mode displays keymap in doc string and so mode help. * More maintainers' PGP keys. * Remove built changelog parsers with `clean' target in source. -- Ian Jackson Sat, 10 Aug 1996 23:35:51 +0100 --- diff --git a/debian/changelog b/debian/changelog index b48d6098..547ebc47 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,24 @@ +dpkg (1.3.3) experimental; urgency=low + + * Programmers' & policy manuals in source tree; HTML in /usr/doc/dpkg. + * Old guidelines.info and text files in /usr/doc/dpkg removed. + + * dpkg-source sets permissions on extracted debianised source tree + and does not copy ownerships out of archive even if running as root. + + * Emacs mode `dpkg changelog' renamed to `Debian changelog'. + * Default changelog format renamed from `dpkg' to `debian'. + + * debian-changelog-mode sets fill-prefix correctly. + * debian-changelog-mode urgencies except HIGH lowercase by default. + * debian-changelog-mode displays keymap in doc string and so mode help. + + * More maintainers' PGP keys. + + * Remove built changelog parsers with `clean' target in source. + + -- Ian Jackson Sat, 10 Aug 1996 23:35:51 +0100 + dpkg (1.3.2) experimental; urgency=LOW (MEDIUM for dpkg-source) * Faster update-rc.d written in Perl by Miquel van Smoorenburg. @@ -1552,5 +1573,5 @@ Thu Aug 25 11:46:27 1994 Ian Murdock (imurdock@debra.debian.org) ChangeLog begins Thu Aug 25 11:46:27 1994 for dpkg 0.93.5. Local variables: -mode: dpkg-changelog +mode: debian-changelog End: diff --git a/debian/postinst b/debian/postinst index e5ef4d2d..545c24b9 100755 --- a/debian/postinst +++ b/debian/postinst @@ -2,9 +2,6 @@ set -e -install-info --section Development Development \ - --quiet /usr/info/guidelines.info.gz - dupdaemonhelp () { cat <<'END' diff --git a/debian/rules b/debian/rules index dfa32378..4fa10962 100755 --- a/debian/rules +++ b/debian/rules @@ -36,7 +36,6 @@ binary: checkroot build datadir=$(DIR)/debian/tmp/var/lib/dpkg \ etcdir=$(DIR)/debian/tmp/etc \ install - gzip -9 debian/tmp/usr/info/guidelines.info* cp debian/copyright debian/tmp/usr/doc/copyright/dpkg cp TODO debian/tmp/usr/doc/dpkg/WISHLIST touch debian/tmp/var/lib/dpkg/{status,available} diff --git a/doc/Makefile.in b/doc/Makefile.in index 3c0afeb9..a64b312a 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -35,15 +35,22 @@ INSTALL_DATA = @INSTALL_DATA@ MAKEINFO = makeinfo TEXI2DVI = texi2dvi -DPKGDOCS= auto-deconfiguration.txt dependency-ordering.txt \ - disappear-replace.txt diversions.text \ - essential-flag.txt version-ordering.txt developer-keys.pgp +DPKGDOCS= developer-keys.pgp + +SGMLDOCS= programmer policy -# Files folded into main guidelines document +# Files folded into manuals OBSOLETEDOCS= descriptions.txt upgrades+errors.txt \ - maintainer-script-args.txt virtual-dependencies.txt + maintainer-script-args.txt virtual-dependencies.txt \ + auto-deconfiguration.txt dependency-ordering.txt \ + disappear-replace.txt diversions.text \ + essential-flag.txt version-ordering.txt + +all: $(DPKGDOCS) $(SGMLDOCS) -all: $(DPKGDOCS) guidelines.info +$(SGMLDOCS): + debiandoc2html $@.sgml + touch $@ guidelines.info: guidelines.texi $(MAKEINFO) $(srcdir)/guidelines.texi @@ -57,16 +64,12 @@ database-structure.monops: database-structure.ps 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 $(SGMLDOCS) rm -f database-structure.ps database-structure.monops ps rm -f *.{aux,cp,dvi,fn,ky,log,pg,toc,tp,vr,bak} - rm -f guidelines.info* + rm -f guidelines.info* *.sasp* + rm -rf {programmer,policy}.html distclean: rm -f Makefile *.orig *~ *.~* ./#*# @@ -75,8 +78,9 @@ install: all $(INSTALL_DATA) deb.5 $(man5dir)/deb.$(man5) $(INSTALL_DATA) deb-old.5 $(man5dir)/deb-old.$(man5) $(INSTALL_DATA) deb-control.5 $(man5dir)/deb-control.$(man5) - $(INSTALL_DATA) guidelines.info guidelines.info-*[0-9] \ - $(infodir)/. + set -e; for f in $(SGMLDOCS) ; do \ + cp -r $$f.html $(dpkgdocdir)/$$f.html ; \ + done set -e; for d in $(DPKGDOCS) ; do \ $(INSTALL_DATA) $$d $(dpkgdocdir)/$$d ; \ done diff --git a/doc/developer-keys.pgp b/doc/developer-keys.pgp index e3073bbc..3877423a 100644 Binary files a/doc/developer-keys.pgp and b/doc/developer-keys.pgp differ diff --git a/doc/junk b/doc/junk deleted file mode 100644 index 46c35873..00000000 --- a/doc/junk +++ /dev/null @@ -1,29 +0,0 @@ - -@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/auto-deconfiguration.txt b/doc/obsolete/auto-deconfiguration.txt similarity index 100% rename from doc/auto-deconfiguration.txt rename to doc/obsolete/auto-deconfiguration.txt diff --git a/doc/dependency-ordering.txt b/doc/obsolete/dependency-ordering.txt similarity index 100% rename from doc/dependency-ordering.txt rename to doc/obsolete/dependency-ordering.txt diff --git a/doc/descriptions.txt b/doc/obsolete/descriptions.txt similarity index 100% rename from doc/descriptions.txt rename to doc/obsolete/descriptions.txt diff --git a/doc/disappear-replace.txt b/doc/obsolete/disappear-replace.txt similarity index 100% rename from doc/disappear-replace.txt rename to doc/obsolete/disappear-replace.txt diff --git a/doc/diversions.text b/doc/obsolete/diversions.text similarity index 100% rename from doc/diversions.text rename to doc/obsolete/diversions.text diff --git a/doc/dpkg.texi b/doc/obsolete/dpkg.texi similarity index 100% rename from doc/dpkg.texi rename to doc/obsolete/dpkg.texi diff --git a/doc/dselect-methods.txt b/doc/obsolete/dselect-methods.txt similarity index 100% rename from doc/dselect-methods.txt rename to doc/obsolete/dselect-methods.txt diff --git a/doc/essential-flag.txt b/doc/obsolete/essential-flag.txt similarity index 100% rename from doc/essential-flag.txt rename to doc/obsolete/essential-flag.txt diff --git a/doc/guidelines.texi b/doc/obsolete/guidelines.texi similarity index 100% rename from doc/guidelines.texi rename to doc/obsolete/guidelines.texi diff --git a/doc/maintainer-script-args.txt b/doc/obsolete/maintainer-script-args.txt similarity index 100% rename from doc/maintainer-script-args.txt rename to doc/obsolete/maintainer-script-args.txt diff --git a/doc/upgrades+errors.txt b/doc/obsolete/upgrades+errors.txt similarity index 100% rename from doc/upgrades+errors.txt rename to doc/obsolete/upgrades+errors.txt diff --git a/doc/version-ordering.txt b/doc/obsolete/version-ordering.txt similarity index 100% rename from doc/version-ordering.txt rename to doc/obsolete/version-ordering.txt diff --git a/doc/virtual-dependencies.txt b/doc/obsolete/virtual-dependencies.txt similarity index 100% rename from doc/virtual-dependencies.txt rename to doc/obsolete/virtual-dependencies.txt diff --git a/doc/policy.sgml b/doc/policy.sgml new file mode 100644 index 00000000..e15c9394 --- /dev/null +++ b/doc/policy.sgml @@ -0,0 +1,1222 @@ + + + + + + +Debian policy manual +<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ +<version>version 0.1, <date> + +<abstract> +This manual describes the policy requirements which must be satisfied +for a package to be included in the Debian distribution. This +includes details of the permissions and ownerships of files in +packages and other technical requirements as well as information like +the upload procedure. +</abstract> + +<copyright>Copyright ©1996 Ian Jackson. +<p> + +This manual is free software; you may redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2, or (at your option) any +later version. +<p> + +This is distributed in the hope that it will be useful, but +<em>without any warranty</em>; without even the implied warranty of +merchantability or fitness for a particular purpose. See the GNU +General Public License for more details. +<p> + +You should have received a copy of the GNU General Public License with +your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or +with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>. If +not, write to the Free Software Foundation, Inc., 675 Mass Ave, +Cambridge, MA 02139, USA. + +<toc sect> + +<chapt id="scope">Introduction and scope of this manual +<p> + +This manual describes the criteria that a Debian-format package must +satisfy to be included in the Debian distribution. +<p> + +Much of this information will be useful even when building a package +which is to be distributed in some other way or is for local use. +<p> + +This manual does <em/not/ describe the technical mechanisms involved +in package creation, installation and removal. This information can +be found in the <prgn/dpkg/ programmers' manual and the <prgn/dpkg/ system +administrators' manual. +<p> + +This document assumes familiarity with these other two manuals. +<p> + +The Debian version of the FSF's GNU <prgn/hello/ program is provided +as an example for people wishing to create Debian packages. +<p> + +<em>Note that this document is still a draft!</em> + +<chapt id="pkgcopyright">Package copyright +<p> + +Please study the copyright of your submission <em/carefully/ and +understand it before proceeding. If you have doubts or questions, +please ask. +<p> + +All packages in the Debian distribution proper must be freely useable, +modifiable and redistributable in both source and binary form. It +must be possible for anyone to distribute and use modified source code +and their own own compiled binaries, at least when they do so as part +of a Debian distribution. +<p> + +Packages whose copyright permission notices (or patent problems) do +not allow distribution and copying for profit, without restriction on +the amount charged, or where distribution is restricted according to +the medium used, or where the distributor must ask any kind of special +permission of the authors, or with other onerous conditions, may only +be placed in the semi-supported non-free section of the Debian FTP +archives. This is important so that CDROM manufacturers can +distribute Debian without having to check the copyright of each +package individually, simply by leaving out the contents of the +non-free area; CDROM distributors are encouraged, though, to check the +copyrights on programs in non-free individually and include as many as +they can. +<p> + +Packages whose copyright permission notices (or patent problems) allow +only distribution of compiled binaries (and thus of which only +binaries are available), or where the source code which may be +distributed is not the complete source code required to compile the +program (ie, the program cannot be compiled using only packages in the +main Debian distribution), or which depend for their use on non-free +or contrib packages, or allow free use only for a trial period +(shareware), or are demonstration programs lacking vital functionality +(crippleware), or are only installer-packages which require the user +to supply a separate file to be installed, or which fail to meet some +other policy requirements, may only be placed in the semi-supported +contrib section of the Debian FTP archives (unless they need to be in +non-free - see above). +<p> + +Programs whose authors encourage the user to make donations are fine +for the main distribution, provided that the authors do not claim that +not donating is immoral, unethical, illegal or something similar; +otherwise they must go in contrib (or non-free, if even distribution +is restricted by such statements). +<p> + +Packages whose copyright permission notices (or patent problems) do +not allow redistribution even of only binaries, and where no special +permission has been obtained, cannot placed on the Debian FTP site and +its mirrors at all. +<p> + +Note that under international copyright law<footnote>This applies in +the United States, too.</footnote> <em/no/ distribution or modification +of a work is allowed without an explicit notice saying so. Therefore +a program without a copyright notice <em/is/ copyrighted and you may +not do anything to it without risking being sued! Likewise if a +program has a copyright notice but no statement saying what is +permitted then nothing is permitted. +<p> + +Many authors are unaware of the problems that restrictive copyrights +(or lack of copyright notices) can cause for the users of their +supposedly-free software. It is often worthwhile contacting such +authors diplomatically to ask them to modify their terms generally, or +specially for Debian. However, this is a politically difficult thing +to do and you should ask for advice on <prgn/debian-devel/ first. +<p> + +When in doubt, send mail to <email/debian-devel@lists.debian.org/. Be +prepared to provide us with the copyright statement. Software covered +by the GPL, public domain software and BSD-like copyrights are safe; +be wary of the phrases `commercial use prohibited' and `distribution +restricted'. +<p> + +Every package submission <em/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 by the binary package - see <ref +id="copyrightfile">. + +<chapt id="binarypkg">Contents of the binary package + +<sect>Control file requirements + +<sect1><tt/Maintainer/ information +<p> + +All packages must have a <tt/Maintainer/ field with the correct name +and a working email address for the Debian maintainer of the package. +If one person maintains several packages they should try to avoid +having different forms of their name and address in different +<tt/Maintainer/ fields. + +<sect1>Dependencies and virtual packages +<p> + +Add a dependency for any shared libraries required by +dynamically-linked executable binaries in your package. Almost every +package containing compiled C code should therefore include a +<tt/Depends/ field which mentions the shared C library required for +the program to run. For ELF binaries linked against <tt/libc.so.5/ +the relevant package name is <tt/libc5/. +<p> + +All packages must use virtual package names where appropriate, and +arrange to create new ones if necessary. They must not use virtual +package names (except privately, amongst a cooperating group of +packages) unless they have been agreed upon and appear in the list of +virtual package names. +<p> + +The latest version of the authoritative list of virtual package names +can be found on <ftpsite>ftp.debian.org</> in +<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</> +or your local mirror. The procedure for updating it is described at +the top of the file. + +<sect1><tt/Section/ and <tt/Priority/ +<p> + +Decide whether your package can go in <tt/non-free/, <tt/contrib/ or +the main distribution - see <ref id="pkgcopyright">, and put +an appropriate value for the distribution in the +<tt>debian/changelog</> file. +<p> + +The <tt/Priority/ and <tt/Section/ control file fields give +information for classifying the package in <prgn/dselect/ and say +which directory to place it in the FTP archive. +<p> + +They are ultimately the responsibility of the distribution +maintainers; however, you should suggest values for them in your +<tt/.changes/ information when you upload a package. You do this by +including appropriate information in the <tt>debian/control</tt> file +before building the packages. +<p> + +For a list of the currently in-use sections, please see the FTP +archive. Packages in the non-free and contrib areas should have +section <tt/non-free/ and <tt/contrib/, respectively. + +<sect2><tt/Priority/ values +<p> + +<taglist> +<tag><tt/required/ +<item> +<tt/required/ packages are necessary for the proper functioning of the +system. You must not remove these packages or your system may become +totally broken and you may probably not even be able to use +<prgn/dpkg/ to put things back. Systems with only the <tt/required/ +packages are probably unuseable, but they do have enough functionality +to allow the sysadmin to boot and install more software. + +<tag><tt/important/ +<item> +Important programs, including those which one would expect to find on +any Unix-like system. If the expectation is that an experienced Unix +person who found it missing would go `What the F*!@<+ is going on, +where is <prgn/foo/', it should be in <tt/important/. This is an +important criterion because we are trying to produce, amongst other +things, a free Unix. Other packages without which the system will not +run well or be useable should also be here. This does <em/not/ +include Emacs or X11 or TeX or any other large applications. The +<tt/important/ packages are just a bare minimum of commonly-expected +and necessary tools. + +<tag><tt/standard/ +<item> +These packages provide a reasonably small but not too limited +character-mode system. This is what will install by default if the +user doesn't select anything else. It doesn't include many large +applications, but it does include Emacs (this is more of a piece of +infrastructure than an application) and a reasonable subset of TeX and +LaTeX (if this is possible without X). + +<tag><tt/optional/<footnote>In a sense everything is optional that +isn't required, but that's not what is meant here.</footnote> +<item> +This is all the software that you might reasonably want to install if +you didn't know what it was or don't have specialised requirements. +This is a much larger system and includes X11, a full TeX +distribution, and lots of applications. + +<tag><tt/extra/ +<item> +This contains packages that conflict with others with higher +priorities, or are only likely to be useful if you already know what +they are or have specialised requirements. + +</taglist> +<p> + +Priority values are not case-sensitive. + +<sect2>Base packages +<p> + +Some packages have <tt/Section: base/ and are in the <tt/base/ +subdirectory on the FTP archives. These are the packages that are +supplied on the base disks. They are the minimum sensible set for +installing new packages (perhaps via a network). +<p> + +Most of these packages should have <tt/Priority: required/ or at least +<tt/Priority: important/. + +<sect1>The <tt/Essential/ flag +<p> + +The <tt/Essential: yes/ control file field should not be used unless +removing a package really will completely hose the system; nor should +it be used for a shared library package - the dependencies will +prevent its premature removal, and we need to be able to remove it +when it has been superseded. + +<sect1>Including <tt/Priority/ and <tt/Section/ in the <tt/.deb/ +control file +<p> + +If a user installs a package which is not part of the standard +distribution, or without downloading and updating from a new +<prgn/Packages/ file, the information about the priority and section +of a package will be absent, and the <prgn/dselect/ package listing +will have the package listed under `unclassified'. In order to +improve this it is permissible to use the <tt/-is/, <tt/-isp/ or +<tt/-ip/ option to <prgn/dpkg-gencontrol/, so that the <tt/Section/ +and/or <tt/Priority/ is copied into the actual control information in +the <tt/.deb/ file. However, if you do this you should make sure you +keep the information up to date so that users are not shown +conflicting information. + + +<sect1>Formatting of the <tt/Description/ control file field +<p> + +Every Debian package should have an extended description. +<p> + +The description should be written so that it tells the user what they +need to know to decide whether to install the package. This +description should not just be copied from the blurb for the program. +Instructions for configuring or using the package should not be +included - that is what installation scripts, manpages, Info files and +<tt>/usr/doc/<var/package/</> are for. Copyright statements and other +administrivia should not be included - that is what +<tt>/usr/doc/copyright</> is for. +<p> + +If you wish to include a list in your extended with entries which are +a line or more each you must indent each entry by one space to make +sure that it doesn't get wordwrapped. The start of each list entry +should be marked with an asterisk, followed by a single space. You +must wrap the list entries yourself to 75 columns, and should start +continuation lines indented by three spaces so that they line up with +the start of the text on the first line of each list entry. +<p> + +See the programmers' manual for further requirements and pitfalls. + +<sect>Locations of files +<p> + +The location of all installed files and directories must comply fully +with the Linux File System Standard (FSSTND). The latest version of +this document can be found alongside this manual or on +<ftpsite/tsx-11.mit.edu/ in +<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>. Specific questions +about following the standard may be asked on <prgn/debian-devel/, or +referred to Daniel Quinlan, the FSSTND coordinator, at +<email/quinlan@yggdrasil.com/. +<p> + +<sect1>Manpages +<p> + +You must install manpages in <prgn/nroff/ source form, in appropriate +places under <tt>/usr/man</tt>. You should only use sections 1 to 9 +(see the FSSTND for more details). You must <em/not/ install a +preformatted `cat page'. +<p> + +If no manual page is available for a particular program, utility or +function and this is reported as a bug on debian-bugs, a symbolic link +from the requested manual page to the <manref name=undocumented +section=7> manual page should be provided. This symbolic link can be +created from <tt>debian/rules</> like this: +<example> +ln -s ../man7/undocumented.7 \ + debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9] +</example> +This manpage claims that the lack of a manpage has been reported as a +bug, so you may only do this if it really has (you can report it +yourself, if you like). Do not close the bug report until a proper +manpage is available. +<p> + +You may forward a complaint about a missing manpage to the upstream +authors, and mark the bug as forwarded in the Debian bug tracking +system. Even though the GNU Project do not in general consider the +lack of a manpage to be a bug, we do - if they tell you that they +don't consider it a bug you should leave the bug in our bug tracking +system open anyway. +<p> + +Manpages should be installed uncompressed. +<p> + +If one manpage needs to be accesssible via several names it is better +to use a symbolic link than the <tt/.so/ feature, but there is no need +to fiddle with the relevant parts of the upstream source to change +from <tt/.so/ to symlinks - don't do it unless it's easy. Do not +create hard links in the manual page directories, and do not put +absolute filenames in <tt/.so/ directives. The filename in a +<tt/.so/ in a manpage should be relative to the base of the manpage +tree (usually <tt>/usr/man</tt>). + +<sect1>Info documents +<p> + +Info documents should be installed in <tt>/usr/info</tt>. They should +be compressed with <tt/gzip -9/. +<p> + +Your package must call <prgn/install-info/ to update the Info <tt/dir/ +file, in its post-installation script: +<example> +install-info --quiet --section Development Development \ + /usr/info/foobar.info +</example> +<p> + +It is a good idea to specify a section for the location of your +program; this is done with the <tt/--section/ switch. To determine +which section to use, you should use look at <tt>/usr/info/dir</> on +your system and choose the most relevant (or create a new section if +none of the current sections are relevant). Note that the +<tt/--section/ flag takes two arguments; the first is a regular +expression to match (case-insensitively) against an existing section, +the second is used when creating a new one. +<p> + +You must remove the entries in the pre-removal script: +<example> +install-info --quiet --remove /usr/info/foobar.info +</example> +<p> + +If <prgn/install-info/ cannot find a description entry in the Info file +you will have to supply one. See <manref name=install-info section=8> +for details. + +<sect1>Additional documentation +<p> + +Any additional documentation that comes with the package can be +installed at the discretion of the package maintainer. Text +documentation should be installed in a directory +<tt>/usr/doc/<var/package/</tt><footnote>Where <var/package/ is the +name of the package.</footnote> and compressed with <tt/gzip -9/ +unless it is small. +<p> + +If a package comes with large amounts of documentation which many +users of the package will not require you should create a separate +binary package to contain it, so that it does not take up disk space +on the machines of users who do not need or want it installed. +<p> + +It is often a good idea to put text information files that come with +the source package in <tt>/usr/doc/<var/package/</> in the binary +package. However, don't install the instructions for building and +installing the package, of course! + +<sect1>Preferred documentation formats +<p> + +The unification of Debian documentation is being carried out via HTML. +<p> + +If your package comes with extensive documentation in a markup format +that can be converted to various other formats you should if possible +ship HTML versions in the binary package, in the directory +<tt>/usr/doc/<var/package/</> or its subdirectories. +<p> + +Other formats such as PostScript may be provided at your option. + +<sect2>Examples +<p> + +Any examples (configurations, source files, whatever), should be +installed in a directory <tt>/usr/doc/<var/package//examples</tt>. +These files should not be referenced by any program - they're there +for the benefit of the system administrator and users, as +documentation only. + +<sect1 id="copyrightfile"><tt>/usr/doc/copyright/<var/package/</tt> +<p> + +This file must contain details of the authorship and copyright of the +package. It must say where the upstream sources (if any) were +obtained, and explain briefly what modifications were made in the +Debian version of the package compared to the upstream one. It must +name the original authors of the package and the Debian maintainer(s) +who were involved with its creation. +<p> + +It must contain the full text of the copyright notice and any +acknowledgements for the program and the licence terms under which the +program is distributed. If the package is distributed under the GNU +General Public Licence, the GNU Library General Public Licence, the +Regents of the University of California at Berkeley (BSD) licence or +Larry Wall's Artistic Licence please say so instead of including a +copy of the licence. The files <tt/BSD/, <tt/GPL/, <tt/LGPL/ and +<tt/Artistic/ are be available in <tt>/usr/doc/copyright</tt> for you +to refer to. The package's copyright file should not be compressed. +<p> + +Do not use the copyright file as a general <tt/README/ file. If your +package has such a file it should be installed in +<tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some +other appropriate place. Do not make links between +<tt>/usr/doc/<var/package/</> and the <tt/copyright/ directory. + +<sect1>Symbolic links +<p> + +Most 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). +<p> + +In particular, symlinks from one part of <tt>/usr</tt> to another +should be relative. +<p> + +In certain cases, however, relative links may cause more problems. +For example, links into <tt>/etc</tt> and <tt>/var</tt> should be +absolute. +<p> + +Note that when creating a relative link using <prgn/ln/ it is not +necessary for the target of the link to exist relative to the working +directory you're running <prgn/ln/ from; nor is it necessary to change +directory to the directory where the link is to be made. Simply +include the string that should appear as the target of the link (this +will be a pathname relative to the directory in which the link +resides) as the first argument to <prgn/ln/. +<p> + +For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things +like: +<example> +ln -fs gcc $(prefix)/bin/cc +ln -fs gcc debian/tmp/usr/bin/cc +ln -fs ../sbin/sendmail $(prefix)/bin/runq +ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq +</example> + +<sect1>Logfiles +<p> + +Logfiles should usually be named +<tt>/var/log/<var/package/.log</tt>. If you have many logfiles, +or need a separate directory for permissions reasons +(<tt>/var/log</tt> is writeable only by <tt/root/), you should usually +create a directory named <tt>/var/log/<var/package/</tt>. +<p> + +Make sure that any logfiles are rotated occasionally using so that +they don't grow indefinitely; the best way to do this is to use +<prgn/savelog/ program in an <tt>/etc/cron.daily</>, +<tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script. +<p> + +Make sure that any logfiles are removed when the package is purged +(but not when it is only removed), by checking the argument to the +postrm script (see the programmer's manual for details). + +<sect1><tt>/usr/local</> - for the use of the system administrator +<p> + +As mandated by the FSSTND no package should place any files in +<tt>/usr/local</>, either by putting them in the filesystem archive to +be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer +scripts. +<p> + +Every package that searches a number of directories or files for +something (for example, looking for shared libraries in <tt>/lib</> or +<tt>/usr/lib</>) should search an appropriate directory in +<tt>/usr/local</> too. +<p> + +In order that the system administrator may know where to place +additional files a package should create an empty directory in the +appropriate place in <tt>/usr/local</> by supplying it in the +filesystem archive for unpacking by <prgn/dpkg/. The +<tt>/usr/local</> directory itself and all the subdirectories created +by the package should have permissions 2775 (group-writeable and +set-group-id) and be owned by <tt/root.staff/. +<p> + +In the future it will be possible to tell <prgn/dpkg/ not to unpack +files matching certain patterns, so that system administrators who do +not wish these directories in <tt>/usr/local</> do not need to have +them. + +<sect>Permissions and ownerships +<p> + +The rules in this section are guidelines for general use. If +necessary you may deviate from the details below. However, if you do +so you must make sure that what is done is secure and you must try to +be as consistent as possible with the rest of the system. You should +probably also discuss it on <prgn/debian-devel/ first. +<p> + +Files should be owned by <tt/root.root/, and made writeable only by +the owner and universally readable (and executable, if appropriate). +<p> + +Directories should be mode 755 or (for group-writability) mode 2775. +The ownership of the directory should be consistent with its mode - +if a directory is mode 2775, it should be owned by the group that +needs write access to it. +<p> + +Setuid and setgid executables should be mode 4755 or 2755 +respectively, and owned by the appropriate user or group. They should +not be made unreadable (modes like 4711 or 2711 or even 4111); doing +so achieves no extra security, because anyone can find the binary in +the freely available Debian package - it is merely inconvenient. For +the same reason you should not restrict read or execute permissions on +non-set-id executables. +<p> + +Some setuid programs need to be restricted to particular sets of +users, using file permissions. In this case they should be owned by +the uid to which they are set-id, and by the group which should be +allowed to execute them. They should have mode 4754; there is no +point in making them unreadable to those users who must not be allowed +to execute them. +<p> + +Do not arrange that the system administrator can only reconfigure the +package to correspond to their local security policy by changing the +permissions on a binary. Ordinary files installed by <prgn/dpkg/ (as +opposed to conffiles and other similar objects) have their permissions +reset to the distributed permissions when the package is reinstalled. +Instead you should consider (for example) creating a group for people +allowed to use the program(s) and making any setuid executables +executable only by that group. +<p> + +Shared libraries should be installed executable. + +<sect>Configuration files +<p> + +Any configuration files created or used by your package should reside +in <tt>/etc</tt>. If there are several you should consider creating a +subdirectory named after your package. +<p> + +It is almost certain that any file in <tt>/etc</tt> that is in your +package's filesystem archive should be listed in <prgn/dpkg/'s +<tt/conffiles/ control area file. (See the <prgn/dpkg/ programmers' +manual). + +<sect>Maintainer scripts +<p> + +The package installation scripts should avoid producing output which +it is unnecessary for the user to see and should rely on <prgn/dpkg/ to +stave off boredom on the part of a user installing many packages. +This means, amongst other things, using the <tt/--quiet/ option on +<prgn/install-info/. +<p> + +Packages should try to minimise the amount of prompting they need to +do, and they should ensure that the user will only every be asked each +question once. This means that packages should try to use appropriate +shared configuration files (such as <tt>/etc/papersize</> and +<tt>/etc/news/server</>, rather than each prompting for their own +list of required pieces of information. +<p> + +It also means that an upgrade should not ask the same questions again, +unless the user has used <tt/dpkg --purge/ to remove the package's +configuration. The answers to configuration questions should be +stored in an appropriate place in <tt>/etc</> so that the user can +modify them, and how this has been done should be documented. +<p> + +If a package has a vitally important piece of information to pass to +the user (such as "don't run me as I am, you must edit the following +configuration files first or you risk your system emitting +badly-formatted messages"), it should display this in the +<prgn/postinst/ script and prompt the user to hit return to +acknowledge the message. Copyright messages do not count as vitally +important (they belong in <tt>/usr/doc/copyright</>); neither do +instructions on how to use a program (these should be in on line +documentation, where all the users can see them). +<p> + +Any necessary prompting should almost always be confined to the +post-installation script, and should be protected with a conditional +so that unnecssary prompting doesn't happen if a package's +installation fails and the <prgn/postinst/ is called with +<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/. +<p> + +Errors which occur during the execution of an installation script +<em/must/ be checked and the installation <em/must not/ continue after +an error. +<p> + +The section below on scripts in general applies to package maintainer +scripts too. + +<sect>Scripts in general +<p> + +All command scripts, including the package maintainer scripts inside +the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming +the shell to be used to interpret them. +<p> + +In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>. +<p> + +Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly +start with <tt>set -e</> so that errors are detected. Every script +<em/must/ use <tt/set -e/ or check the exit status of <em/every/ +command. +<p> + +Perl scripts should check for errors when making any system calls, +including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and +<tt/system/. +<p> + +<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages. See +Csh Programming Considered Harmful, one of the <tt/comp.unix.*/ FAQs. +If an upstream package comes with <prgn/csh/ scripts then you must make +sure that they start with <tt>#!/bin/csh</tt> and make your package +depend on <prgn/csh/. +<p> + +<sect>Compilation options +<p> + +Generally the following compilation parameters should be used: +<example> +CC = gcc +CFLAGS = -O2 -g -Wall # sane warning options vary between programs +LDFLAGS = # none +install -s # (or use strip on the files in debian/tmp) +</example> +<p> + +Note that all installed binaries should be stripped, either by using +the <tt/-s/ flag to <prgn/install/, or by calling <prgn/strip/ on the +binaries after they have been copied into <tt>debian/tmp</> but +before the tree is made into a package. +<p> + +Make sure that you do not link with <tt/-g/, as this makes a.out +compilers produce huge statically linked binaries. The <tt/-g/ flag +is useful on compilation so that you have available a full set of +debugging symbols in your built source tree, in case anyone should +file a bug report involving (for example) a core dump. +<p> + +The <tt/-N/ flag should not be used. On a.out systems it may have +been useful for some very small binaries, but for ELF it has no good +effect. +<p> + +It is up to the package maintainer to decide what compilation options +are best for the package. Certain binaries (such as +computationally-intensive programs) may function better with certain +flags (<tt/-O3/, for example); feel free to use them. Please use good +judgment here. Don't use flags for the sake of it; only use them if +there is good reason to do so. Feel free to override the upstream +author's ideas about which compilation options are best - they are +often inappropriate for our environment. +<p> + +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. + +<sect>Shared library packages +<p> + +Packages involving shared libraries should be split up into several +binary packages. +<p> + +For a straightforward library which has a development environment and +a runtime kit including just shared libraries you need to create two +packages: <tt/<var/libraryname/<var/soname//<footnote><var/soname/ is +the shared object name of the shared library - it's the thing that has +to match exactly between building an executable and running it for the +dynamic linker to be able run the program. Usually the <var/soname/ +is the major number of the library.</footnote> and +<tt/<var/libraryname/<var/soname/-dev/. +<p> + +If you prefer only to support one development version time you may +name the development package <tt/<var/libraryname/-dev/; otherwise you +may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that the +user only installs one development version at a time (after all, +different development versions are likely to have the same header +files in them, causing a filename clash if both are installed). +Typically the development version will also need an exact version +dependency on the runtime library, to make sure that compilation and +linking happens correctly. +<p> + +Packages which use the shared library should have a dependency on the +name of the shared library package, +<tt/<var/libraryname/<var/soname//. When the <var/soname/ changes you +can have both versions of the library installed while moving from the +old library to the new. +<p> + +If your package has some run-time support programs which use the +shared library you must <em/not/ put them in the shared library +package. If you do that then you won't be able to install several +versions of the shared library without getting filename clashes. +Instead, either create a third package for the runtime binaries (this +package might typically be named <tt/<var/libraryname/-runtime/ - note +the absence of the <var/soname/ in the package name) or if the +development package is small include them in there. +<p> + +If you have several shared libraries built from the same source tree +you can lump them all togther into a single shared library package, +provided that you change all their <var/soname/s at once (so that you +don't get filename clashes if you try to install different versions of +the combined shared libraries package). +<p> + +Follow the directions in the <prgn/dpkg/ programmers' manual for +putting the shared library in its package. + +<sect>Application configuration files, dotfiles and <tt>/etc/skel</> +<p> + +Files in <tt>/etc/skel</> will automatically be copied into new user +accounts by <prgn/adduser/. They should not be referenced there by +any program. +<p> + +Therefore, if a program needs a dotfile to exist in advance in +<tt/$HOME/ to work sensibly that dotfile should be installed in +<tt>/etc/skel</> (and listed in conffiles, if it is not generated and +modified dynamically by the package's installation scripts). +<p> + +However, programs that require dotfiles in order to operate sensibly +(dotfiles that they do not create themselves automatically, that is) +are a bad thing, and programs should be configured by the Debian +default installation as close to normal as possible. +<p> + +Therefore, if a program in a Debian package needs to be configured in +some way in order to operate sensibly that configuration should be +done in a site-wide global configuration file elsewhere in +<tt>/etc</>. Only if the program doesn't support a site-wide default +configuration and the package maintainer doesn't have time to add it +should a default per-user file be placed in <tt>/etc/skel</>. +<p> + +<tt>/etc/skel</> should be as empty as we can make it. This is +particularly true because there is no easy mechanism for ensuring that +the appropriate dotfiles are copied into the accounts of existing +users when a package is installed. +<p> + +Ideally the sysadmin should ideally not have to do any configuration +other than that done (semi-)automatically by the postinst script. + +<sect id="mail">Mail processing on Debian systems +<p> + +Debian packages which process electronic mail, whether +mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/ +make sure that they are compatible with the configuration decisions +below. Failure to do this may result in lost mail, broken <tt/From:/ +lines, and other serious brain damage! +<p> + +The mail spool is <tt>/var/spool/mail</> and the interface to send a +mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND). The +mail spool is part of the base system and not part of the MTA package. +<p> + +Mailboxes are locked using the <tt/<var/username/.lock/ lockfile +convention, rather than <prgn/fcntl/, <prgn/flock/ or <prgn/lockf/. +<p> + +Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has +chosen otherwise. A MUA may remove a mailbox (unless it has +nonstandard permissions) in which case the MTA or another MUA must +recreate it if needed. Mailboxes must be writeable by group mail. +<p> + +The mail spool is 2775 <tt/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). +<p> + +<tt>/etc/aliases</> is the source file for the system mail aliases +(e.g. postmaster, usenet, etc.) - it is the one which the sysadmin +and postinst scripts may edit. After <tt>/etc/aliases</> is edited +the program or human editing it must call <prgn/newaliases/. All MTA +packages should come with a <prgn/newaliases/ program, even if it does +nothing, but older MTA packages do not do this so programs should not +fail if <prgn/newaliases/ cannot be found. +<p> + +The convention of writing <tt/forward to <var/address// in the mailbox +itself is not supported. Use a <tt/.forward/ file instead. +<p> + +The location for the <prgn/rmail/ program used by UUCP for incoming +mail is <tt>/usr/sbin/rmail</>, as per the FSSTND. Likewise, +<prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in +<tt>/usr/sbin/rsmtp</> if it is supported. +<p> + +Smail is not using HoneyDanBer UUCP, whose <prgn/uux/ apparently +accepts <tt/-a/ and <tt/-g/ options. +<p> + +If you need to know what name to use (for example) on outgoing news +and mail messages which are generated locally, you should use the file +<tt>/etc/mailname</>. It will contain the portion after the username +and <tt/@/ (at) sign for email addresses of users on the machine +(followed by a newline). +<p> + +A package should check for the existence of this file. If it exists +it should use it without comment.<footnote>An MTA's prompting +configuration script may wish to prompt the user even if it finds this +file exists.</footnote> If it does not exist it should prompt the user +for the value and store it in <tt>/etc/mailname</> as well as using it +in the package's configuration. The prompt should make it clear that +the name will not just be used by that package. E.g., in this +situation the INN package says: +<example> +Please enter the `mail name' of your system. This is the hostname +portion of the address to be shown on outgoing news and mail messages. +The default is <var/syshostname/, your system's host name. +Mail name [`<var/syshostname/']: +</example> +where <var/syshostname/ is the output of <tt/hostname -fqdn/. + + +<sect>Packages which can use the X shared libraries +<p> + +Some programs can be configured with or without support for X Windows. +Typically these binaries produced when configured for X will need the +X shared libraries to run. +<p> + +Such programs should be configured <em/with/ X support, and should +declare a dependency on <tt/elf-x11r6lib/ (for the X11R6 libraries). +Users who wish to use the program can install just the relatively +small <tt/xlib/ package, and do not need to install the whole of X. +<p> + +Do not create two versions (one with X support and one without) of +your package. + + +<sect>Games +<p> + +The permissions on /var/lib/games are 755 <tt/root.root/. +<p> + +Each game decides on its own security policy. +<p> + +Games which require protected, privileged access to high-score files, +savegames, &c, must be made set-<em/group/-id (mode 2755) and +owned by <tt/root.games/, and use files and directories with +appropriate permissions (770 <tt/root.games/, for example). They must +<em/not/ be made set-<em/user/-id, as this causes security +problems.<footnote>If an attacker can subvert any set-user-id game +they can overwrite the executable of any other, causing other players +of these cames to run a trojan. With a set-group-id game the attacker +only gets access to less important game data, and if they can get at +the other players' accounts at all it will take considerably more +effort.</footnote> +<p> + +Some packages, for example some fortune cookie programs, are +configured by the upstream authors to install with their data files or +other static information made unreadable so that they can only be +accessed through set-id programs provided. Do not do this in a Debian +package: anyone can download the <tt/.deb/ file and read the data from +it, so there is no point making the files unreadable. Not making the +files unreadable also means that you don't have to make so many +programs set-id, which reduces the risk of a security hole. + +<sect>Allocating package-specific users and groups +<p> + +If you need to create a new user or group for your package there are +two possibilities. Firstly, you may need to make some files in the +binary package be owned by this user or group, or you may need to +compile the user or group id (rather than just the name) into the +binary (though this latter should be avoided if possible). In this +case you need a statically allocated id. +<p> + +You must ask for a user or group id from the base system maintainer, +and must not release the package until you have been allocated one. +Once you have been allocated one you must make the package depend +on a version of the base system with the id present in +<tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or alternatively arrange +for your package to create the user or group itself with the correct +id (using <tt/adduser/) in its pre- or post-installation script (the +latter is to be preferred if it is possible). +<p> + +On the other hand, the program may able to determine the uid or gid +from the group name at runtime, so that a dynamic id can be used. In +this case you must choose an appropriate user or group name, +discussing this on <prgn/debian-devel/ and checking with the base system +maintainer that it is unique and that they do not wish you to use a +statically allocated id instead. When this has been checked you must +arrange for your package to create the user or group if necessary +using <prgn/adduser/ in the pre- or post-installation script (again, the +latter is to be preferred if it is possible). +<p> + +Note that changing the numeric value of an id associated with a name +is very difficult, and involves searching the filesystem for all +appropriate files. You need to think carefully whether a static or +dynamic id is required, since changing your mind later will cause +problems. + +<chapt id="sourcepkg">Source package + +<sect>Documentation and the <tt/changelog/ +<p> + +Document your changes and updates to the source package properly in +the <tt>debian/changelog</tt> file. +<p> + +A copy of the file which will be installed in +<tt>/usr/doc/copyright/<var/package/</tt> should be in +<tt>debian/copyright</tt>. +<p> + +In non-experimental packages you may only use a format for +<tt>debian/changelog</> which is supported by the most recent released +version of <prgn/dpkg/. If your format is not supported and there is +general support for it you should contact the <prgn/dpkg/ maintainer +to have the parser script for your format included in the <prgn/dpkg/ +package.<footnote>You will need to agree that the parser and its +manpage may be distributed under the GNU GPL, just as the rest of +<prgn/dpkg/ is.</footnote> + +<sect>Changes to the upstream sources +<p> + +If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/ +scripts are used, you should edit the <tt/.in/ files rather than +editing the <prgn/Makefile/ directly. This allows the user to +reconfigure the package if necessary. You should <em/not/ configure +the package and edit the generated <prgn/Makefile/! This makes it +impossible for someone else to later reconfigure the package. +<p> + +If changes to the source code are made that are generally applicable +please try to get them included in the upstream version of the package +by supplying the upstream authors with the changes in whatever form +they prefer. +<p> + +If you need to configure the package differently for Debian or for +Linux, and the upstream source doesn't provide a way to configure it +the way you need to, please add such configuration facilities (for +example, a new <prgn/autoconf/ test or <tt/#define/) and send the +patch to the upstream authors, with the default set to the way they +originally had it. You can then easily override the default in your +<tt>debian/rules</tt> or wherever is appropriate. + +<sect>Error trapping in makefiles +<p> + +When <prgn/make/ invokes a command in a makefile (including your +package's upstream makefiles and the <tt>debian/rules</>) it does so +using <tt/sh/. This means that <tt/sh/'s usual bad error handling +properties apply: if you include a miniature script as one of the +commands in your makefile you'll find that if you don't do anything +about it then errors are not detected and <prgn/make/ will blithely +continue after problems. +<p> + +Every time you put more than one shell command (this includes using a +loop) in a makefile command you <em/must/ make sure that errors are +trapped. For simple compound commands, such as changing directory and +then running a program, using <tt/&&/ rather than semicolon as +a command separator is sufficient. For more complex commands +including most loops and conditionals you must include a separate +<tt/set -e/ command at the start of every makefile command that's +actually one of these miniature shellscripts. + +<sect>Permissions +<p> + +All the files in the source package should be world-readable and +user-writeable. Directories and executable programs should be +world-exectuable. None of the files should be world-writeable. The +files may or may not be group-writeable, and directories may or may +not be setgid. Pipes should not be world-readable and should be +either both group readable and writeable or neither (and they should +not be executable). +<p> + +In summary: data files may be <tt/664/, <tt/644/. Executable files +may be <tt/775/ or <tt/755/. Directories may be <tt/775/, <tt/755/, +<tt/2775/ or <tt/2755/. Pipes may be <tt/660/ or <tt/600/. + +<chapt id="developer">How to become a Debian developer + +<sect>Before you start work +<p> + +So, you've read all the documentation, you understand what everything +in the <prgn/hello/ example package is for, and you're about to +Debianise your favourite package. How do you actually become a Debian +developer so that your work can be incorporated into the Project? +<p> + +Firstly, subscribe to <prgn/debian-devel/ if you haven't already. +Send the word <tt/subscribe/ in the <em/Subject/ of a mail to +<email/debian-devel-REQUEST@lists.debian.org/. In case of problems +contact the list administrator, Anders Chrigstrom <email/ac@netg.se/. +<p> + +You should to subscribe and lurk for a bit before doing any coding, +and you should post about your intentions to work on something to +avoid duplicated effort. +<p> + +If you do not have a PGP key yet generate one. You should probably +read the PGP manual, as it has much important information which is +critical to its security. Many more security failures are due to +human error than to software failure or high-powered spy techniques. + +<sect>When you have a package to upload +<p> + +When you have your package ready to be uploaded you must send a +message to the project leader, Bruce Perens <email/bruce@pixar.com/, +the administrator of <tt/master.debian.org/, Simon Shapiro +<email/shimon@i-connect.net/, the mailing list administrator, Anders +Chrigstrom <email/ac@netg.se/ and the <prgn/dpkg/ maintainer, Ian +Jackson <email/ijackson@gnu.ai.mit.edu/. +<p> + +The message should say what you've done and who you are, and should +ask for an account on <prgn/master/ and to be subscribed to +<prgn/debian-private/ (the developers-only mailing list). It should +contain your PGP key (extracted using <tt/pgp -kxa/) for the database +of keys which is shipped with <prgn/dpkg/. + +When you have your personal account on <prgn/master/ log in and +transfer the files to +<tt>/home/Debian/ftp/private/project/Incoming</>. You cannot upload +to <prgn/Incoming/ on <prgn/master/ using anonymous FTP. +<p> + +You can also upload files to <prgn/Incoming/ via a <prgn/cron/-driven +upload queue in Europe on <ftpsite/chiark.chu.cam.ac.uk/. For details +connect to <prgn/chiark/ using anonymous FTP and read +<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>. + +<sect id="changesfiles">Upload handling - <tt/.changes/ files +<p> + +When a package is uploaded to the Debian FTP archive, it must be +accompanied by a <tt/.changes/ file which gives directions for its +handling. This is usually generated by <prgn/dpkg-genchanges/. +<p> + +This file is a control file with the following fields: +<list compact> +<item><tt/Format/ +<item><tt/Date/ +<item><tt/Source/ +<item><tt/Binary/ +<item><tt/Architecture/ +<item><tt/Version/ +<item><tt/Distribution/ +<item><tt/Urgency/ +<item><tt/Maintainer/ +<item><tt/Description/ +<item><tt/Changes/ +<item><tt/Files/ +</list> +<p> + +All of them are mandatory for a Debian upload. See the list of +control fields in the <prgn/dpkg/ programmers' manual for the contents +of these fields. + + +<chapt id="mailinglists">The Debian mailing lists +<p> + +The mailing list server is at <tt/lists.debian.org/. Mail +<tt/debian-<var/foo/-REQUEST@lists.debian.org/<footnote>where +<tt/debian-<var/foo// is the name of the list</footnote> with the word +<tt/subscribe/ in the Subject to subscribe or <tt/unsubscribe/ to +unsubscribe. +<p> + +When replying to messages on the mailing list, please do not send a +carbon copy (<tt/CC/ - this does not mean `courtesy copy') to the +original poster. Anyone who posts to a mailing list should read it to +see the responses. +<p> + +As ever on the net, please trim down the quoting of articles you're +replying to. + +</book> diff --git a/doc/programmer.sgml b/doc/programmer.sgml new file mode 100644 index 00000000..6360d245 --- /dev/null +++ b/doc/programmer.sgml @@ -0,0 +1,2990 @@ +<!doctype debiandoc system> + +<!-- + Debian Linux dpkg package installation tool. + programmers' manual. + Copyright (C)1996 Ian Jackson; released under the terms of the GNU + General Public License, version 2 or (at your option) any later. + --> + +<book> + +<title><prgn/dpkg/ programmers' manual +<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ +<version><date> + +<abstract> +This manual describes the technical aspects of creating Debian binary +and source packages. It also documents the interface between +<prgn/dselect/ and its access method scripts. It does not deal with +the Debian Project policy requirements, and it assumes familiarity +with <prgn/dpkg/'s functions from the system administrator's +perspective. + +<copyright>Copyright ©1996 Ian Jackson. +<p> + +This manual is free software; you may redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2, or (at your option) any +later version. +<p> + +This is distributed in the hope that it will be useful, but +<em>without any warranty</em>; without even the implied warranty of +merchantability or fitness for a particular purpose. See the GNU +General Public License for more details. +<p> + +You should have received a copy of the GNU General Public License with +your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or +with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>. If +not, write to the Free Software Foundation, Inc., 675 Mass Ave, +Cambridge, MA 02139, USA. + +<toc sect> + +<!-- Describes the technical interface between a package and dpkg. + +How to safely put shared libraries in a package. Details of dpkg's +handling of individual files. Sections on when to use which feature +(eg Replaces vs. Replaces/Conflicts vs. update-alternatives +vs. diversions) Cross-references to the policy document (see below) +where appropriate. Description of the interface between dselect and +its access methods. Hints on where to start with a new package (ie, +the hello package). What to do about file aliasing. + +file aliasing + +Manpages are required for: update-rc.d, diversions, +update-alternatives, install-info in a package. + +--> + +<chapt id="scope">Introduction and scope of this manual +<p> + +<prgn/dpkg/ is a suite of programs for creating binary package files +and installing and removing them on Unix systems.<footnote><prgn/dpkg/ +is targetted primarily at Debian GNU/Linux, but may work on or be +ported to other systems.</footnote> +<p> + +The binary packages are designed for the management of installed +executable programs (usually compiled binaries) and their associated +data, though source code examples and documentation are provided as +part of some packages. +<p> + +This manual describes the technical aspects of creating Debian binary +packages (<tt/.deb/ files). It documents the behaviour of the +package management programs <prgn/dpkg/, <prgn/dselect/ et al. and and the +way they interact with packages. +<p> + +It also documents the interaction between <prgn/dselect/'s core and the +access method scripts it uses to actually install the selected +packages, and describes how to create a new access method. +<p> + +This manual does not go into detail about the options and usage of the +package building and installation tools. It should therefore be read +in conjuction with those programs' manpages. +<p> + +The utility programs which are provided with <prgn/dpkg/ for managing +various system configuration and similar issues, such as +<prgn/update-rc.d/ and <prgn/install-info/, are not described in +detail here - please see their manpages. +<p> + +It does <em/not/ describe the policy requirements imposed on Debian +packages, such as the permissions on files and directories, +documentation requirements, upload procedure, and so on. You should +see the Debian packaging policy manual for these details. (Many of +them will probably turn out to be helpful even if you don't plan to +upload your package and make it available as part of the +distribution.) +<p> + +It is assumed that the reader is reasonably familiar with the +<prgn/dpkg/ System Administrators' manual. +<p> + +The Debian version of the FSF's GNU hello program is provided as an +example for people wishing to create Debian packages. +<p> + +<em>Note that this document is still a draft!</em> + +<chapt id="binarypkg">Binary packages +<p> + +The binary package has two main sections. The first part consists of +various control information files and scripts used by <prgn/dpkg/ when +installing and removing. See <ref id="controlarea">. +<p> + +The second part is an archive (currently a <prgn/tar/ archive) +containing files and directories to be installed. +<p> + +In the future binary packages may also contain other components, such +as checksums and digital signatures. + + +<sect id="bincreating">Creating package files - <prgn/dpkg-deb/ +<p> + +All manipulation of binary package files is done by <prgn/dpkg-deb/; +it's the only program that has knowledge of the format. +(<prgn/dpkg-deb/ may be invoked by calling <prgn/dpkg/, as <prgn/dpkg/ will +spot that the options requested are appropriate to <prgn/dpkg-deb/ and +invoke that instead with the same arguments.) +<p> + +In order to create a binary package you must make a directory tree +which contains all the files and directories you want to have in the +filesystem data part of the package. In Debian-format source packages +this directory is usually <tt>debian/tmp</tt>, relative to the top of +the package's source tree. +<p> + +They should have the locations (relative to the root of the directory +tree you're constructing) ownerships and permissions which you want +them to have on the system when they are installed. +<p> + +With current versions of <prgn/dpkg/ the uid/username and gid/groupname +mappings for the users and groups being used should be the same on the +system where the package is built and the one where it is installed. +<p> + +You need to add one special directory to the root of the miniature +filesystem tree you're creating: <prgn/DEBIAN/. It should contain the +control information files, notably the binary package control file +(see <ref id="controlfile">). +<p> + +The <prgn/DEBIAN/ directory will not appear in the filesystem archive of +the package, and so won't be installed by <prgn/dpkg/ when the package +is installed. +<p> + +When you've prepared the package, you should invoke: +<example> +dpkg --build <var/directory/ +</example> +<p> + +This will build the package in <tt/<var/directory/.deb/. +(<prgn/dpkg/ knows that <tt/--build/ is a <prgn/dpkg-deb/ option, so it +invokes <prgn/dpkg-deb/ with the same arguments to build the package.) +<p> + +See the manpage <manref name="dpkg-deb" section=8> for details of how +to examine the contents of this newly-created file. You may find the +output of following commands enlightening: +<example> +dpkg-deb --info <var/filename/.deb +dpkg-deb --contents <var/filename/.deb +</example> + +<sect id="controlarea">Package control information files +<p> + +The control information portion of a binary package is a collection of +files with names known to <prgn/dpkg/. It will treat the contents of +these files specially - some of them contain information used by +<prgn/dpkg/ when installing or removing the package; others are scripts +which the package maintainer wants <prgn/dpkg/ to run. +<p> + +It is possible to put other files in the package control area, but +this is not generally a good idea (though they will largely be +ignored). +<p> + +Here is a brief list of the control info files supported by <prgn/dpkg/ +and a summary of what they're used for. +<p> + +<taglist> +<tag><tt/control/ +<item> + +This is the key description file used by <prgn/dpkg/. It specifies the +package's name and version, gives its description for the user, states +its relationships with other packages, and so forth. +See <ref id="controlfile">. + +<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/ +<item> + +These are exectuable files (usually scripts) which <prgn/dpkg/ runs +during installation, upgrade and removal of packages. They allow the +package to deal with matters which are particular to that package or +require more complicated processing than that provided by <prgn/dpkg/. +Details of when and how they are called are in +<ref id="maintainerscripts">. +<p> + +It is very important to make these scripts itempotent.<footnote>That +means that if it runs successfully or fails and then you call it again +it doesn't bomb out, but just ensures that everything is the way it +ought to be.</footnote> This is so that if an error occurs, the user +interrupts <prgn/dpkg/ or some other unforeseen circumstance happens you +don't leave the user with a badly-broken package. +<p> + +The maintainer scripts are guaranteed to run with a controlling +terminal and can interact with the user. If they need to prompt for +passwords, do full-screen interaction or something similar you should +do these things to and from <tt>/dev/tty</>, since <prgn/dpkg/ will at +some point redirect scripts' standard input and output so that it can +log the installation process. Likewise, because these scripts may be +executed with standard output redirected into a pipe for logging +purposes, Perl scripts should set unbuffered output by setting +<tt/$|=1/ so that the output is printed immediately rather than being +buffered. +<p> + +Each script should return a zero exit status for success, or a nonzero +one for failure. + +<tag><tt/conffiles/ +<item> + +This file contains a list of configuration files which are to be +handled automatically by <prgn/dpkg/ (see <ref id="conffiles">). Note +that not necessarily every configuration file should be listed here. + +</taglist> + +<sect id="controlfile">The main control information file: <tt/control/ +<p> + +The most important control information file used by <prgn/dpkg/ when it +installs a package is <tt/control/. It contains all the package's +`vital statistics'. +<p> + +The binary package control files of packages built from Debian sources +are made by a special tool, <prgn/dpkg-gencontrol/, which reads +<tt>debian/control</> and <tt>debian/changelog</> to find the +information it needs. See <ref id="sourcepkg"> for more details. +<p> + +The fields in binary package control files are: +<list compact> + +<item><qref id="f-Package"><tt/Package/</> (mandatory) +<item><qref id="versions"><tt/Version/</> (mandatory) + +<item><qref id="f-Architecture"><tt/Architecture/</> +(mandatory)<footnote>This field should appear in all packages, though +<prgn/dpkg/ doesn't require it yet so that old packages can still be +installed.</footnote> + +<item><qref id="relationships"><tt/Depends/, <tt/Provides/ et al.</> +<item><qref id="f-Essential"><tt/Essential/</> +<item><qref id="f-Maintainer"><tt/Maintainer/</> +<item><qref id="f-classification"><tt/Section/, <tt/Priority/</> +<item><qref id="f-Source"><tt/Source/</> +<item><qref id="descriptions"><tt/Description/</> + +</list> +<p> + +A description of the syntax of control files and the purpose of these +fields is available in <ref id="controlfields">. + + +<chapt id="sourcepkg">Source packages +<p> + +The Debian binary packages in the distribution are generated from +Debian sources, which are in a special format to assist the easy and +automatic building of binaries. +<p> + +Tools are provided for manipulating source packages; they pack and +unpack sources and help build of binary packages and help manage the +distribution of new versions. See <manref name=dpkg-source section=1> +for details. + +<sect>The Debianised source tree +<p> + +The source archive scheme described later is intended to allow a +Debianised source tree with some associated control information to be +reproduced and transported easily. The Debianised source tree is a +version of the original program with certain files added for the +benefit of the Debianisation process, and with any other changes +required made to the rest of the source code and installation scripts. +<p> + +The extra files created for Debian are in the subdirectory <tt/debian/ +of the top level of the Debianised source tree. They are described +below. + +<sect1><tt>debian/rules</tt> - the main building script +<p> + +This file is an executable makefile, and contains the package-specific +recipies for compiling the package and building binary package(s) out +of the source. +<p> + +It must start with the line <tt>#!/usr/bin/make -f</tt>, so that it +can be invoked by saying its name rather than invoking <prgn/make/ +explicitly. +<p> + +The targets which are required to be present are: + +<taglist> +<tag/<tt/build// +<item> + +This should perform all non-interactive configuration and compilation +of the package. If a package has an interactive pre-build +configuration routine, the Debianised source package should be built +after this has taken place, so that it can be built without rerunning +the configuration. +<p> + +For some packages, notably ones where the same source tree is compiled +in different ways to produce two binary packages, the <prgn/build/ +target does not make much sense. For these packages it is good enough +to provide two (or more) targets (<tt/build-a/ and <tt/build-b/ or +whatever) for each of the ways of building the package, and a +<prgn/build/ target that does nothing. The <prgn/binary/ target will have +to build the package in each of the possible ways and make the binary +package out of each. +<p> + +The <prgn/build/ target must not do anything that might require root +privilege. +<p> + +The <prgn/build/ target may need to run <prgn/clean/ first - see below. +<p> + +When a package has a configuration routine that takes a long time, or +when the makefiles are poorly designed, or when <prgn/build/ needs to +run <prgn/clean/ first, it is a good idea to <tt/touch build/ when the +build process is complete. This will ensure that if <tt>debian/rules +build</tt> is run again it will not rebuild the whole program. + +<tag/<tt/binary// +<item> + +This target should be all that is necessary for the user to build the +binary package. It should depend on the <prgn/build/ target, above, +so that the package is built if it has not been already. It should +then create the binary package(s), using <prgn/dpkg-gencontrol/ to +make their control files and <prgn/dpkg-deb/ to build them and place +them in the parent of the top level directory. +<p> + +<ref id="binarypkg"> describes how to construct binary packages. +<p> + +The <prgn/binary/ target must be invoked as root. + +<tag/<tt/clean// +<item> + +This should undo any effects that the <prgn/build/ and <prgn/binary/ +targets may have had, except that it should leave alone any output +files created in the parent directory by a run of <prgn/binary/. +<p> + +If a <prgn/build/ file is touched at the end of the <prgn/build/ target, +as suggested above, it must be removed as the first thing that +<prgn/clean/ does, so that running <prgn/build/ again after an interrupted +<prgn/clean/ doesn't think that everything is already done. +<p> + +The <prgn/clean/ target must be invoked as root if <prgn/binary/ has +been invoked since the last <prgn/clean/, or if <prgn/build/ has been +invoked as root (since <prgn/build/ may create directories, for +example). + +<tag/<tt/get-orig-source// +<item> + +This target fetches the most recent version of the original source +package from a canonical archive site (via FTP or WWW, for example), +does any necessary rearrangement to turn it into the original source +tarfile format described below, and leaves it in the current directory. +<p> + +This target may be invoked in any directory, and should take care to +clean up any temporary files it may have left. +<p> + +This target is optional, but providing it if possible is a good idea. + +</taglist> + +The <prgn/build/, <prgn/binary/ and <prgn/clean/ targets must be +invoked with a current directory of the package's top-level +directory. + +<p> + +Additional targets may exist in <tt>debian/rules</tt>, either as +published or undocumented interfaces or for the package's internal +use. + + +<sect1><tt>debian/control</tt> +<p> + +This file contains version-independent details about the source +package and about the binary packages it creates. +<p> + +It is a series of sets of control fields, each syntactically similar +to a binary package control file. The sets are separated by one or +more blank lines. The first set is information about the source +package in general; each subsequent set describes one binary package +that the source tree builds. +<p> + +The syntax and semantics of the fields are described below in +<ref id="controlfields">. +<p> + +The general (binary-package-independent) fields are: +<list compact> +<item><qref id="f-Source"><tt/Source/</> (mandatory) +<item><qref id="f-Maintainer"><tt/Maintainer/</> +<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> +(classification, mandatory) +<item><qref id="f-Standards-Version"><tt/Standards-Version/</> +</list> +<p> + +The per-binary-package fields are: +<list compact> +<item><qref id="f-Package"><tt/Package/</> (mandatory) +<item><qref id="f-Architecture"><tt/Architecture/</> (mandatory) +<item><qref id="descriptions"><tt/Description/</> +<item><qref id="f-classification"><tt/Section/ and <tt/Priority/</> (classification) +<item><qref id="f-Essential"><tt/Essential/</> +<item><qref id="relationships"><tt/Depends/ et al.</> (package interrelationships) +</list> +<p> + +These fields are used by <prgn/dpkg-gencontrol/ to generate control +files for binary packages (see below), by <prgn/dpkg-genchanges/ to +generate the <tt/.changes/ file to accompany the upload, and by +<prgn/dpkg-source/ when it creates the <tt/.dsc/ source control file as +part of a source archive. +<p> + +The fields here may contain variable references - their values will be +substituted by <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ or +<prgn/dpkg-source/ when they generate output control files. See <ref +id="srcsubstvars"> for details. +<p> + +<sect2>User-defined fields +<p> + +Additional user-defined fields may be added to the source package +control file. Such fields will be ignored, and not copied to (for +example) binary or source package control files or upload control +files. +<p> + +If you wish to add additional unsupported fields to these output files +you should use the mechanism described here. +<p> + +Fields in the main source control information file with names starting +<tt/X/, followed by one or more of the letters <tt/BCS/ and a hyphen +<tt/-/, will be copied to the output files. Only the part of the +field name after the hyphen will be used in the output file. Where +the letter <tt/B/ is used the field will appear in binary package +control files, where the letter <tt/S/ is used in source package +control files and where <tt/C/ is used in upload control +(<tt/.changes/) files. +<p> + +For example, if the main source information control file contains the +field +<example> +XBS-Comment: I stand between the candle and the star. +</example> +then the binary and source package control files will contain the +field +<example> +Comment: I stand between the candle and the star. +</example> + +<sect1 id="dpkgchangelog"><tt>debian/changelog</> +<p> + +This file records the changes to the Debian-specific parts of the +package<footnote>Though there is nothing stopping an author who is +also the Debian maintainer from using it for all their changes, it +will have to be renamed if the Debian and upstream maintainers become +different people.</footnote>. +<p> + +It has a special format which allows the package building tools to +discover which version of the package is being built and find out +other release-specific information. +<p> + +That format is a series of entries like this: +<example> +<var/package/ (<var/version/) <var/distribution(s)/; urgency=<var/urgency/ + + * <var/change details/ + <var/more change details/ + * <var/even more change details/ + + -- <var/maintainer name and email address/ <var/date/ +</example> +<p> + +<var/package/ and <var/version/ are the source package name and +version number. <var/distribution(s)/ lists the distributions where +this version should be installed when it is uploaded - it is copied to +the <tt/Distribution/ field in the <tt/.changes/ file. See <ref +id="f-Distribution">. +<p> + +<var/urgency/ is the value for the <tt/Urgency/ field in the +<tt/.changes/ file for the upload. See <ref id="f-Urgency">. It is +not possible to specify an urgency containing commas; commas are used +to separate <tt/<var/keyword/=<var/value// settings in the <prgn/dpkg/ +changelog format (though there is currently only one useful +<var/keyword/, <tt/urgency/). +<p> + +The change details may in fact be any series of lines starting with at +least two spaces, but conventionally each change starts with an +asterisk and a separating space and continuation lines are indented so +as to bring them in line with the start of the text above. Blank +lines may be used here to separate groups of changes, if desired. +<p> + +The maintainer name and email address should <em/not/ necessarily be +those of the usual package maintainer. They should be the details of +the person doing <em/this/ version. The information here will be +copied to the <tt/.changes/ file, and then later used to send an +acknowledgement when the upload has been installed. +<p> + +The <var/date/ should be in RFC822 format; it should include the +timezone specified numerically, with the timezone name or abbreviation +optionally present as a comment. +<p> + +The first `title' line with the package name should start at the left +hand margin; the `trailer' line with the maintainer and date details +should be preceded by exactly one space. The maintainer details and +the date must be separated by exactly two spaces. +<p> + +An Emacs mode for editing this format is available: it is called +<tt/debian-changelog-mode/. You can have this mode selected +automatically when you edit a Debian changelog by adding a local +variables clause to the end of the changelog. + +<sect2>Defining alternative changelog formats +<p> + +It is possible to use a different format to the standard one, by +providing a parser for the format you wish to use. +<p> + +In order to have <tt/dpkg-parsechangelog/ run your parser, you must +include a line within the last 40 lines of your file matching the Perl +regular expression: +<example> +\schangelog-format:\s+([0-9a-z]+)\W +</example> +The part in parentheses should be the name of the format. +<p> + +If such a line exists then <tt/dpkg-parsechangelog/ will look for the +parser as <tt>/usr/lib/dpkg/parsechangelog/<var/format-name/</> or +<tt>/usr/local/lib/dpkg/parsechangelog/<var/format-name/</>; it is an +error for it not to find it, or for it not to be an executable +program. The default changelog format is <tt/dpkg/, and a parser for +it is provided with the <tt/dpkg/ package. +<p> + +The parser will be invoked with the changelog open on standard input +at the start of the file. It should read the file (it may seek if it +wishes) to determine the information required and return the parsed +information to standard output in the form of a series of control +fields in the standard format. By default it should return +information about only the most recent version in the changelog; it +should accept a <tt/-v<var/version// option to return changes +information from all versions present <em/strictly after/ +<var/version/, and it should then be an error for <var/version/ not to +be present in the changelog. +<p> + +The fields are: +<list compact> +<item><qref id="f-Source"><tt/Source/</> +<item><qref id="versions"><tt/Version/</> (mandatory) +<item><qref id="f-Distribution"><tt/Distribution/</> (mandatory) +<item><qref id="f-Urgency"><tt/Urgency/</> (mandatory) +<item><qref id="f-Maintainer"><tt/Maintainer/</> (mandatory) +<item><qref id="f-Date"><tt/Date/</> +<item><qref id="f-Changes"><tt/Changes/</> (mandatory) +</list> +<p> + +If several versions are being returned (due to the use of <tt/-v/), +the urgency value should be of the highest urgency code listed at the +start of any of the versions requested followed by the concatenated +(space-separated) comments from all the versions requested; the +maintainer, version, distribution and date should always be from the +most recent version. +<p> + +For the format of the <tt/Changes/ field see <ref id="f-Changes">. +<p> + +If the changelog format which is being parsed always or almost always +leaves a blank line between individual change notes these blank lines +should be stripped out, so as to make the resulting output compact. +<p> + +If the changelog format does not contain date or package name +information this information should be omitted from the output. The +parser should not attempt to synthesise it or find it from other +sources. +<p> + +If the changelog does not have the expected format the parser should +exit with a nonzero exit status, rather than trying to muddle through +and possibly generating incorrect output. +<p> + +A changelog parser may not interact with the user at all. + +<sect1 id="srcsubstvars"><tt>debian/substvars</> and variable substitutions +<p> + +When <prgn/dpkg-gencontrol/, <prgn/dpkg-genchanges/ and +<prgn/dpkg-source/ generate control files they do variable +substitutions on their output just before writing it. Variable +substitutions have the form <tt/${<var/variable-name/}/. The optional +file <tt>debian/substvars</> contains variable substitutions to be +used; variables can also be set directly from <tt>debian/rules</> +using the <tt/-V/ option to the source packaging commands, and certain +predefined variables are available. +<p> + +The file may be a static part of the source archive, or generated and +modified dynamically by <tt>debian/rules</> targets. In the latter +case it must be removed by the <prgn/clean/ target. +<p> + +See <manref name=dpkg-source section=1> for full details about source +variable substitutions, including the format of +<tt>debian/substvars</>. + +<sect1><tt>debian/files</> +<p> + +This file is not a permanent part of the source tree; it is used while +building packages to record which files are being generated. +<prgn/dpkg-genchanges/ uses it when it generates a <tt/.changes/ file. +<p> + +It should not exist in a shipped source package, and so it (and any +backup files or temporary files such as +<tt/files.new/<footnote><tt/files.new/ is used as a temporary file by +<prgn/dpkg-gencontrol/ and <prgn/dpkg-distaddfile/ - they write a new +version of <tt/files/ here before renaming it, to avoid leaving a +corrupted copy if an error occurs</footnote>) should be removed by the +<prgn/clean/ target. It may also be wise to ensure a fresh start by +emptying or removing it at the start of the <prgn/binary/ target. +<p> + +<prgn/dpkg-gencontrol/ adds an entry to this file for the <tt/.deb/ +file that will be created by <prgn/dpkg-deb/ from the control file +that it generates, so for most packages all that needs to be done with +this file is to delete it in <prgn/clean/. +<p> + +If a package upload includes files besides the source package and any +binary packages whose control files were made with +<prgn/dpkg-gencontrol/ then they should be placed in the parent of the +package's top-level directory and <prgn/dpkg-distaddfile/ should be +called to add the file to the list in <tt>debian/files</>. + +<sect1><tt>debian/tmp</> +<p> + +This is the canonical temporary location for the construction of +binary packages by the <prgn/binary/ target. The directory <tt/tmp/ +serves as the root of the filesystem tree as it is being constructed +(for example, by using the package's upstream makefiles install +targets and redirecting the output there), and it also contains the +<tt/DEBIAN/ subdirectory. See <ref id="bincreating">. +<p> + +If several binary packages are generated from the same source tree it +is usual to use several <tt>debian/tmp<var/something/</> directories, +for example <tt/tmp-a/ or <tt/tmp-doc/. +<p> + +Whatever <tt>tmp</> directories are created and used by <prgn/binary/ +must of course be removed by the <prgn/clean/ target. + + +<sect id="sourcearchives">Source packages as archives +<p> + +As it exists on the FTP site, a Debian source package consists of +three related files. You must have the right versions of all three to +be able to use them. +<p> + +<taglist> +<tag/Debian source control file - <tt/.dsc// +<item> + +This file contains a series of fields, identified and separated just +like the fields in the control file of a binary package. The fields +are listed below; their syntax is described above, in +<ref id="controlfields">. +<list compact> +<item><qref id="f-Source"><tt/Source/</> +<item><qref id="versions"><tt/Version/</> +<item><qref id="f-Maintainer"><tt/Maintainer/</> +<item><qref id="f-Binary"><tt/Binary/</> +<item><qref id="f-Architecture"><tt/Architecture/</> +<item><qref id="f-Standards-Version"><tt/Standards-Version/</> +<item><qref id="f-Files"><tt/Files/</> +</list> +<p> + +The source package control file is generated by <prgn/dpkg-source/ +when it builds the source archive, from other files in the source +package, described above. When unpacking it is checked against the +files and directories in the other parts of the source package, as +described below. + +<tag/Original source archive - <tt/<var/package/_<var/upstream-version/.orig.tar.gz// +<item> + +This is a compressed (with <tt/gzip -9/) <prgn/tar/ file containing +the source code from the upstream authors of the program. The tarfile +unpacks into a directory +<tt/<var/package/-<var/upstream-version/.orig/, and does not contain +files anywhere other than in there or in its subdirectories. + +<tag/Debianisation diff - <tt/<var/package/_<var/version-revision/.diff.gz// +<item> + +This is a unified context diff (<tt/diff -u/) giving the changes which +are required to turn the original source into the Debian source. +These changes may only include editing and creating plain files. The +permissions of files, the targets of symbolic links and the +characteristics of special files or pipes may not be changed and no +files may be removed or renamed. +<p> + +All the directories in the diff must exist, except the <tt/debian/ +subdirectory of the top of the source tree, which will be created by +<prgn/dpkg-source/ if necessary when unpacking. +<p> + +The <prgn/dpkg-source/ program will automatically make the +<tt>debian/rules</tt> file executable (see below). + +</taglist> +<p> + +If there is no original source code - for example, if the package is +specially prepared for Debian or the Debian maintainer is the same as +the upstream maintainer - the format is slightly different: then there +is no diff, and the tarfile is named +<tt/<var/package/_<var/version/.tar.gz</> and contains a directory +<tt/<var/package/-<var/version/</>. + +<sect>Unpacking a Debian source package without <prgn/dpkg-source/ +<p> + +<tt/dpkg-source -x/ is the recommended way to unpack a Debian source +package. However, if it is not available it is possible to unpack a +Debian source archive as follows: + +<enumlist compact> +<item>Untar the tarfile, which will create a <tt/.orig/ directory. +<item>Rename the <tt/.orig/ directory to +<tt/<var/package/-<var/version//. +<item>Create the subdirectory <tt/debian/ at the top of the source +tree. +<item>Apply the diff using <tt/patch -p0/. +<item>Untar the tarfile again if you want a copy of the original +source code alongside the Debianised version. +</enumlist> +<p> + +It is not possible to generate a valid Debian source archive without +using <prgn/dpkg-source/. In particular, attempting to use +<prgn/diff/ directly to generate the <tt/.diff.gz/ file will not work. + +<sect1>Restrictions on objects in source packages +<p> + +The source package may not contain any device special files, sockets +or setuid or setgid files.<footnote>Setgid directories are +allowed.</footnote> +<p> + +The source packaging tools manage the changes between the original and +Debianised source using <prgn/diff/ and <prgn/patch/. Turning the +original source tree as included in the <tt/.orig.tar.gz/ into the +debianised source must not involve any changes which cannot be handled +by these tools. Problematic changes which cause <prgn/dpkg-source/ to +halt with an error when building the source package are: +<list compact> +<item>Adding or removing symbolic links, sockets or pipes. +<item>Changing the targets of symbolic links. +<item>Creating directories, other than <tt/debian/. +<item>Changes to the contents of binary files. +</list> +Changes which cause <prgn/dpkg-source/ to print a warning but continue +anyway are: +<list compact> +<item>Removing files, directories or symlinks. <footnote>Renaming a +file is not treated specially - it is seen as the removal of the old +file (which generates a warning, but is otherwise ignored), and the +creation of the new one.</footnote> +</list> +Changes which are not represented, but which are not detected by +<prgn/dpkg-source/, are: +<list compact> +<item>Changing the permissions of files (other than +<tt>debian/rules</>) and directories. +</list> +<p> + +The <tt/debian/ directory and <tt>debian/rules</> are handled +specially by <prgn/dpkg-source/ - before applying the changes it will +create the <tt/debian/ directory, and afterwards it will make +<tt>debian/rules</> world-exectuable. + +<chapt id="controlfields">Control files and their fields +<p> + +Many of the tools in the <prgn/dpkg/ suite manipulate data in a common +format, known as control files. Binary and source packages have +control data as do the <tt/.changes/ files which control the +installation of uploaded files, and <prgn/dpkg/'s internal databases +are in a similar format. + +<sect>Syntax of control files +<p> + +A file consists of one or more paragraphs of fields. The paragraphs +are separated by blank lines. Some control files only allow one +paragraph; others allow several, in which case each paragraph often +refers to a different package. +<p> + +Each paragraph is a series of fields and values; each field consists +of a name, followed by a colon and the value. It ends at the end of +the line. Horizontal whitespace (spaces and tabs) may occur before or +after the value and is ignored there; it is conventional to put a +single space after the colon. +<p> + +Some fields' values may span several lines; in this case each +continuation line <em/must/ start with a space or tab. Any trailing +spaces or tabs at the end of individual lines of a field value are +ignored. +<p> + +Except where otherwise stated only a single line of data is allowed +and whitespace is not significant in a field body. Whitespace may +never appear inside names (of packages, architectures, files or +anything else), version numbers or in between the characters of +multi-character version relationships. +<p> + +Field names are not case-sensitive, but it is usual to capitalise the +fields using mixed case as shown below. +<p> + +Blank lines, or lines consisting only of spaces and tabs, are not +allowed within field values or between fields - that would mean a new +paragraph. +<p> + +It is important to note that there are several fields which are +optional as far as <prgn/dpkg/ and the related tools are concerned, +but which must appear in every Debian package, or whose omission may +cause problems. When writing the control files for Debian packages +you <em/must/ read the Debian policy manual in conjuction with the +details below and the list of fields for the particular file. + +<sect>List of fields + +<sect1 id="f-Package"><tt/Package/ +<p> + +The name of the binary package. Package names consist of the +alphanumerics and <tt/+/ <tt/-/ <tt/./ (plus, minus and full +stop).<footnote>The characters <tt/@/ <tt/:/ <tt/=/ <tt/%/ <tt/_/ (at, +colon, equals, percent and underscore) used to be legal and are still +accepted when found in a package file, but may not be used in new +packages</footnote> +<p> + +They must be at least two characters and must start with an +alphanumeric. In current versions of dpkg they are sort of +case-sensitive<footnote>This is a bug.</footnote>; use lowercase +package names unless the package you're building (or referring to, in +other fields) is already using uppercase. + +<sect1 id="f-Version"><tt/Version/ +<p> + +This lists the source or binary package's version number - see <ref +id="versions">. + +<sect1 id="f-Architecture"><tt/Architecture/ +<p> + +This is the architecture string; it is a single word for the CPU +architecture. +<p> + +<prgn/dpkg/ will check the declared architecture of a binary package +against its own compiled-in value before it installs it. +<p> + +The special value <tt/all/ indicates that the package is +architecture-independent. +<p> + +In the main <tt>debian/control</> file in the source package, or in +the source package control file <tt/.dsc/, a list of architectures +(separated by spaces) is also allowed, as is the special value +<tt/any/. A list indicates that the source will build an +architecture-dependent package, and will only work correctly on the +listed architectures. <tt/any/ indicates that though the source +package isn't dependent on any particular architecture and should +compile fine on any one, the binary package(s) produced are not +architecture-independent but will instead be specific to whatever the +current build architecture is. +<p> + +In a <tt/.changes/ file the <tt/Architecture/ field lists the +architecture(s) of the package(s) currently being uploaded. This will +be a list; if the source for the package is being uploaded too the +special entry <tt/source/ is also present. +<p> + +The current build architecture can be determined using <tt/dpkg +--print-architecture/.<footnote>This actually invokes +<example> +gcc --print-libgcc-file-name +</example> +and parses and decomposes the output and looks the CPU type from the +GCC configuration in a table in <prgn/dpkg/. This is so that it will +work if you're cross-compiling. +</footnote> +This value is automatically used by <prgn/dpkg-gencontrol/ when +building the control file for a binary package for which the source +control information doesn't specify architecture <tt/all/. +<p> + +There is a separate option, <tt/--print-installation-architecture/, +for finding out what architecture <prgn/dpkg/ is willing to install. +This information is also in the output of <tt/dpkg --version/. + +<sect1 id="f-Maintainer"><tt/Maintainer/ +<p> + +The package maintainer's name and email address. The name should come +first, then the email address inside angle brackets <tt/<>/ (in +RFC822 format). +<p> + +If the maintainer's name contains a full stop then the whole field +will not work directly as an email address due to a misfeature in the +syntax specified in RFC822; a program using this field as an address +must check for this and correct the problem if necessary (for example +by putting the name in round brackets and moving it to the end, and +bringing the email address forward). +<p> + +In a <tt/.changes/ file or parsed changelog data this contains the +name and email address of the person responsible for the particular +version in question - this may not be the package's usual maintainer. +<p> + +This field is usually optional in as far as the <prgn/dpkg/ are +concerned, but its absence when building packages usually generates a +warning. + +<sect1 id="f-Source"><tt/Source/ +<p> + +This field identifies the source package name. +<p> + +In a main source control information or a <tt/.changes/ or <tt/.dsc/ +file or parsed changelog data this may contain only the name of the +source package. +<p> + +In the control file of a binary package (or in a <tt/Packages/ file) +it may be followed by a version number in parentheses.<footnote>It is +usual to leave a space after the package name if a version number is +specified.</footnote> This version number may be omitted (and is, by +<prgn/dpkg-gencontrol/) if it has the same value as the <tt/Version/ +field of the binary package in question. The field itself may be +omitted from a binary package control file when the source package has +the same name and version as the binary package. + +<sect1>Package interrelationship fields: +<tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/ +<tt/Suggests/, <tt/Conflicts/, <tt/Provides/, <tt/Replaces/ +<p> + +These fields describe the package's relationships with other packages. +Their syntax and semantics are described in <ref id="relationships">. + +<sect1 id="f-Description"><tt/Description/ +<p> + +In a binary package <tt/Packages/ file or main source control file +this field contains a description of the binary package, in a special +format. See <ref id="descriptions"> for details. +<p> + +In a <tt/.changes/ file it contains a summary of the descriptions for +the packages being uploaded. The part of the field before the first +newline is empty; thereafter each line has the name of a binary +package and the summary description line from that binary package. +Each line is indented by one space. + +<sect1 id="f-Essential"><tt/Essential/ +<p> + +This is a boolean field which may occur only in the control file of a +binary package (or in the <tt/Packages/ file) or in a per-package +fields paragraph of a main source control data file. +<p> + +If set to <tt/yes/ then <prgn/dpkg/ and <prgn/dselect/ will refuse to +remove the package (though it can be upgraded and/or replaced). The +other possible value is <tt/no/, which is the same as not having the +field at all. + +<sect1 id="f-classification"><tt/Section/ and <tt/Priority/ +<p> + +These two fields classify the package. The <tt/Priority/ represents +how important that it is that the user have it installed; the +<tt/Section/ represents an application area into which the package has +been classified. +<p> + +When they appear in the <tt>debian/control</> file these fields give +values for the section and priority subfields of the <tt/Files/ field +of the <tt/.changes/ file, and give defaults for the section and +priority of the binary packages. +<p> + +The section and priority are represented, though not as separate +fields, in the information for each file in the <qref +id="f-Files"><tt/Files/</> field of a <tt/.changes/ file. The +section value in a <tt/.changes/ file is used to decide where to +install a package in the FTP archive. +<p> + +These fields are not used by by <prgn/dpkg/ proper, but by +<prgn/dselect/ when it sorts packages and selects defaults. See the +Debian policy manual for the priorities in use and the criteria for +selecting the priority for a Debian package, and look at the Debian +FTP archive for a list of currently in-use priorities. +<p> + +These fields may appear in binary package control files, in which case +they provide a default value in case the <tt/Packages/ files are +missing the information. <prgn/dpkg/ and <prgn/dselect/ will only use +the value from a <tt/.deb/ file if they have no other information; a +value listed in a <tt/Packages/ file will always take precedence. By +default <prgn/dpkg-genchanges/ does not include the section and +priority in the control file of a binary package - use the <tt/-isp/, +<tt/-is/ or <tt/-ip/ options to achieve this effect. + +<sect1 id="f-Binary"><tt/Binary/ +<p> + +This field is a list of binary packages. +<p> + +When it appears in the <tt/.dsc/ file it is the list of binary +packages which a source package can produce. It does not necessarily +produce all of these binary packages for every architecture. The +source control file doesn't contain details of which architectures are +appropriate for which of the binary packages. +<p> + +When it appears in a <tt/.changes/ file it lists the names of the +binary packages actually being uploaded. +<p> + +The syntax is a list of binary packages separated by +commas.<footnote>A space after each comma is conventional.</footnote> +Currently the packages must be separated using only spaces in the +<tt/.changes/ file. + +<sect1 id="f-Files"><tt/Files/ +<p> + +This field contains a list of files with information about each one. +The exact information and syntax varies with the context. In all +cases the the part of the field contents on the same line as the field +name is empty. The remainder of the field is one line per file, each +line being indented by one space and containing a number of sub-fields +separated by spaces. +<p> + +In the <tt/.dsc/ (Debian source control) file each line contains the +MD5 checksum, size and filename of the tarfile and (optionally) diff +file which make up the remainder of the source package.<footnote>That +is, the parts which are not the <tt/.dsc/.</footnote> The exact forms +of the filenames are described in <ref id="sourcearchives">. +<p> + +In the <tt/.changes/ file this contains one line per file being +uploaded. Each line contains the MD5 checksum, size, section and +priority and the filename. The section and priority are the values of +the corresponding fields in the main source control file - see <ref +id="f-classification">. If no section or priority is specified then +<tt/-/ should be used, though section and priority values must be +specified for new packages to be installed properly. +<p> + +The special value <tt/byhand/ for the section indicates that the file +in question is not an ordinary package file and must by installed by +hand by the distribution maintainers. If the section is <tt/byhand/ +the priority should be <tt/-/. + + +<sect1 id="f-Standards-Version"><tt/Standards-Version/ +<p> + +The most recent version of the standards (the <prgn/dpkg/ programmers' +and policy manuals and associated texts) with which the package +complies. This is updated manually when editing the source package to +conform to newer standards; it can sometimes be used to tell when a +package needs attention. +<p> + +Its format is the same as that of a version number except that no +epoch or Debian revision is allowed - see <ref id="versions">. + +<sect1 id="f-Distribution"><tt/Distribution/ +<p> + +In a <tt/.changes/ file or parsed changelog output this contains the +(space-separated) name(s) of the distribution(s) where this version of +the package should be or was installed. Distribution names follow the +rules for package names. (See <ref id="f-Package">). +<p> + +Current distribution values are <tt/stable/, <tt/unstable/, +<tt/contrib/, <tt/non-free/ and <tt/experimental/. + +<sect1 id="f-Urgency"><tt/Urgency/ +<p> + +This is a description of how important it is to upgrade to this +version from previous ones. It consists of a single keyword usually +taking one of the values <tt/LOW/, <tt/MEDIUM/ or <tt/HIGH/) followed +by an optional commentary (separated by a space) which is usually in +parentheses. For example: +<example> +Urgency: LOW (HIGH for diversions users) +</example> +<p> + +This field appears in the <tt/.changes/ file and in parsed changelogs; +its value appears as the value of the <tt/urgency/ attribute in a +<prgn/dpkg/-style changelog (see <ref id="dpkgchangelog">). +<p> + +Urgency keywords are not case-sensitive. + +<sect1 id="f-Date"><tt/Date/ +<p> + +In <tt/.changes/ files and parsed changelogs, this gives the date the +package was built or last edited. + +<sect1 id="f-Format"><tt/Format/ +<p> + +This field occurs in <tt/.changes/ files, and specifies a format +revision for the file. The format described here is version <tt/1.5/. +The syntax of the format value is the same as that of a package +version number except that no epoch or Debian revision is allowed - +see <ref id="versions">. + +<sect1 id="f-Changes"><tt/Changes/ +<p> + +In a <tt/.changes/ file or parsed changelog this field contains the +human-readable changes data, describing the differences between the +last version and the current one. +<p> + +There should be nothing in this field before the first newline; all +the subsequent lines must be indented by at least one space; blank +lines must be represented by a line consiting only of a space and a +full stop. +<p> + +Each version's change information should be preceded by a `title' line +giving at least the version, distribution(s) and urgency, in a +human-readable way. +<p> + +If data from several versions is being returned the entry for the most +recent version should be returned first, and entries should be +separated by the representation of a blank line (the `title' line may +also be followed by the representation of blank line). + +<sect1 id="f-Filename"><tt/Filename/ and <tt/MSDOS-Filename/ +<p> + +These fields in <tt/Packages/ files give the filename(s) of (the parts +of) a package in the distribution directories, relative to the root of +the Debian hierarchy. If the package has been split into several +parts the parts are all listed in order, separated by spaces. + +<sect1 id="f-Size"><tt/Size/ and <tt/MD5sum/ +<p> + +These fields in <tt/Packages/ files give the size (in bytes, expressed +in decimal) and MD5 checksum of the file(s) which make(s) up a binary +package in the distribution. If the package is split into several +parts the values for the parts are listed in order, separated by +spaces. + +<sect1 id="f-Status"><tt/Status/ +<p> + +This field in <prgn/dpkg/'s status file records whether the user wants a +package installed, removed or left alone, whether it is broken +(requiring reinstallation) or not and what its current state on the +system is. Each of these pieces of information is a single word. + +<sect1 id="f-Config-Version"><tt/Config-Version/ +<p> + +If a package is not installed or not configured, this field in +<prgn/dpkg/'s status file records the last version of the package which +was successfully configured. + +<sect1 id="f-Conffiles"><tt/Conffiles/ +<p> + +This field in <prgn/dpkg/'s status file contains information about the +automatically-managed configuration files held by a package. This +field should <em/not/ appear anywhere in a package! + +<sect1>Obsolete fields +<p> + +These are still recognised by <prgn/dpkg/ but should not appear anywhere +any more. + +<taglist compact> + +<tag><tt/Revision/ +<tag><tt/Package-Revision/ +<tag><tt/Package_Revision/ +<item> +The Debian revision part of the package version was at one point in a +separate control file field. This field went through several names. + +<tag><tt/Recommended/ +<item>Old name for <tt/Recommends/ + +<tag><tt/Optional/ +<item>Old name for <tt/Suggests/. + +<tag><tt/Class/ +<item>Old name for <tt/Priority/. + +</taglist> + +<chapt id="versions">Version numbering +<p> + +Every package has a version number, in its <tt/Version/ control file +field. +<p> + +<prgn/dpkg/ imposes an ordering on version numbers, so that it can tell +whether packages are being up- or downgraded and so that <prgn/dselect/ +can tell whether a package it finds available is newer than the one +installed on the system. The version number format has the most +significant parts (as far as comparison is concerned) at the +beginning. +<p> + +The version number format is: +&lsqb<var/epoch/<tt/:/]<var/upstream-version/[<tt/-/<var/debian-revision/]. +<p> + +The three components here are: + +<taglist> + +<tag><var/epoch/ +<item> + +This is a single unsigned integer, which should usually be small. It +may be omitted, in which case zero is assumed. If it is omitted then +the <var/upstream-version/ may not contain any colons. +<p> + +It is provided to allow mistakes in the version numbers of older +versions of a package, and also a package's previous version numbering +schemes, to be left behind. +<p> + +<prgn/dpkg/ will not usually display the epoch unless it is essential +(non-zero, or if the <var/upstream-version/ contains a colon); +<prgn/dselect/ does not display epochs at all in the main part of the +package selection display. + +<tag><var/upstream-version/ +<item> + +This is the main part of the version. It is usually version number of +the original (`upstream') package of which the <tt/.deb/ file has been +made, if this is applicable. Usually this will be in the same format +as that specified by the upstream author(s); however, it may need to +be reformatted to fit into <prgn/dpkg/'s format and comparison scheme. +<p> + +The comparison behaviour of <prgn/dpkg/ with respect to the +<var/upstream-version/ is described below. The <var/upstream-version/ +portion of the version number is mandatory. +<p> + +The <var/upstream-version/ may contain only alphanumerics and the +characters <tt/+/ <tt/./ <tt/-/ <tt/:/ (full stop, plus, hyphen, +colon) and should start with a digit. If there is no +<var/debian-revision/ then hyphens are not allowed; if there is no +<var/epoch/ then colons are not allowed. + +<tag><var/debian-revision/ +<item> + +This part of the version represents the version of the modifications +that were made to the package to make it a Debian binary package. It +is in the same format as the <var/upstream-version/ and <prgn/dpkg/ +compares it in the same way. +<p> + +It is optional; if it isn't present then the <var/upstream-version/ +may not contain a hyphen. This format represents the case where a +piece of software was written specifically to be turned into a Debian +binary package, and so there is only one `debianization' of it and +therefore no revision indication is required. +<p> + +It is conventional to restart the <var/debian-revision/ at <tt/1/ each +time the <var/upstream-version/ is increased. +<p> + +<prgn/dpkg/ will break the <var/upstream-version/ and +<var/debian-revision/ apart at the last hyphen in the string. The +absence of a <var/debian-revision/ compares earlier than the presence +of one (but note that the <var/debian-revision/ is the least +significant part of the version number). +<p> + +The <var/debian-revision/ may contain only alphanumerics and the +characters <tt/+/ and <tt/./ (plus and full stop). + +</taglist> + +The <var/upstream-version/ and <var/debian-revision/ parts are +compared by <prgn/dpkg/ using the same algorithm: +<p> + +The strings are compared from left to right. +<p> + +First the initial part of each string consisting entirely of non-digit +characters is determined. These two parts (one of which may be empty) +are compared lexically. If a difference is found it is returned. The +lexical comparison is a comparison of ASCII values modified so that +all the letters sort earlier than all the non-letters. +<p> + +Then the initial part of the remainder of each string which consists +entirely of digit characters is determined. The numerical values of +these two parts are compared, and any difference found is returned as +the result of the comparison. For these purposes an empty string +(which can only occur at the end of one or both version strings being +compared) counts as zero. +<p> + +These two steps are repeated (chopping initial non-digit strings and +initial digit strings off from the start) until a difference is found +or both strings are exhausted. +<p> + +Note that the purpose of epochs is to allow us to leave behind +mistakes in version numbering, and to cope with situations where the +version numbering changes. It is <em/not/ there to cope with version +numbers containing strings of letters which <prgn/dpkg/ cannot interpret +(such as <tt/ALPHA/ or <tt/pre-/), or with silly orderings (the author +of this manual has heard of a package whose versions went <tt/1.1/, +<tt/1.2/, <tt/1.3/, <tt/1/, <tt/2.1/, <tt/2.2/, <tt/2/ and so forth). +<p> + +If an upstream package has problematic version numbers they should be +converted to a sane form for use in the <tt/Version/ field. + + +<chapt id="maintainerscripts">Package maintainer scripts +and installation procedure +<sect>Introduction to package maintainer scripts +<p> + +It is possible supply scripts as part of a package which <prgn/dpkg/ +will run for you when your package is installed, upgraded or removed. +<p> + +These scripts should be the files <tt/preinst/, <tt/postinst/, +<tt/prerm/ and <tt/postrm/ in the control area of the package. They +must be proper exectuable files; if they are scripts (which is +recommended) they must start with the usual <tt/#!/ convention. They +should be readable and executable to anyone, and not world-writeable. +<p> + +<prgn/dpkg/ looks at the exit status from these scripts. It is +important that they exit with a non-zero status if there is an error, +so that <prgn/dpkg/ can stop its processing. For shell scripts this +means that you <em/almost always/ need to use <tt/set -e/ (this is +usually true when writing shell scripts, in fact). It is also +important, of course, that they don't exit with a non-zero status if +everything went well. +<p> + +It is necessary for the error recovery procedures that the scripts be +idempotent: ie, invoking the same script several times in the same +situation should do no harm. If the first call failed, or aborted +half way through for some reason, the second call should merely do the +things that were left undone the first time, if any, and exit with a +success status. +<p> + +When a package is upgraded a combination of the scripts from the old +and new packages is called in amongst the other steps of the upgrade +procedure. If your scripts are going to be at all complicated you +need to be aware of this, and may need to check the arguments to your +scripts. +<p> + +Broadly speaking the <prgn/preinst/ is called before (a particular +version of) a package is installed, and the <prgn/postinst/ afterwards; +the <prgn/prerm/ before (a version of) a package is removed and the +<prgn/postrm/ afterwards. + + +<sect id="mscriptsinstact">Summary of ways maintainer scripts are called +<p> + +<list compact> +<item><var/new-preinst/ <tt/install/ +<item><var/new-preinst/ <tt/install/ <var/old-version/ +<item><var/new-preinst/ <tt/upgrade/ <var/old-version/ +<item><var/old-preinst/ <tt/abort-upgrade/ <var/new-version/ +</list> +<p> + +<list compact> +<item><var/postinst/ <tt/configure/ <var/most-recently-configured-version/ +<item><var/old-postinst/ <tt/abort-upgrade/ <var/new version/ +<item><var/conflictor's-postinst/ <tt/abort-remove/ + <tt/in-favour/ <var/package/ <var/new-version/ +<item><var/deconfigured's-postinst/ <tt/abort-deconfigure/ + <tt/in-favour/ <var/failed-install-package/ <var/version/ + <tt/removing/ <var/conflicting-package/ <var/version/ +</list> +<p> + +<list compact> +<item><var/prerm/ <tt/remove/ +<item><var/old-prerm/ <tt/upgrade/ <var/new-version/ +<item><var/new-prerm/ <tt/failed-upgrade/ <var/old-version/ +<item><var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/ + <var/package/ <var/new-version/ +<item><var/deconfigured's-prerm/ <tt/deconfigure/ + <tt/in-favour/ <var/package-being-installed/ <var/version/ + <tt/removing/ <var/conflicting-package/ <var/version/ +</list> +<p> + +<list compact> +<item><var/postrm/ <tt/remove/ +<item><var/postrm/ <tt/purge/ +<item><var/old-postrm/ <tt/upgrade/ <var/new-version/ +<item><var/new-postrm/ <tt/failed-upgrade/ <var/old-version/ +<item><var/new-postrm/ <tt/abort-install/ +<item><var/new-postrm/ <tt/abort-install/ <var/old-version/ +<item><var/new-postrm/ <tt/abort-upgrade/ <var/old-version/ +<item><var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/new-version/ +</list> + + +<sect>Details of unpack phase of installation or upgrade +<p> + +The procedure on installation/upgrade/overwrite/disappear (ie, when +running <tt/dpkg --unpack/, or the unpack stage of <tt/dpkg +--install/) is as follows. In each case if an error occurs the +actions in are general run backwards - this means that the maintainer +scripts are run with different arguments in reverse order. These are +the `error unwind' calls listed below. + +<enumlist> +<item> + +<enumlist> +<item> +If a version the package is already +installed, call +<example> +<var/old-prerm/ upgrade <var/new-version/ +</example> + +<item> +If this gives an error (ie, a non-zero exit status), dpkg will +attempt instead: +<example> +<var/new-prerm/ failed-upgrade <var/old-version/ +</example> +Error unwind, for both the above cases: +<example> +<var/old-postinst/ abort-upgrade <var/new-version/ +</example> + +</enumlist> + +<item> +If a `conflicting' package is being removed at the same time: +<enumlist> + +<item> +If any packages depended on that conflicting package and +<tt/--auto-deconfigure/ is specified, call, for each such package: +<example> +<var/deconfigured's-prerm/ deconfigure \ + in-favour <var/package-being-installed/ <var/version/ \ + removing <var/conflicting-package/ <var/version/ +</example> +Error unwind: +<example> +<var/deconfigured's-postinst/ abort-deconfigure \ + in-favour <var/package-being-installed-but-failed/ <var/version/ \ + removing <var/conflicting-package/ <var/version/ +</example> +The deconfigured packages are marked as requiring configuration, so +that if <tt/--install/ is used they will be configured again if +possible. + +<item> +To prepare for removal of the conflicting package, call: +<example> +<var/conflictor's-prerm/ remove in-favour <var/package/ <var/new-version/ +</example> +Error unwind: +<example> +<var/conflictor's-postinst/ abort-remove \ + in-favour <var/package/ <var/new-version/ +</example> + +</enumlist> + +<item> +<enumlist> +<item> +If the package is being upgraded, call: +<example> +<var/new-preinst/ upgrade <var/old-version/ +</example> + +<item> +Otherwise, if the package had some configuration files from a previous +version installed (ie, it is in the `configuration files only' state): +<example> +<var/new-preinst/ install <var/old-version/ +</example> + +<item> +Otherwise (ie, the package was completely purged): +<example> +<var/new-preinst/ install +</example> +Error unwind versions, respectively: +<example> +<var/new-postrm/ abort-upgrade <var/old-version/ +<var/new-postrm/ abort-install <var/old-version/ +<var/new-postrm/ abort-install +</example> + +</enumlist> + +<item> +The new package's files are unpacked, overwriting any that may be on +the system already, for example any from the old version of the same +package or from another package (backups of the old files are left +around, and if anything goes wrong dpkg will attempt to put them back +as part of the error unwind). +<p> + +It is an error for a package to contains files which are on the system +in another package, unless <tt/Replaces/ is used (see +<ref id="replaces">). Currently the <tt/--force-overwrite/ flag is +enabled, downgrading it to a warning, but this may not always be the +case. +<p> + +Packages which overwrite each other's files produce behaviour which +though deterministic is hard for the system administrator to +understand. It can easily lead to `missing' programs if, for example, +a package is installed which overwrites a file from another package, +and is then removed again.<footnote>Part of the problem is due to what +is arguably a bug in <prgn/dpkg/.</footnote> + +<item> + +<enumlist> +<item> +If the package is being upgraded, call +<example> +<var/old-postrm/ upgrade <var/new-version/ +</example> + +<item> +If this fails, <prgn/dpkg/ will attempt: +<example> +<var/new-postrm/ failed-upgrade <var/old-version/ +</example> +Error unwind, for both cases: +<example> +<var/old-preinst/ abort-upgrade <var/new-version/ +</example> + +</enumlist> + +This is the point of no return - if <prgn/dpkg/ gets this far, it won't +back off past this point if an error occurs. This will leave the +package in a fairly bad state, which will require a successful +reinstallation to clear up, but it's when <prgn/dpkg/ starts doing +things that are irreversible. + +<item> +Any files which were in the old version of the package but not in the +new are removed. + +<item> +The new file list replaces the old. + +<item> +The new maintainer scripts replace the old. + +<item> +Any packages all of whose files have been overwritten during the +installation, and which aren't required for dependencies, are considered +to have been removed. For each such package, + +<enumlist> +<item> +<prgn/dpkg/ calls: +<example> +<var/disappearer's-postrm/ disappear \ + <var/overwriter/ <var/overwriter-version/ +</example> + +<item> +The package's maintainer scripts are removed. + +<item> +It is noted in the status database as being in a sane state, namely +not installed (any conffiles it may have are ignored, rather than +being removed by <prgn/dpkg/). Note that disappearing packages do not +have their prerm called, because <prgn/dpkg/ doesn't know in advance +that the package is going to vanish. + +</enumlist> + +<item> +Any files in the package we're unpacking that are also listed in the +file lists of other packages are removed from those lists. (This will +lobotomise the file list of the `conflicting' package if there is one.) + +<item> +The backup files made during installation, above, are deleted. + +<item> +The new package's status is now sane, and recorded as `unpacked'. Here +is another point of no return - if the conflicting package's removal +fails we do not unwind the rest of the installation; the conflicting +package is left in a half-removed limbo. + +<item> +If there was a conflicting package we go and do the removal actions +(described below), starting with the removal of the conflicting +package's files (any that are also in the package being installed +have already been removed from the conflicting package's file list, +and so do not get removed now). + +</enumlist> + +<sect>Details of configuration +<p> + +When we configure a package (this happens with <tt/dpkg --install/, or +with <tt/--configure/), we first update the conffiles and then call: +<example> +<var/postinst/ configure <var/most-recently-configured-version/ +</example> +<p> + +No attempt is made to unwind after errors during configuration. +<p> + +If there is no most recently configured version <prgn/dpkg/ will pass a +null argument; older versions of dpkg may pass +<tt><unknown></tt> (including the angle brackets) in this case. +Even older ones do not pass a second argument at all, under any +circumstances. + +<sect>Details of removal and/or configuration purging +<p> + +<enumlist> +<item> +<example> +<var/prerm/ remove +</example> + +<item> +The package's files are removed (except conffiles). + +<item> +<example> +<var/postrm/ remove +</example> + +<item> +All the maintainer scripts except the postrm are removed. +<p> + +If we aren't purging the package we stop here. Note that packages +which have no postrm and no conffiles are automatically purged when +removed, as there is no difference except for the <prgn/dpkg/ status. + +<item> +The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files, +<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed. + +<item> +<example> +<var/postrm/ purge +</example> + +<item> +The package's file list is removed. + +</enumlist> + +No attempt is made to unwind after errors during removal. + + +<chapt id="descriptions">Descriptions of packages - the +<tt/Description/ field +<p> + +The <tt/Description/ control file field is used by <prgn/dselect/ when +the user is selecting which packages to install and by <prgn/dpkg/ +when it displays information about the status of packages and so +forth. It is included on the FTP site in the <prgn/Packages/ files, +and may also be used by the Debian WWW pages. +<p> + +The description is intended to describe the program to a user who has +never met it before so that they know whether they want to install it. +It should also give information about the significant dependencies and +conflicts between this package and others, so that the user knows why +these dependencies and conflicts have been declared. +<p> + +The field's format is as follows: +<example> +Description: <var/single line synopsis/ + <var/extended description over several lines/ +</example> +<p> + +The synopsis is often printed in lists of packages and so forth, and +should be as informative as possible. Every package should also have +an extended description. +<p> + +<sect>Types of formatting line in the extended description +<p> + +<list> +<item> +Those starting with a single space are part of a paragraph. +Successive lines of this form will be word-wrapped when displayed. +The leading space will usually be stripped off. + +<item> +Those starting with two or more spaces. These will be displayed +verbatim. If the display cannot be panned horizontally the +displaying program will linewrap them `hard' (ie, without taking +account of word breaks). If it can they will be allowed to trail +off to the right. None, one or two initial spaces may be deleted, +but the number of spaces deleted from each line will be the same +(so that you can have indenting work correctly, for example). + +<item> +Those containing a single space followed by a single full stop +character. These are rendered as blank lines. This is the <em/only/ +way to get a blank line - see below. + +<item> +Those containing a space, a full stop and some more characters. These +are for future expansion. Do not use them. +</list> + +<sect>Notes about writing descriptions +<p> + +<em/Always/ start extended description lines with at least one +whitespace character. Fields in the control file and in the Packages +file are separated by field names starting in the first column, just +as message header fields are in RFC822. Forgetting the whitespace +will cause <prgn/dpkg-deb/<footnote>Version 0.93.23 or +later.</footnote> to produce a syntax error when trying to build the +package. If you force it to build anyway <prgn/dpkg/ will refuse to +install the resulting mess. +<p> + +<em/Do not/ include any completely <em/empty/ lines. These separate +different records in the Packages file and different packages in the +<tt>debian/control</> file, and are forbidden in package control +files. See the previous paragraph for what happens if you get this +wrong. +<p> + +The single line synopsis should be kept brief - certainly under 80 +characters. <prgn/dselect/ displays between 25 and 49 characters +without panning if you're using an 80-column terminal, depending on +what display options are in effect. +<p> + +Do not include the package name in the synopsis line. The display +software knows how to display this already, and you do not need to +state it. Remember that in many situations the user may only see +the synopsis line - make it as informative as you can. +<p> + +The extended description should describe what the package does and +how it relates to the rest of the system (in terms of, for +example, which subsystem it is which part of). +<p> + +The blurb that comes with a program in its announcements and/or +<prgn/README/ files is rarely suitable for use in a description. It +is usually aimed at people who are already in the community where the +package is used. The description field needs to make sense to anyone, +even people who have no idea about any of the +things the package deals with. +<p> + +Put important information first, both in the synopis and extended +description. Sometimes only the first part of the synopsis or of +the description will be displayed. You can assume that there will +usually be a way to see the whole extended description. +<p> + +You may include information about dependencies and so forth in the +extended description, if you wish. +<p> + +Do not use tab characters. Their effect is not predictable. +<p> + +Do not try to linewrap the summary (the part on the same line as the +field name <tt/Description/) into the extended description. This will +not work correctly when the full description is displayed, and makes +no sense where only the summary is available. + +<sect>Example description in control file for Smail +<p> + +<example> +Package: smail +Version: 3.1.29.1-13 +Maintainer: Ian Jackson <iwj10@cus.cam.ac.uk> +Recommends: pine | mailx | elm | emacs | mail-user-agent +Suggests: metamail +Depends: cron, libc5 +Conflicts: sendmail +Provides: mail-transport-agent +Description: Electronic mail transport system. + Smail is the recommended mail transport agent (MTA) for Debian. + . + An MTA is the innards of the mail system - it takes messages from + user-friendly mailer programs and arranges for them to be delivered + locally or passed on to other systems as required. + . + In order to make use of it you must have one or more user level + mailreader programs such as elm, pine, mailx or Emacs (which has Rmail + and VM as mailreaders) installed. If you wish to send messages other + than just to other users of your system you must also have appropriate + and VM as mailreaders) installed. If you wish to send messages other + than just to other users of your system you must also have appropriate + networking support, in the form of IP or UUCP. +</example> + +<chapt id="relationships">Declaring relationships between packages +<p> + +Packages can declare in their control file that they have certain +relationships to other packages - for example, that they may not be +installed at the same time as certain other packages, and/or that they +depend on the presence of others, or that they should overwrite files +in certain other packages if present. +<p> + +This is done using the <tt/Depends/, <tt/Recommends/, <tt/Suggests/, +<tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields. +<p> + +<sect>Syntax of relationship fields +<p> + +These fields all have a uniform syntax. They are a list of package +names separated by commas. +<p> + +In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/ +(the fields which declare dependencies of the package in which they +occur on other packages) these package names may also be lists of +alternative package names, separated by vertical bar symbols <tt/|/ +(pipe symbols). +<p> + +All the fields except <tt/Provides/ may restrict their applicability +to particular versions of each named package. This is done in +parentheses after each individual package name; the parentheses should +contain a relation from the list below followed by a version number, +in the format described in <ref id="versions">. +<p> + +The relations allowed are +<tt/<</, +<tt/<=/, +<tt/=/, +<tt/>=/ and +<tt/>>/ +for strictly earlier, earlier or equal, exactly equal, later or equal +and strictly later, respectively. The forms <tt/</ and <tt/>/ +were used to mean earlier/later or equal, rather than strictly +earlier/later, so they should not appear in new packages (though +<prgn/dpkg/ still supports them). +<p> + +Whitespace may appear at any point in the version specification, and +must appear where it's necessary to disambiguate; it is not otherwise +significant. For consistency and in case of future changes to +<prgn/dpkg/ it is recommended that a single space be used after a +version relationship and before a version number; it is usual also to +put a single space after each comma, on either side of each vertical +bar, and before each open parenthesis. +<p> + +For example: +<example> +Package: metamail +Version: 2.7-3 +Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh +</example> + +<sect>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/ +<p> + +These four fields are used to declare a dependency by one package on +another. They appear in the depending package's control file. +<p> + +All but <tt/Pre-Depends/ (discussed below) take effect <em/only/ when +a package is to be configured. They do not prevent a package being on +the system in an unconfigured state while its dependencies are +unsatisfied, and it is possible to replace a package whose +dependencies are satisfied and which is properly installed with a +different version whose dependencies are not and cannot be satisfied; +when this is done the depending package will be left unconfigured +(since attempts to configure it will give errors) and will not +function properly. +<p> + +For this reason packages in an installation run are usually all +unpacked first and all configured later; this gives later versions of +packages with dependencies on later versions of other packages the +opportunity to have their dependencies satisfied. +<p> + +Thus <tt/Depends/ allows package maintainers to impose an order in +which packages should be configured. + +<taglist> +<tag><tt/Depends/ +<item> + +This declares an absolute dependency. +<p> + +<prgn/dpkg/ will not configure +packages whose dependencies aren't satisfied. If it is asked to make +an installation which would cause an installed package's dependencies +to become unsatisfied it will complain<footnote>Current versions +(1.2.4) of <prgn/dpkg/ have a bug in this area which will cause some of +these problems to be ignored.</footnote>, unless +<tt/--auto-deconfigure/ is specified, in which case those packages +will be deconfigured before the installation proceeds. +<p> + +<prgn/dselect/ makes it hard for the user to select packages for +installation, removal or upgrade in a way that would mean that +packages' <prgn/Depends/ fields would be unsatisfied. The user can +override this if they wish, for example if they know that <prgn/dselect/ +has an out-of-date view of the real package relationships. +<p> + +The <tt/Depends/ field should be used if the depended-on package is +required for the depending package to provide a significant amount of +functionality. + +<tag><tt/Recommends/ +<item> +This declares a strong, but not absolute, dependency. +<p> + +<tt/Recommends/ is ignored by <prgn/dpkg/, so that users using the +command-line (who are presumed to know what they're doing) will not be +impeded. +<p> + +It is treated by <prgn/dselect/ exactly as <tt/Depends/ is; this makes +it hard for the user to select things so as to leave <tt/Recommends/ +fields unsatisfied, but they are able to do so by being persistent. +<p> + +The <tt/Recommends/ field should list packages that would be found +together with this one in all but unusual installations. + +<tag><tt/Suggests/ +<item> + +This is used to declare that one package may be more useful with one +or more others. Using this field tells the packaging system and the +user that the listed packages are be related to this one and can +perhaps enhance its usefulness, but that installing this one without +them is perfectly reasonable. +<p> + +<prgn/dselect/ will offer suggsted packages to the system administrator +when they select the suggesting package, but the default is not to +install the suggested package. + +<tag><tt/Pre-Depends/ +<item> + +This field is like <tt/Depends/, except that it also forces <prgn/dpkg/ +to complete installation of the packages named before even starting +the installation of the package which declares the predependency. +<p> + +<prgn/dselect/ checks for predependencies when it is doing an +installation run, and will attempt to find the packages which are +required to be installed first and do so in the right order. +<p> + +However, this process is slow (because it requires repeated +invocations of <prgn/dpkg/) and troublesome (because it requires +guessing where to find the appropriate files). +<p> + +For these reasons, and because this field imposes restrictions on the +order in which packages may be unpacked (which can be difficult for +installations from multipart media, for example), <tt/Pre-Depends/ +should be used sparingly, preferably only by packages whose premature +upgrade or installation would hamper the ability of the system to +continue with any upgrade that might be in progress. +<p> + +When the package declaring it is being configured, a +<tt/Pre-Dependency/ will be considered satisfied only if the depending +package has been correctly configured, just as if an ordinary +<tt/Depends/ had been used. +<p> + +However, when a package declaring a predependency is being unpacked +the predependency can be satisfied even if the depended-on package(s) +are only unpacked or half-configured, provided that they have been +configured correctly at some point in the past (and not removed or +partially removed since). In this case both the previously-configured +and currently unpacked or half-configured versions must satisfy any +version clause in the <tt/Pre-Depends/ field. + +</taglist> + +<sect1>Deconfiguration due to removal during bulk installations +<p> + +If <prgn/dpkg/ would like to remove a package due to a conflict, as +described above, but this would violate a dependency of some other +package on the system, <prgn/dpkg/ will usually not remove the +conflicting package and halt with an error. +<p> + +However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used +<prgn/dpkg/ will automatically `deconfigure' the package with the +problematic dependency, so that the conflicting package can be removed +and the package we're trying to install can be installed. If +<prgn/dpkg/ is being asked to install packages (rather than just +unpacking them) it will try to reconfigure the package when it has +unpacked all its arguments, in the hope that one of the other packages +it is installing will satisfy the problematic dependency. +<p> + +<prgn/dselect/ supplies this argument to <prgn/dpkg/ when it invokes it, +so that bulk installations proceed smoothly. + +<sect id="conflicts">Alternative packages - <tt/Conflicts/ and <tt/Replaces/ +<p> + +When one package declares a conflict with another <prgn/dpkg/ will +refuse to allow them to be installed on the system at the same time. +<p> + +If one package is to be installed, the other must be removed first - +if the package being installed is marked as replacing (<ref +id="replaces">) the one on the system, or the one on the system is +marked as deselected, or both packages are marked <tt/Essential/, then +<prgn/dpkg/ will automatically remove the package which is causing the +conflict, otherwise it will halt the installation of the new package +with an error. +<p> + +<prgn/dselect/ makes it hard to select conflicting packages, though the +user can override this if they wish. If they do not override it then +<prgn/dselect/ will select one of the packages for removal, and the user +must make sure it is the right one. In the future <prgn/dselect/ will +look for the presence of a <tt/Replaces/ field to help decide which +package should be installed and which removed. +<p> + +A package will not cause a conflict merely because its configuration +files are still installed; it must be at least half-installed. +<p> + +A special exception is made for packages which declare a conflict with +their own package name, or with a virtual package which they provide +(see below): this does not prevent their installation, and allows a +package to conflict with others providing a replacement for it. You +use this feature when you want the package in question to be the only +package providing something. +<p> + +A <tt/Conflicts/ entry should almost never have an `earlier than' +version clause. This would prevent <prgn/dpkg/ from upgrading or +installing the package which declared such a conflict until the +upgrade or removal of the conflicted-with package had been completed. +This aspect of installation ordering is not handled by <prgn/dselect/, +so that the use <tt/Conflicts/ in this way is likely to cause problems +for `bulk run' upgrades and installations. +<p> + + +<sect id="virtual">Virtual packages - <tt/Provides/ +<p> + +As well as the names of actual (`concrete') packages, the package +relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and +<tt/Conflicts/ may mention virtual packages. +<p> + +A virtual package is one which appears in the <tt/Provides/ control +file field of another package. The effect is as if the package(s) +which provide a particular virtual package name had been listed by +name everywhere were the virtual package name appears. +<p> + +If there are both a real and a virtual package of the same name then +the dependency may be satisfied (or the conflict caused) by either the +real package or any of the virtual packages which provide it. This is +so that, for example, supposing we have +<example> +Package: vm +Depends: emacs +</example> +and someone else releases an xemacs package they can say +<example> +Package: xemacs +Provides: emacs +</example> +and all will work in the interim (until a purely virtual package name +is decided on and the <tt/emacs/ and <tt/vm/ packages are changed to +use it). +<p> + +If a dependency or a conflict has a version number attached then only +real packages will be considered to see whether the relationship is +satisfied (or the prohibition violated, for a conflict) - it is +assumed that a real package which provides virtual package is not of +the `right' version. So, a <tt/Provides/ field may not contain +version numbers, and the version number of the concrete package which +provides a particular virtual package will not be looked at when +considering a dependency on or conflict with the virtual package name. +<p> + +If you want to specify which of a set of real packages should be the +default to satisfy a particular dependency on a virtual package, you +should list the real package as alternative before the virtual. +<p> + + +<sect id="replaces"><tt/Replaces/ - overwriting files and replacing packages +<p> + +The <tt/Replaces/ control file field has two purposes, which come into +play in different situations. +<p> + +Virtual packages (<ref id="virtual">) are not considered when looking +at a <tt/Replaces/ field - the packages declared as being replaced +must be mentioned by their real names. + +<sect1>Overwriting files in other packages +<p> + +Firstly, as mentioned before, it is usually an error for a package to +contains files which are on the system in another package, though +currently the <tt/--force-overwrite/ flag is enabled by default, +downgrading the error to a warning, +<p> + +If the overwriting package declares that it replaces the one +containing the file being overwritten then <prgn/dpkg/ will proceed, and +replace the file from the old package with that from the new. The +file will no longer be listed as `owned' by the old package. +<p> + +If a package is completely replaced in this way, so that <prgn/dpkg/ +does not know of any files it still contains, it is considered to have +disappeared. It will be marked as not wanted on the system (selected +for removal) and not installed. Any conffiles details noted in the +package will be ignored, as they will have been taken over by the +replacing package(s). The package's <prgn/postrm/ script will be run to +allow the package to do any final cleanup required. +See <ref id="mscriptsinstact">. +<p> + +In the future <prgn/dpkg/ will discard files which overwrite those from +another package which declares that it replaces the one being +installed (so that you can install an older version of a package +without problems). +<p> + +This usage of <tt/Replaces/ only takes effect when both packages are +at least partially on the system at once, so that it can only happen +if they do not conflict or if the conflict has been overridden. + +<sect1>Replacing whole packages, forcing their removal +<p> + +Secondly, <tt/Replaces/ allows <prgn/dpkg/ and <prgn/dselect/ to resolve +which package should be removed when a conflict - see +<ref id="conflicts">. This usage only takes effect when the two +packages <em/do/ conflict, so that the two effects do not interfere +with each other. +<p> + +<sect>Defaults for satisfying dependencies - ordering +<p> + +Ordering is significant in dependency fields. +<p> + +Usually dselect will suggest to the user that they select the package +with the most `fundamental' class (eg, it will prefer Base packages to +Optional ones), or the one that they `most wanted' to select in some +sense. +<p> + +In the absence of other information <prgn/dselect/ will offer a +default selection of the first named package in a list of +alternatives. +<p> + +However, there is no way to specify the `order' of several packages +which all provide the same thing, when that thing is listed as a +dependency. +<p> + +Therefore a dependency on a virtual package should contain a concrete +package name as the first alternative, so that this is the default. +<p> + +For example, consider the set of packages: + +<example> +Package: glibcdoc +Recommends: info-browser + +Package: info +Provides: info-browser + +Package: emacs +Provides: info-browser +</example> +<p> + +If <prgn/emacs/ and <prgn/info/ both have the same priority then +<prgn/dselect/'s choice is essentially random. Better would be +<example> +Package: glibcdoc +Recommends: info | info-browser +</example> +so that <prgn/dselect/ defaults to selecting the lightweight standalone +info browser. + + + +<chapt id="conffiles">Configuration file handling +<p> + +<prgn/dpkg/ can do a certain amount of automatic handling of package +configuration files. +<p> + +Whether this mechanism is appropriate depends on a number of factors, +but basically there are two approaches to any particular configuration +file. +<p> + +The easy method is to ship a best-effort configuration in the package, +and use <prgn/dpkg/'s conffile mechanism to handle updates. If the user +is unlikely to want to edit the file, but you need them to be able to +without losing their changes, and a new package with a changed version +of the file is only released infrequently, this is a good approach. +<p> + +The hard method is to build the configuration file from scratch in the +<prgn/postinst/ script, and to take the responsibility for fixing any +mistakes made in earlier versions of the package automatically. This +will be appropriate if the file is likely to need to be different on +each system. + +<sect>Automatic handling of configuration files by <prgn/dpkg/ +<p> + +A package may contain a control area file called <tt/conffiles/. This +file should be a list of filenames of configuration files needing +automatic handling, separated by newlines. The filenames should be +absolute pathnames, and the files referred to should actually exist in +the package. +<p> + +When a package is upgraded <prgn/dpkg/ will process the configuration +files during the configuration stage, shortly before it runs the +package's <prgn/postinst/ script, +<p> + +For each file it checks to see whether the version of the file +included in the package is the same as the one that was included in +the last version of the package (the one that is being upgraded +from); it also compares the version currently installed on the system +with the one shipped with the last version. +<p> + +If neither the user nor the package maintainer has changed the file, +it is left alone. If one or the other has changed their version, then +the changed version is preferred - ie, if the user edits their file, +but the package maintainer doesn't ship a different version, the +user's changes will stay, silently, but if the maintainer ships a new +version and the user hasn't edited it the new version will be +installed (with an informative message). If both have changed their +version the user is prompted about the problem and must resolve the +differences themselves. +<p> + +The comparisons are done by calculating the MD5 message digests of the +files, and storing the MD5 of the file as it was included in the most +recent version of the package. +<p> + +When a package is installed for the first time <prgn/dpkg/ will install +the file that comes with it, unless that would mean overwriting a file +already on the filesystem. +<p> + +However, note that <prgn/dpkg/ will <em/not/ replace a conffile that +was removed by the user (or by a script). This is necessary because +with some programs a missing file produces an effect hard or +impossible to achieve in another way, so that a missing file needs to +be kept that way if the user did it. +<p> + +Note that a package should <em/not/ modify a <prgn/dpkg/-handled +conffile in its maintainer scripts. Doing this will lead to +<prgn/dpkg/ giving the user confusing and possibly dangerous options +for conffile update when the package is upgraded. + +<sect>Fully-featured maintainer script configuration handling +<p> + +For files which contain site-specific information such as the hostname +and networking details and so forth, it is better to create the file +in the package's <prgn/postinst/ script. +<p> + +This will typically involve examining the state of the rest of the +system to determine values and other information, and may involve +prompting the user for some information which can't be obtained some +other way. +<p> + +When using this method there are a couple of important issues which +should be considered: +<p> + +If you discover a bug in the program which generates the configuration +file, or if the format of the file changes from one version to the +next, you will have to arrange for the postinst script to do something +sensible - usually this will mean editing the installed configuration +file to remove the problem or change the syntax. You will have to do +this very carefully, since the user may have changed the file, perhaps +to fix the very problem that your script is trying to deal with - you +will have to detect these situations and deal with them correctly. +<p> + +If you do go down this route it's probably a good idea to make the +program that generates the configuration file(s) a separate program in +<tt>/usr/sbin</>, by convention called <tt/<var/package/config/ and +then run that if appropriate from the post-installation script. The +<tt/<var/package/config/ program should not unquestioningly overwrite +an existing configuration - if its mode of operation is geared towards +setting up a package for the first time (rather than any arbitrary +reconfiguration later) you should have it check whether the +configuration already exists, and require a <tt/--force/ flag to +overwrite it. + + + +<chapt id="alternatives">Alternative versions of an interface - +<prgn/update-alternatives/ +<p> + +When several packages all provide different versions of the same +program or file it is useful to have the system select a default, but +to allow the system administrator to change it and have their +decisions respected. +<p> + +For example, there are several versions of the <prgn/vi/ editor, and +there is no reason to prevent all of them from being installed at +once, each under their own name (<prgn/nvi/, <prgn/vim/ or whatever). +Nevertheless it is desirable to have the name <tt/vi/ refer to +something, at least by default. +<p> + +If all the packages involved cooperate, this can be done with +<prgn/update-alternatives/. +<p> + +Each package provides its own version under its own name, and calls +<prgn/update-alternatives/ in its postinst to register its version +(and again in its prerm to deregister it). +<p> + +See the manpage <manref name=update-alternatives section=8> for +details. +<p> + +If <prgn/update-alternatives/ does not seem appropriate you may wish +to consider using diversions instead. + + +<chapt id="diversions">Diversions - overriding a package's version of a file +<p> + +It is possible to have <prgn/dpkg/ not overwrite a file when it +reinstalls the package it belongs to, and to have it put the file from +the package somewhere else instead. +<p> + +This can be used locally to override a package's version of a file, or +by one package to override another's version (or provide a wrapper for +it). +<p> + +Before deciding to use a diversion, read <ref id="alternatives"> to +see if you really want a diversion rather than several alternative +versions of a program. +<p> + +There is a diversion list, which is read by <prgn/dpkg/, and updated +by a special program <prgn/dpkg-divert/. Please see <manref +name=dpkg-divert section=8> for full details of its operation. +<p> + +When a package wishes to divert a file from another, it should call +<prgn/dpkg-divert/ in its preinst to add the diversion and rename the +existing file. For example, supposing that a <prgn/smailwrapper/ +package wishes to install a wrapper around <tt>/usr/sbin/smail</>: +<example> +if [ install = "$1" ]; then + dpkg-divert --package smailwrapper --add --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail +fi +</example> +Testing <tt/$1/ is necessary so that the script doesn't try to add the +diversion again when <prgn/smailwrapper/ is upgraded. The +<tt/--package smailwrapper/ ensures that <prgn/smailwrapper/'s copy of +<tt>/usr/sbin/smail</> can bypass the diversion and get installed as +the true version. +<p> + +The postrm has to do the reverse: +<example> +if [ remove = "$1" ]; then + dpkg-divert --package smailwrapper --remove --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail +fi +</example> +<p> + +Do not attempt to divert a file which is vitally important for the +system's operation - when using <prgn/dpkg-divert/ there is a time, +after it has been diverted but before <prgn/dpkg/ has installed the +new version, when the file does not exist. + + +<chapt id="sharedlibs">Shared libraries +<p> + +Packages containing shared libraries must be constructed with a little +care to make sure that the shared library is always available. This +is especially important for packages whose shared libraries are +vitally important, such as the libc. +<p> + +Firstly, your package should install the shared libraries under their +normal names. For example, the <prgn/libgdbm1/ package should install +<tt/libgdbm.so.1.7.3/ as <tt>/usr/lib/libgdbm.so.1.7.3</tt>. The +files should not be renamed or relinked by any prerm or postrm +scripts; <prgn/dpkg/ will take care of renaming things safely without +affecting running programs, and attempts to interfere with this are +likely to lead to problems. +<p> + +Secondly, your package should include the symlink that <prgn/ldconfig/ +would create for the shared libraries. For example, the <prgn/libgdbm1/ +package should include a symlink from <tt>/usr/lib/libgdbm.so.1</tt> +to <tt/libgdbm.so.1.7.3/. This is needed so that <prgn/ld.so/ can find +the library in between the time <prgn/dpkg/ installs it and +<prgn/ldconfig/ is run in the <prgn/postinst/ script. Futhermore, and <em/this +is very important/, the symlink must be placed before the library it +points to in the <tt/.deb/ file. Currently the way to ensure the +ordering is done properly is to create the symlink in the appropriate +<tt>debian/tmp/.../lib</tt> directory before installing the library +when you build the package. +<p> + +If you do the above your package does not need to call <prgn/ldconfig/ +in its maintainer scripts. It is especially important not to call +<prgn/ldconfig/ in the postrm or preinst scripts in the case where the +package is being upgraded (see the programmer's manual), as +<prgn/ldconfig/ will see the temporary names that <prgn/dpkg/ uses for the +files while it is installing them and will make the shared library +links point to them, just before <prgn/dpkg/ continues the installation +and removes the links! + + + +<chapt id="sysvinit">Configuration of <prgn/init/ +<p> + +<sect>Introduction to the <tt/init.d/ scheme +<p> + +The <tt>/etc/init.d</> directory contains the scripts executed by +<prgn/init/ when init state (or `runlevel') is changed (see <manref +name=init section=8>). +<p> + +These scripts are be referenced by symbolic links in the +<tt>/etc/rc<var/n/.d</> directories. When changing runlevels, init +looks in the directory <tt>/etc/rc<var/n/.d</> for the scripts it +should execute, where <var/n/ is the runlevel that is being changed +to. +<p> + +The names of the links all have the form <tt/S<var/mm/<var/script// or +<tt/K<var/mm/<var/script// where <var/mm/ is a two-digit number and +<var/script/ is the name of the script (this should be the same as the +name of the actual script in <tt>/etc/init.d</>. + +When <prgn/init/ changes runlevel first the targets of the links whose +names starting with a <tt/K/ are executed, each with the single +argument <tt/stop/, followed by the scripts prefixed with an <tt/S/, +each with the single argument <tt/start/. The <tt/K/ links are +responsible for killing services and the <tt/S/ link for starting +services upon entering the runlevel. +<p> + +For example, if we are changing from runlevel 2 to runlevel 3, init +will first execute all of the <tt/K/ prefixed scripts it finds in +<tt>/etc/rc3.d</>, and then all of the <tt/S/ prefixed scripts. The +links starting with <tt/K/ will cause the referred-to file to be +executed with an argument of <tt/stop/, and the <tt/S/ links with an +argument of <tt/start/. +<p> + +The two-digit number <var/mm/ is used to decide which order to start +and stop things in - low-numbered links have their scripts run first. +For example, the <tt/K20/ scripts will be executed before the <tt/K30/ +scripts. This is used when a certain service must be started before +another. For example, the name server <prgn/bind/ might need to be +started before the news server <prgn/inn/ so that <prgn/inn/ can set +up its access lists. In this case, the script that starts <prgn/bind/ +should have a lower number than the script that starts <prgn/inn/ so +that it runs first: +<example> +/etc/rc2.d/S17bind +/etc/rc2.d/S70inn +</example> + +<sect>Writing <tt/init.d/ scripts +<p> + +Packages can and should place scripts in <tt>/etc/init.d</> to start +or stop services at boot time or during a change of runlevel. These +scripts should be named <tt>/etc/init.d/<var/package/</>, and they +should accept one argument, saying what to do: <tt/start/, meaning to +starts the service, or <tt/stop/, to stop the service. Optionally +they can support <tt/reload/ which causes the configuration to be +reloaded. +<p> + +The <tt/init.d/ scripts should ensure that they will behave sensibly +if invoked with <tt/start/ when the service is already running, or +with <tt/stop/ when it isn't, and that they don't kill +unfortunately-named user processes. The best way to achieve this is +usually to use <prgn/start-stop-daemon/. +<p> + +These scripts should not fail obscurely when the configuration files +remain but the package has been removed, as the default in <prgn/dpkg/ +is to leave configuration files on the system after the package has +been removed. Only when it is executed with the <tt/--purge/ option +will dpkg remove configuration files. Therefore, you should include a +<tt/test/ statement at the top of the script, like this: +<example> +test -f <var/program-executed-later-in-script/ || exit 0 +</example> + +<sect>Managing the <tt/rc<var/n/.d/ links - <prgn/update-rc.d/ +<p> + +A program is provided, <prgn/update-rc.d/, to make it easier for +package maintainers to arrange for the proper creation and removal of +<tt>/etc/rc<var/n/.d</> symbolic links from their postinst and postrm +scripts. +<p> + +You should use this script to make changes to <tt>/etc/rc<var/n/.d</> +and <em/never/ include any <tt>/etc/rc<var/n/.d</> symbolic links in +the actual archive. +<p> + +By default <prgn/update-rc.d/ will start services in each of the +multi-user state runlevels (2, 3, 4, and 5) and stop them in the halt +runlevel (0), the single-user runlevel (1) and the reboot runlevel +(6). The system administrator will have the opportunity to customize +runlevels by simply adding, moving, or removing the symbolic links in +<tt>/etc/rc<var/n/.d</>. +<p> + +To get the default behaviour for your package, put in your postinst +script +<example> +update-rc.d <var/package/ default >/dev/null +</example> +and in your postrm +<example> +if [ purge = "$1" ]; then + update-rc.d <var/package/ remove >/dev/null +fi +</example> +<p> + +This will use a default sequence number of 20. If it does not matter +when or in which order the script is run, use this default. If it +does, then you should talk to the maintainer of the <prgn/sysvinit/ +package or post to <tt>debian-devel</>, and they will help you choose +a number. +<p> + +For more information about using <tt/update-rc.d/, please consult its +manpage <manref name=update-rc.d section=8>. + +<sect>Boot-time initialisation - <tt/rc.boot/ +<p> + +There is another directory, <tt>/etc/rc.boot</>, which contains +scripts which are run once per machine boot. This facility is +provided for initialisation of hardware devices, cleaning up of +leftover files, and so forth. +<p> + +For example, the <prgn/kbd/ package provides a script here for +initialising the keyboard layout and console font and mode. +<p> + +The files in <tt>/etc/rc.boot</> should <em/not/ be links into +<tt>/etc/init.d</> - they should be the scripts themselves. +<p> + +<tt/rc.boot/ should <em/not/ be used for starting general-purpose +daemons and similar activities. This should be done using the +<tt/rc<var/n/.d/ scheme, above, so that the services can be started +and stopped cleanly when the runlevel changes or the machine is to be +shut down or rebooted. + +<sect>Notes +<p> + +<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in +the <tt/.deb/ filesystem archive! <em/This will cause problems!/ +You should create them with <prgn/update-rc.d/, as above. +<p> + +<em/Do not/ include the <tt>/etc/rc<var/n/.d/*</> symbolic links in +<prgn/dpkg/'s conffiles list! <em/This will cause problems!/ +<em/Do/, however, include the <tt>/etc/init.d</> scripts in conffiles. + +<sect>Example +<p> + +The <prgn/bind/ DNS (nameserver) package wants to make sure that the +nameserver is running in multiuser runlevels, and is properly shut +down with the system. It puts a script in <tt>/etc/init.d</>, naming +the script appropriately <tt/bind/. As you can see, the script +interprets the argument <tt/reload/ to send the nameserver a <tt/HUP/ +signal (causing it to reload its configuration); this way the user can +say <tt>/etc/init.d/bind reload</> to reload the nameserver. +<p> + +<example> +#!/bin/sh +# Original version by Robert Leslie <rob@mars.org>, edited by iwj +test -x /usr/sbin/named || exit 0 +case "$1" in + start) + test -f /etc/named.boot -a -f /var/named/boot.options || exit 0 + start-stop-daemon --start --verbose --exec /usr/sbin/named + ;; + stop) + start-stop-daemon --stop --verbose \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + ;; + reload) + start-stop-daemon --stop --signal 1 --verbose \ + --pidfile /var/run/named.pid --exec /usr/sbin/named + ;; + *) + echo "Usage: /etc/init.d/bind {start|stop|reload}" >&2 + exit 1 + ;; +esac +exit 0 +</example> +<p> + +Another example on which to base your <tt>/etc/init.d</> scripts is in +<tt>/etc/init.d/skeleton</>. +<p> + +If this package is happy with the default setup from +<prgn/update-rc.d/, namely an ordering number of 20 and having named +running in all runlevels, it can say in its postinst: +<example> +update-rc.d bind default >/dev/null +</example> +And in its postrm, to remove the links when the package is purged: +<example> +if [ purge = "$1" ]; then + update-rc.d acct remove >/dev/null +fi +</example> + + + +<chapt id="methif"><prgn/dselect/'s interface to its installation methods +<p> + +<prgn/dselect/ calls scripts from its installation methods when it +needs to actually access data from the distribution. The core program +<prgn/dselect/ itself just calls these scripts and provides the +package and access method selection interfaces. The installation +methods are responsible for invoking <prgn/dpkg/ as appropriate. +<p> + +Each installation method has three scripts: +<list compact> +<item>Setup installation parameters. +<item>Update list of available packages. +<item>Install. +</list> +<p> + +<prgn/dselect/ searches for methods in <tt>/usr/lib/dpkg/methods</> +and <tt>/usr/local/lib/dpkg/methods</>. + +<sect>Functions of the method scripts +<p> + +The setup script is run just after the user has chosen an installation +method. It should prompt the user for parameters like the site to +NFS-mount or FTP from, the directory to use, or the directory or +filesystem where the <tt/.deb/ files can be found, or the tape or +floppy device to install from. It should store the responses under +<tt>/var/lib/dpkg/methods</> - see below. If no available +packages list is available it should perhaps offer to scan the +available packages. +<p> + +The update script should obtain a list of available packages if +possible, and run <tt/dpkg --update-avail/, <tt/dpkg --merge-avail/ +and/or <tt/dpkg --forget-old-unavail/ to load it into <prgn/dpkg/ and +<prgn/dselect/'s database of available packages. If no packages list +was available and the user was offered and accepted the option of +scanning the actual files available this scan should be done here, +using <tt/dpkg --record-avail/. +<p> + +The install script should feed all the available <tt/.deb/ files to +<tt/dpkg --iGOEB/ (this is equivalent to <tt/dpkg --install +--refuse-downgrade --selected-only --skip-same-version +--auto-deconfigure/). The <tt/-R/ (<tt/--recursive/) option for +traversing subdirectories may also be useful here). +<p> + +If any of these scripts needs to display a message for the user, it +should wait for the user to hit `return' before exiting so that +dselect doesn't immediately rewrite the screen. +<p> + +If a method script succeeds (returns a zero exit status) +<prgn/dselect/ will return immediately to the main menu, with the +`next' option highlighted ready for the user to select it. If it +fails <prgn/dselect/ will display a message and wait for the user to +hit return. + +<sect>Location and arguments of the method scripts +<p> + +A set of scripts (henceforth known as a group) may provide several +methods on the `main menu' with different behaviour. For example, +there might be a generic get-packages-by-FTP group which might provide +methods in the main menu for installation directly from one of the +Debian mirror sites as well as for installation from a user-specified +site. +<p> + +Each group of methods implemented by the same set of scripts should +have a subdirectory <tt>/usr/lib/dpkg/methods/<var/group/</> or +<tt>/usr/local/lib/dpkg/methods/<var/group/</>, containing: +<taglist compact> +<tag><tt/names/ +<item>a list of user-visible methods provided by these scripts. +<tag><tt/setup/ +<tag><tt/update/ +<tag><tt/install/ +<item>executable programs, the scripts themselves. +<tag><tt/desc.<var/option// +<item>description file. +</taglist> +<p> + +<tt/names/ will be formatted as a list of lines, each containing: +<example> +<var/sequence/ <var/method/ <var/summary/ +</example> +<p> + +<var/sequence/ is a two-digit number that will be used much like +<tt/rc.d/ prefixes to control the order in the main menu. If in doubt +use 50. +<p> + +<var/method/ is a name which is displayed by <prgn/dselect/ as the +name of the method, and which will be passed to <tt/setup/, +<tt/update/ and <tt/unpack/ as their first argument. +<p> + +<var/summary/ is the brief description string for <prgn/dselect/'s menu. +<p> + +Each of the three scripts gets the same three arguments: <var/vardir/, +<var/group/ and <var/method/. <var/vardir/ is the base directory for +storing <prgn/dpkg/ and <prgn/dselect/'s state, usually +<tt>/var/lib/dpkg</>; this is passed in so that the <tt/--admindir/ +option to <prgn/dselect/ is honoured). +<p> + +Each option may have an extended description in +<tt/desc.<var/option//. This should be formatted like the extended +description part of a <tt/Description/ field entry <em/shifted one +character to the left/. +<p> + +<tt><var/vardir//methods</> will exist, and a method group may use a +<tt><var/vardir//methods/<var/group/</> directory to store its state. +<p> + +The group name and method name must follow the rules for C identifiers. + +</book> diff --git a/doc/sgml/programmer.sgml b/doc/sgml/programmer.sgml deleted file mode 100644 index e6f27ae9..00000000 --- a/doc/sgml/programmer.sgml +++ /dev/null @@ -1,1443 +0,0 @@ -<!doctype linuxdoc system "./linuxdoc.dtd" > - -<!-- - Debian Linux dpkg package installation tool. - Programmers' manual. - Copyright (C)1996 Ian Jackson; released under the terms of the GNU - General Public License, version 2 or (at your option) any later. - --> - -<article> - -<title><tt/dpkg/ Programmers' manual -<author>Ian Jackson, <tt/ijackson@gnu.ai.mit.edu/ -<date>1st June 1996 -<abstract> -This manual describes the technical aspects of creating Debian binary -packages. It describes how to use utilities like <tt/install-info/. -It also documents the interface between <tt/dselect/ and its access -method scripts. It does not deal with the Debian Project policy -requirements, and it assumes familiarity with <tt/dpkg/'s functions -from the system administrator's perspective. -</abstract> - -<toc> - -<!-- Describes the technical interface between a package and dpkg. -How to use -update-rc.d, diversions, update-alternatives, install-info in a -package. How to safely put shared libraries in a package. Details of -dpkg's handling of individual files. -Sections on when to use which feature (eg Replaces -vs. Replaces/Conflicts vs. update-alternatives vs. diversions) -Cross-references to the policy document (see below) where appropriate. -Description of the interface between dselect and its access methods. -Hints on where to start with a new package (ie, the hello package). -What to do about file aliasing. ---> - -<sect>Scope of this manual -<p> - -This manual describes the technical aspects of creating Debian binary -packages (<tt/.deb/ files.). It documents the behaviour of the -package management programs <tt/dpkg/, <tt/dselect/ et al and and the -way they interact with packages. -<p> - -It documents the utility programs which are provided with <tt/dpkg/ -for managing various system configuration and similar issues (such as -<tt/update-rc.d/ and <tt/install-info/. - -It also documents the interaction between <tt/dselect/'s core and the -access method scripts it uses to actually install the selected -packages, and describes how to create a new access method. -<p> - -It does <em/not/ describe the policy requirements imposed on Debian -packages, such as the permissions on files and directories, -documentation requirements, upload procedure, and so on. You should -see the Debian packaging policy manual for these details. (Many of -them will probably turn out to be helpful even if you don't plan to -upload your package and make it available as part of the -distribution.) -<p> - -It is assumed that the reader is reasonably familiar with the -<tt/dpkg/ System Administrators' manual. -<p> - -The Debian version of the FSF's GNU hello program is provided as an -example for people wishing to create Debian packages. -<p> - -<em>Note that this document is not yet complete !</em> - -<sect>Binary package format -<p> - -<tt/dpkg/ is a suite of programs for creating binary package files and -installing and removing them on Unix systems.<footnote><tt/dpkg/ is -targetted primarily at Debian Linux, but may work or be ported to -other systems.</footnote> -<p> - -The binary package files' contents may be architecture-independent, -but they usually aren't. They aren't designed for the management of -program source code (though examples of this are provided as part of -some packages by way of documentation). -<p> - -The binary package has two main sections: the first part consists of -various control information files and scripts used by <tt/dpkg/ when -installing and removing. -<p> - -The second part is an archive (currently a <tt/tar/ archive) -containing files and directories to be installed. See <ref -id="controlarea">. -<p> - -In the future binary packages may also contain other components, such -as checksums and digital signatures. -<p> - - -<sect1>Creating package files -- <tt/dpkg-deb/ -<p> - -All manipulation of binary package files is done by <tt/dpkg-deb/; -it's the only program that has knowledge of the format. -(<tt/dpkg-deb/ may be invoked by calling <tt/dpkg/, as <tt/dpkg/ will -spot that the options requested are appropriate to <tt/dpkg-deb/ and -invoke that instead with the same arguments.) -<p> - -In order to create a binary package you must make a directory tree -which contains all the files and directories you want to have in the -filesystem data part of the package. -<p> - -They should have the locations (relative to the root of the directory -tree you're constructing) ownerships and permissions which you want -them to have on the system when they are installed. -<p> - -With current versions of <tt/dpkg/ the uid/username and gid/groupname -mappings for the users and groups being used should be the same on the -system where the package is built and the one where it is installed. -<p> - -You need to add one special directory to the root of the miniature -filesystem tree you're creating: <tt/DEBIAN/. It should contain the -control information files, notably the main package control file (see -<ref id="controlarea">). -<p> - -The <tt/DEBIAN/ directory will not appear in the filesystem archive of -the package, and so won't be installed by <tt/dpkg/ when the package -is installed. -<p> - -When you've prepared the package, you should invoke:<!--var--> -<example> -dpkg --build <it/directory/ -</example> -<p> - -This will build the package in <var/directory/<tt/.deb/. -(<tt/dpkg/ knows that <tt/--build/ is a <tt/dpkg-deb/ option, so it -invokes <tt/dpkg-deb/ with the same arguments to build the package.) -<p> - -See the manpage for <tt/dpkg-deb/ for details of how to examine the -contents of this newly-created file. You may find the output of -following commands enlightening: -<example> -dpkg-deb --info <var/filename/<tt/.deb/ -dpkg-deb --contents <var/filename/<tt/.deb/ -</example> - -<sect1>Package control information files<label id="controlarea"> -<p> - -The control information portion of a binary package is a collection of -files with names known to <tt/dpkg/. It will treat the contents of -these files specially - some of them contain information used by -<tt/dpkg/ when installing or removing the package; others are scripts -which the package maintainer wants <tt/dpkg/ to run. -<p> - -It is possible to put other files in the package control area, but -this is not generally a good idea (though they will largely be -ignored). -<p> - -Here is a brief list of the control info files supported by <tt/dpkg/ -and a summary of what they're used for. - -<descrip> - -<tag/<tt/control// - -This is the key description file used by <tt/dpkg/. It specifies the -package's name and version, gives its description for the user, states -its relationships with other packages, and so forth. -See <ref id="controlfile">. - -<tag><tt/postinst/, <tt/preinst/, <tt/postrm/, <tt/prerm/</tag> - -These are exectuable files (usually scripts) which <tt/dpkg/ runs -during installation, upgrade and removal of packages. They allow the -package to deal with matters which are particular to that package or -require more complicated processing than that provided by <tt/dpkg/. -Details of when and how they are called are in -<ref id="maintainerscripts">. - -<tag/<tt/conffiles// - -This file contains a list of configuration files which are to be -handled automatically by <tt/dpkg/ (see <ref id="conffiles">). Note -that not necessarily every configuration file should be listed here. - -</descrip> - -<sect1>The main control information file: <tt/control/<label id="controlfile"> -<p> - -The most important control information file used by <tt/dpkg/ when it -installs a package is <tt/control/. It contains all the package's -`vital statistics'. -<p> - -It is a series of fields and values; each field consists of a name, -followed by a colon and the value. It ends at the end of the line. -Horizontal whitespace (spaces and tabs) may occur before or after the -value and is ignored there; it is conventional to put a single space -after the colon. Many of the fields have a syntax where whitespace is -not significant. -<p> - -Some fields' values may span several lines; in this case each -continuation line <em/must/ start with a space or tab. Any trailing -spaces or tabs at the end of individual lines of a field value are -ignored. -<p> - -Field names are not case-sensitive, but it is usual to capitalise the -fields as shown below (usually using a form of mixed case). -<p> - -Blank lines, or lines consisting only of spaces and tabs, are not allowed. -<p> - - -Here is a list of the fields which are permitted in packages, together -with a description of the purposes and syntax of each and or a pointer -to further information if appropriate. -<p> - -It is important to note that there are several fields which are -optional as far as <tt/dpkg/ is concerned, but which must appear in -every Debian package, or whose omission may cause problems. When -writing the control file for a Debian package you <em/must/ read the -Debian policy manual in conjuction with the list below. - -<sect2>List of package control file fields -<p> - -<descrip> - -<tag/<tt/Package// - -The name of the package. Package names consist of the alphanumerics, -plus, minus and dot. They must be at least two characters and must -start with an alphanumeric. In current versions of dpkg they are sort -of case-sensitive; use lowercase package names unless the package -you're building (or referring to, in other fields) is already using -uppercase. -<p> - -This field is mandatory. - -<tag/<tt/Version// - -This lists the package's version number - see <ref id="versions">. - -This field is mandatory. - -<tag/<tt/Architecture// - -This is the architecture string; it is a single word for the CPU -architecture, and <tt/dpkg/ will check it against its own compiled-in -value before it installs a package. The special value <tt/all/ -indicates that the package is architecture-independent. -<p> - -The value for this field can be obtained using -<example> -dpkg --print-architecture -</example> -This actually invokes -<example> -gcc --print-libgcc-file-name -</example> -and parses and decomposes the output and looks the CPU type from the -GCC configuration in a table in <tt/dpkg/. This is so that it will -work if you're cross-compiling. -<p> - -There is a separate option, <tt/--print-installation-architecture/, -for finding out what architecture <tt/dpkg/ is willing to install. -This information is also in the output of <tt/dpkg --version/. -<p> - -This field should appear in all packages, though <tt/dpkg/ doesn't -require it yet so that old packages can still be installed. - -<tag/<tt/Maintainer// - -The package maintainer's name and email address. The name should come -first, then the email address inside angle brackets <tt/<>/ (in -RFC822 format). -<p> - -If the maintainer's name contains a full stop then the whole field -will not work directly as an email address due to a misfeature in the -syntax for addresses; a program using this field as an address must -check for this and reverse the components if necessary (for example by -putting the name in round brackets or quotes, and perhaps moving it to -the end). - -This feature is optional as far as <tt/dpkg/ is concerned, but -<tt/dpkg-deb/ will warn if it is missing. - -<tag><tt/Depends/, <tt/Pre-Depends/, <tt/Recommends/, <tt/Suggests/ -<tt/Conflicts/, <tt/Provides/, <tt/Replaces/</tag> - -These fields describe the package's relationships with other packages. -Their syntax and semantics are described in <ref id="depconoverwr">. - -<tag/<tt/Source// - -This field identifies the source package name, primarily for the -benefit of humans reading the control file rather than <tt/dpkg/. It -consists solely of the source package name; it may be omitted when the -source package has the same name as the binary package. - -This field is optional as far as <tt/dpkg/ is concerned. - -<tag/<tt/Description// - -This field contains a description of the package, in a special format. -<p> - -It is very important that you read <ref id="descriptions">. - -<tag/<tt/Essential// - -This is a boolean field. If set to <tt/yes/ then <tt/dpkg/ and -<tt/dselect/ will refuse to remove the package (though it can be -upgraded and/or replaced). The other possible value is <tt/no/, which -is the same as not having the field at all. -<p> - -This field is optional. - -<tag/<tt/Priority// - -This specifies the `priority' of the package; this represents how -important that it is that the user have it installed. -<p> - -This value isn't used by <tt/dpkg/, but only by <tt/dselect/ when it -sorts packages and selects defaults. See the <tt/dpkg/ System -Administrator's Manual for details of the values it can take, and the -Debian Policy Manual for the criteria for selecting the priority for a -Debian package. -<p> - -<tt/dpkg/ and <tt/dselect/ will only use the value from a <tt/.deb/ -file if they have no other information; a priority value listed in a -<tt/Packages/ file will always take precedence. This field is -optional as far as <tt/dpkg/ is concerned. - -<tag/<tt/Section// - -This specifies the `section' of the package, namely the application -area or group of packages which contain it. The value is a simple -string, usually from a set chosen by the distribution maintainers. -<p> - -The section isn't used at all except by <tt/dselect/, which only uses -it for sorting packages in the selection display and not even for -choosing defaults. -<p> - -Just as with <tt/Priority/, this field is optional as far as <tt/dpkg/ -is concerned, and the value from a package file is used only as a last -resort. - -</descrip> - -<sect2>List of other control fields -<p> - -There are several other fields which are used elsewhere by parts of -the system. These should not appear in package control files. - -<sect3>Status fields -<p> - -These fields appear in <tt/dpkg/'s internal status file; they are also -printed by <tt/dpkg --status/ and can be seen in <tt/dselect/ by -selecting the installed control info display. - -<p> - -<descrip> - -<tag/<tt/Status// - -This field in <tt/dpkg/'s status file records whether the user wants a -package installed, removed or left alone, whether it is broken -(requiring reinstallation) or not and what its current state on the -system is. Each of these pieces of information is a single word. - -<tag/<tt/Config-Version// - -If a package is not installed or not configured, this field in -<tt/dpkg/'s status file records the last version of the package which -was successfully configured. - -<tag/<tt/Conffiles// - -This field in <tt/dpkg/'s status file contains information about the -automatically-managed configuration files held by a package. Let me -emphasise that this field should <em/not/ appear in a package ! - -</descrip> - -<sect4><tt/Packages/ file (available package) fields -<p> - -These fields are found in <tt/Packages/ files (lists of packages -available for installation, which are generated by the distribution -maintainers and used principally by <tt/dselect/) and in <tt/dpkg/'s -database of available packages (which can be inspected using -<tt/dpkg --print-avail/ or by selecting the `available control -information' in <tt/dselect/. - -<p> - -<descrip> - -<tag><tt/Filename/, <tt/MSDOS-Filename/</tag> - -These fields in <tt/Packages/ files give the filename(s) of (the parts -of) a package in the distribution directories, relative to the root of -the Debian hierarchy. If the package has been split into several -parts the parts are all listed in order, separated by spaces. - -<tag><tt/Size/, <tt/MD5sum/</tag> - -These fields in <tt/Packages/ files give the size (in bytes, expressed -in decimal) and MD5 checksum of the file(s) which make(s) up a binary -package in the distribution. If the package is split into several -parts the values for the parts are listed in order, separated by -spaces. - -</descrip> - -<sect4>Obsolete fields -<p> - -These are still recognised by <tt/dpkg/ but should not appear anywhere -any more. - -<descrip> - -<tag><tt/Revision/, <tt/Package-Revision/, <tt/Package_Revision/</tag> - -The Debian revision part of the package version was at one point in a -separate control file field. This field went through several names. - -<tag/Recommended/ Old name for <tt/Recommends/. -<tag/Optional/ Old name for <tt/Suggests/. -<tag/Class/ Old name for <tt/Priority/. - -</descrip> - -<sect1>Version numbering<label id="versions"> -<p> - -Every package has a version number, in its <tt/Version/ control file -field. -<p> - -<tt/dpkg/ imposes an ordering on version numbers, so that it can tell -whether packages are being up- or downgraded and so that <tt/dselect/ -can tell whether a package it finds available is newer than the one -installed on the system. The version number format has the most -significant parts (as far as comparison is concerned) at the -beginning. -<p> - -The version number format is: -&lsqb<var/epoch/<tt/:/]<var/upstream-version/[<tt/-/<var/debian-revision/]. -<p> - -The three components here are: - -<descrip> - -<tag/<var/epoch// - -This is a single unsigned integer, which should usually be small. It -may be omitted, in which case it defaults to zero. If it is omitted -then the <var/upstream-version/ may not contain any colons. -<p> - -It is provided to allow mistakes in the version numbers of older -versions of a package, and also a package's previous version numbering -schemes, to be left behind. -<p> - -<tt/dpkg/ will not usually display the epoch unless it is essential -(non-zero, or if the <var/upstream-version/ contains a colon); -<tt/dselect/ does not display epochs at all in the main part of the -package selection display. - -<tag/<var/upstream-version// - -This is the main part of the version. It is usually version number of -the original (`upstream') package of which the <tt/.deb/ file has been -made, if this is applicable. Usually this will be in the same format -as that specified by the upstream author(s); however, it may need to -be reformatted to fit into <tt/dpkg/'s format and comparison scheme. -<p> - -The comparison behaviour of <tt/dpkg/ with respect to the -<var/upstream-version/ is described below. The <var/upstream-version/ -portion of the version number is mandatory. - -<tag/<var/debian-revision// - -This part of the version represents the version of the modifications -that were made to the package to make it a Debian binary package. It -is in the same format as the <var/upstream-version/ and <tt/dpkg/ -compares it in the same way. -<p> - -It is optional; if it isn't present then the <var/upstream-version/ -should not contain a hyphen. This format represents the case where a -piece of software was written specifically to be turned into a Debian -binary package, and so there is only one `debianization' of it and -therefore no version indication is require there. -<p> - -It is conventional to restart the <var/debian-revision/ at <tt/1/ each -time the <var/upstream-version/ is increased. -<p> - -<tt/dpkg/ will break the <var/upstream-version/ and -<var/debian-revision/ apart at the last hyphen in the string. The -absence of a <var/debian-revision/ compares earlier than the presence -of one (but note that the <var/debian-revision/ is the least -significant part of the version number). - -</descrip> - -The <var/upstream-version/ and <var/debian-revision/ parts are -compared by <tt/dpkg/ using the same algorithm: -<p> - -The strings are compared from left to right. -<p> - -First the initial part of each string consisting entirely of non-digit -characters is determined. These two parts (one of which may be empty) -are compared lexically. If a difference is found it is returned. The -lexical comparison is a comparison of ASCII values modified so that -all the letters sort earlier than all the non-letters. -<p> - -Then the initial part of the remainder of each string which consists -entirely of digit characters is determined. The numerical values of -these two parts are compared, and any difference found is returned as -the result of the comparison. For these purposes an empty string -(which can only occur at the end of one or both version strings being -compared) counts as zero. -<p> - -These two steps are repeated (chopping initial non-digit strings and -initial digit strings off from the start) until a difference is found -or both strings are exhausted. -<p> - -Note that the purpose of epochs is to allow us to leave behind -mistakes in version numbering, and to cope with situations where the -version numbering changes. It is <em/not/ there to cope with version -numbers containing strings of letters which <tt/dpkg/ cannot interpret -(such as <tt/ALPHA/ or <tt/pre-/), or with silly orderings (the author -of this manual has heard of a package whose versions went <tt/1.1/, -<tt/1.2/, <tt/1.3/, <tt/1/, <tt/2.1/, <tt/2.2/, <tt/2/ and so forth). -<p> - -If an upstream package has problematic version numbers they should be -converted to a sane form for use in the <tt/Version/ field. - -<sect1>Package maintainer scripts run by <tt/dpkg/<label id="maintainerscripts"> -<p> - -It is possible supply scripts as part of a package which <tt/dpkg/ -will run for you when your package is installed, upgraded or removed. -<p> - -These scripts should be the files <tt/preinst/, <tt/postinst/, -<tt/prerm/ and <tt/postrm/ in the control area of the package. They -should be proper exectuable files, so that if they are scripts (which -is to be recommended) they must start with the usual <tt/#!/ -convention. They should be readable and executable to anyone, and not -world-writeable. -<p> - -<tt/dpkg/ looks at the exit status from these scripts. It is -important that they exit with a non-zero status if there is an error, -so that <tt/dpkg/ can stop its processing. For shell scripts this -means that you <em/almost always/ need to use <tt/set -e/ (this is -usually true when writing shell scripts, in fact). It is also -important, of course, that they don't exit with a non-zero status if -everything went well. -<p> - -It is necessary for the error recovery procedures that the scripts be -idempotent: ie, invoking the same script several times in the same -situation should do no harm. If the first call failed, or aborted -half way through for some reason, the second call should merely do the -things that were left undone the first time, if any, and exit with a -success status. -<p> - -When a package is upgraded a combination of the scripts from the old -and new packages is called in amongst the other steps of the upgrade -procedure. If your scripts are going to be at all complicated you -need to be aware of this, and may need to check the arguments to your -scripts. -<p> - -Broadly speaking the <tt/preinst/ is called before (a particular -version of) a package is installed, and the <tt/postinst/ afterwards; -the <tt/prerm/ before (a version of) a package is removed and the -<tt/postrm/ afterwards. -<p> - -See <ref id="maintscripts-instact"> for details of exactly when and -how these scripts are called and with what arguments. - -<sect>Declaring relationships between packages<label id="depconoverwr"> -<p> - -Packages can declare in their control file that they have certain -relationships to other packages - for example, that they may not be -installed at the same time as certain other packages, and/or that they -depend on the presence of others, or that they should overwrite files -in certain other packages if present. -<p> - -This is done using the <tt/Depends/, <tt/Recommends/, <tt/Suggests/, -<tt/Conflicts/, <tt/Provides/ and <tt/Replaces/ control file fields. -<p> - -<sect1>Syntax of relationship fields -<p> - -These fields all have a uniform syntax. They are a list of package -names separated by commas. -<p> - -In <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and <tt/Pre-Depends/ -(the fields which declare dependencies of the package in which they -occur on other packages) these package names may also be lists of -alternative package names, separated by vertical bar symbols <tt/|/ -(pipe symbols). -<p> - -All the fields except <tt/Provides/ may restrict their applicability -to particular versions of each named package. This is done in -parentheses after each individual package name; the parentheses should -contain a relation from the list below followed by a version number, -in the format described in <ref id="versions">. -<p> - -The relations allowed are -<tt/<</, -<tt/<=/, -<tt/=/, -<tt/>=/ and -<tt/>>/ -for strictly earlier, earlier or equal, exactly equal, later or equal -and strictly later, respectively. The forms <tt/</ and <tt/>/ -were used to mean earlier/later or equal, rather than strictly -earlier/later, so they should not appear in new packages (though -<tt/dpkg/ still supports them). -<p> - -Whitespace may appear at any point in the version specification, and -must appear where it's necessary to disambiguate; it is not otherwise -significant. For consistency and in case of future changes to -<tt/dpkg/ it is recommended that a single space be used after a -version relationship and before a version number; it is usual also to -put a single space after each comma, on either side of each vertical -bar, and before each open parenthesis. - -<sect1>Dependencies - <tt/Depends/, <tt/Recommends/, <tt/Suggests/, <tt/Pre-Depends/ -<p> - -These four fields are used to declare a dependency by one package on -another. They appear in the depending package's control file. -<p> - -All but <tt/Pre-Depends/ (discussed below) take effect <em/only/ when -a package is to be configured. They do not prevent a package being on -the system in an unconfigured state while its dependencies are -unsatisfied, and it is possible to replace a package whose -dependencies are satisfied and which is properly installed with a -different version whose dependencies are not and cannot be satisfied; -when this is done the depending package will be left unconfigured -(since attempts to configure it will give errors) and will not -function properly. -<p> - -For this reason packages in an installation run are usually all -unpacked first and all configured later; this gives later versions of -packages with dependencies on later versions of other packages the -opportunity to have their dependencies satisfied. -<p> - -Thus <tt/Depends/ allows package maintainers to impose an order in -which packages should be configured. - -<descrip> -<tag/<tt/Depends// -This declares an absolute dependency. -<p> - -<tt/dpkg/ will not configure -packages whose dependencies aren't satisfied. If it is asked to make -an installation which would cause an installed package's dependencies -to become unsatisfied it will complain<footnote>Current versions -(1.2.4) of <tt/dpkg/ have a bug in this area which will cause some of -these problems to be ignored.</footnote>, unless -<tt/--auto-deconfigure/ is specified, in which case those packages -will be deconfigured before the installation proceeds. -<p> - -<tt/dselect/ makes it hard for the user to select packages for -installation, removal or upgrade in a way that would mean that -packages' <tt/Depends/ fields would be unsatisfied. The user can -override this if they wish, for example if they know that <tt/dselect/ -has an out-of-date view of the real package relationships. - -**** WHEN TO USE -- POLICY STATEMENT HERE ? - -<tag/<tt/Recommends// -This declares a strong, but not absolute, dependency. -<p> - -<tt/Recommends/ is ignored by <tt/dpkg/, so that users using the -command-line (who are presumed to know what they're doing) will not be -impeded. -<p> - -It is treated by <tt/dselect/ exactly as <tt/Depends/ is; this makes -it hard for the user to select things so as to leave <tt/Recommends/ -fields unsatisfied, but they are able to do so by being persistent. - -**** WHEN TO USE -- POLICY STATEMENT HERE ? - -<tag/<tt/Suggests// - -This is used to declare that one package may be more useful with one -or more others. -<p> - -<tt/dselect/ will offer suggsted packages to the system administrator -when they select the suggesting package, but the default is not to -install the suggested package. - -**** WHEN TO USE -- POLICY STATEMENT HERE ? - -<tag/<tt/Pre-Depends// - -This field is like <tt/Depends/, except that it also forces <tt/dpkg/ -to complete installation of the packages named before even starting -the installation of the package which declares the predependency. -<p> - -<tt/dselect/ checks for predependencies when it is doing an -installation run, and will attempt to find the packages which are -required to be installed first and do so in the right order. -<p> - -However, this process is slow (because it requires repeated -invocations of <tt/dpkg/) and troublesome (because it requires -guessing where to find the appropriate files). -<p> - -For these reasons, and because this field imposes restrictions on the -order in which packages may be unpacked (which can be difficult for -installations from multipart media, for example), <tt/Pre-Depends/ -should be used sparingly, preferably only by packages whose premature -upgrade or installation would hamper the ability of the system to -continue with any upgrade that might be in progress. -<p> - -When the package declaring it is being configured, a -<tt/Pre-Dependency/ will be considered satisfied only if the depending -package has been correctly configured, just as if an ordinary -<tt/Depends/ had been used. -<p> - -However, when a package declaring a predependency is being unpacked -the predependency can be satisfied even if the depended-on package(s) -are only unpacked or half-configured, provided that they have been -configured correctly at some point in the past (and not removed or -partially removed since). In this case both the previously-configured -and currently unpacked or half-configured versions must satisfy any -version clause in the <tt/Pre-Depends/ field. - -</descrip> - -<sect2>Deconfiguration due to removal during bulk installations -<p> - -If <tt/dpkg/ would like to remove a package due to a conflict, as -described above, but this would violate a dependency of some other -package on the system, <tt/dpkg/ will usually not remove the -conflicting package and halt with an error. -<p> - -However, if the <tt/--auto-deconfigure/ (<tt/-B/) option is used -<tt/dpkg/ will automatically `deconfigure' the package with the -problematic dependency, so that the conflicting package can be removed -and the package we're trying to install can be installed. If -<tt/dpkg/ is being asked to install packages (rather than just -unpacking them) it will try to reconfigure the package when it has -unpacked all its arguments, in the hope that one of the other packages -it is installing will satisfy the problematic dependency. -<p> - -<tt/dselect/ supplies this argument to <tt/dpkg/ when it invokes it, -so that bulk installations proceed smoothly. - -<sect1>Alternative packages - <tt/Conflicts/ and <tt/Replaces/<label id="conflicts"> -<p> - -When one package declares a conflict with another <tt/dpkg/ will -refuse to allow them to be installed on the system at the same time. -<p> - -If one package is to be installed, the other must be removed first - -if the package being installed is marked as replacing (<ref -id="replaces">) the one on the system, or the one on the system is -marked as deselected, or both packages are marked <tt/Essential/, then -<tt/dpkg/ will automatically remove the package which is causing the -conflict, otherwise it will halt the installation of the new package -with an error. -<p> - -<tt/dselect/ makes it hard to select conflicting packages, though the -user can override this if they wish. If they do not override it then -<tt/dselect/ will select one of the packages for removal, and the user -must make sure it is the right one. In the future <tt/dselect/ will -look for the presence of a <tt/Replaces/ field to help decide which -package should be installed and which removed. -<p> - -A package will not cause a conflict merely because its configuration -files are still installed; it must be at least half-installed. -<p> - -A special exception is made for packages which declare a conflict with -their own package name, or with a virtual package which they provide -(see below): this does not prevent their installation, and allows a -package to conflict with others providing a replacement for it. -<p> - -A <tt/Conflicts/ entry should almost never have an `earlier than' -version clause. This would prevent <tt/dpkg/ from upgrading or -installing the package which declared such a conflict until the -upgrade or removal of the conflicted-with package had been completed. -This aspect of installation ordering is not handled by <tt/dselect/, -so that the use <tt/Conflicts/ in this way is likely to cause problems -for `bulk run' upgrades and installations. -<p> - - - -<sect1>Virtual packages - <tt/Provides/<label id="virtual"> -<p> - -As well as the names of actual (`concrete') packages, the package -relationship fields <tt/Depends/, <tt/Recommends/, <tt/Suggests/ and -<tt/Conflicts/ may mention virtual packages. -<p> - -A virtual package is one which appears in the <tt/Provides/ control -file field of another package. The effect is as if the package(s) -which provide a particular virtual package name had been listed by -name everywhere were the virtual package name appears. -<p> - -If there are both a real and a virtual package of the same name then -the dependency may be satisfied (or the conflict caused) by either the -real package or any of the virtual packages which provide it. This is -so that, for example, supposing we have -<p> - -If a dependency or a conflict has a version number attached then only -real packages will be considered to see whether the relationship is -satisfied (or prohibited, for a conflict) - it is assumed that a real -package which provides virtual package is not of the `right' version. -So, a <tt/Provides/ field may not contain version numbers, and the -version number of the concrete package which provides a particular -virtual package will not be looked at when considering a dependency on -or conflict with the virtual package name. -<p> - -If you want to specify which of a set of real packages should be the -default to satisfy a particular dependency on a virtual package, you -should list the real package as alternative before the virtual. -<p> - -<sect1>Defaults for satisfying dependencies - ordering -<p> - -Ordering is significant in dependency fields. -<p> - -Usually dselect will suggest to the user that they select the package -with the most `fundamental' class (eg, it will prefer Base packages to -Optional ones), or the one that they `most wanted' to select in some -sense. -<p> - -However, in the absence of other information <tt/dselect/ will offer a -default selection of the first named package in a list of -alternatives. -<p> - -However, there is no way to specify the `order' of several packages -which all provide the same thing, when that thing is listed as a -dependency. -<p> - -Therefore a dependency on a virtual package should contain a concrete -package name as the first alternative, so that this is the default. -<p> - -For example, consider the set of packages: - -<example> -Package: glibcdoc -Recommends: info-browser - -Package: info -Provides: info-browser - -Package: emacs -Provides: info-browser -</example> - -If <tt/emacs/ and <tt/info/ both have the same priority then -<tt/dselect/'s choice is essentially random. Better would be -<example> -Package: glibcdoc -Recommends: info | info-browser -</example> -so that <tt/dselect/ defaults to selecting the lightweight standalone -info browser. - -<sect1><tt/Replaces/ - overwriting files and replacing packages<label id="replaces"> -<p> - -The <tt/Replaces/ control file field has two purposes, which come into -play in different situations. -<p> - -Virtual packages (<ref id="virtual">) are not considered when looking -at a <tt/Replaces/ field - the packages declared as being replaced -must be mentioned by their real names. - -<sect2>Overwriting files in other packages -<p> - -Firstly, as mentioned before, it is usually an error for a package to -contains files which are on the system in another package, though -currently the <tt/--force-overwrite/ flag is enabled by default, -downgrading the error to a warning, -<p> - -If the overwriting package declares that it replaces the one -containing the file being overwritten then <tt/dpkg/ will proceed, and -replace the file from the old package with that from the new. The -file will no longer be listed as `owned' by the old package. -<p> - -If a package is completely replaced in this way, so that <tt/dpkg/ -does not know of any files it still contains, it is considered to have -disappeared. It will be marked as not wanted on the system (selected -for removal) and not installed. Any conffiles details noted in the -package will be ignored, as they will have been taken over by the -replacing package(s). The package's <tt/postrm/ script will be run to -allow the package to do any final cleanup required. -See <ref id="maintscripts-instact">. -<p> - -In the future <tt/dpkg/ will discard files which overwrite those from -another package which declares that it replaces the one being -installed (so that you can install an older version of a package -without problems). -<p> - -This usage of <tt/Replaces/ only takes effect when both packages are -at least partially on the system at once, so that it can only happen -if they do not conflict or if the conflict has been overridden. - -<sect2>Replacing whole packages, forcing their removal -<p> - -Secondly, <tt/Replaces/ allows <tt/dpkg/ and <tt/dselect/ to resolve -which package should be removed when a conflict - see -<ref id="conflicts">. This usage only takes effect when the two -packages <em/do/ conflict, so that the two effects do not interfere -with each other. -<p> - -<sect>Order of processing steps and maintainer script arguments<label id="maintscripts-instact"> -<p> - -<sect1>Summary of ways maintainer scripts are called -<p> - -<itemize> -<item><var/new preinst/ <tt/install/ -<item><var/new preinst/ <tt/install/ <var/old-version/ -<item><var/new preinst/ <tt/upgrade/ <var/old-version/ -<item><var/old preinst/ <tt/abort-upgrade/ <var/new-version/ -</itemize> - -<itemize> -<item><var/postinst/ <tt/configure/ <var/most-recently-configured-version/ -<item><var/old-postinst/ <tt/abort-upgrade/ <var/new version/ -<item><var/conflictor's-postinst/ <tt/abort-remove/ - in-favour <var/package/ <var/new-version/ -<item><var/deconfigured's-postinst/ <tt/abort-deconfigure/ - <tt/in-favour/ <var/failed-install-package/ <var/version/ - <tt/removing/ <var/conflicting-package/ <var/version/ -</itemize> - -<itemize> -<item><var/prerm/ <tt/remove/ -<item><var/old-prerm/ <tt/upgrade/ <var/new-version/ -<item><var/new-prerm/ <tt/failed-upgrade/ <var/old-version/ -<item><var/conflictor's-prerm/ <tt/remove/ <tt/in-favour/ - <var/package/ <var/new-version/ -<item><var/deconfigured's-prerm/ <tt/deconfigure/ - <tt/in-favour/ <var/package-being-installed/ <var/version/ - <tt/removing/ <var/conflicting-package/ <var/version/ -</itemize> - -<itemize> -<item><var/postrm/ <tt/remove/ -<item><var/postrm/ <tt/purge/ -<item><var/old-postrm/ <tt/upgrade/ <var/new-version/ -<item><var/new-postrm/ <tt/failed-upgrade/ <var/old-version/ -<item><var/new-postrm/ <tt/abort-install/ -<item><var/new-postrm/ <tt/abort-install/ <var/old-version/ -<item><var/new-postrm/ <tt/abort-upgrade/ <var/old-version/ -<item><var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/new-version/ -</itemize> - -<sect1>Details of unpack phase of installation or upgrade -<p> - -The procedure on installation/upgrade/overwrite/disappear (ie, when -running <tt/dpkg --unpack/, or the unpack stage of <tt/dpkg ---install/) is as follows. In each case if an error occurs the -actions in are general run backwards - this means that the maintainer -scripts are run with different arguments in reverse order. These are -the `error unwind' calls listed below. - -<enum> -<item> - -<enum> -<item> -If a version the package is already -installed, call -<example> -<var/old-prerm/ <tt/upgrade/ <var/new-version/ -</example> - -<item> -If this gives an error (ie, a non-zero exit status), dpkg will -attempt instead: -<example> -<var/new-prerm/ <tt/failed-upgrade/ <var/old-version/ -</example> -Error unwind, for both the above cases: -<example> -<var/old-postinst/ <tt/abort-upgrade/ <var/new-version/ -</example> - -</enum> - -<item> -If a `conflicting' package is being removed at the same time: -<enum> - -<item> -If any packages depended on that conflicting package and -<tt/--auto-deconfigure/ is specified, call, for each such package: -<example> -<var/deconfigured's-prerm/ <tt/deconfigure/ - <tt/in-favour/ <var/package-being-installed/ <var/version/ - <tt/removing/ <var/conflicting-package/ <var/version/ -</example> -Error unwind: -<example> -<var/deconfigured's-postinst/ <tt/abort-deconfigure/ - <tt/in-favour/ <var/package-being-installed-but-failed/ <var/version/ - <tt/removing/ <var/conflicting-package/ <var/version/ -</example> -The deconfigured packages are marked as requiring configuration, so -that if <tt/--install/ is used they will be configured again if -possible. - -<item> -To prepare for removal of the conflicting package, call: -<example> -<var/conflictor's-prerm/ <tt/remove/ - <tt/in-favour/ <var/package/ <var/new-version/ -</example> -Error unwind: -<example> -<var/conflictor's-postinst/ <tt/abort-remove/ - <tt/in-favour/ <var/package/ <var/new-version/ -</example> - -</enum> - -<item> -<enum> -<item> -If the package is being upgraded, call: -<example> -<var/new-preinst/ <tt/upgrade/ <var/old-version/ -</example> - -<item> -Otherwise, if the package had some configuration files from a previous -version installed (ie, it is in the `configuration files only' state): -<example> -<var/new-preinst/ <tt/install/ <var/old-version/ -</example> - -<item> -Otherwise (ie, the package was completely purged): -<example> -<var/new-preinst/ <tt/install/ -</example> -Error unwind versions, respectively: -<example> -<var/new-postrm/ <tt/abort-upgrade/ <var/old-version/ -<var/new-postrm/ <tt/abort-install/ <var/old-version/ -<var/new-postrm/ <tt/abort-install/ -</example> - -</enum> - -<item> -The new package's files are unpacked, overwriting any that may be on -the system already, for example any from the old version of the same -package or from another package (backups of the old files are left -around, and if anything goes wrong dpkg will attempt to put them back -as part of the error unwind). -<p> - -It is an error for a package to contains files which are on the system -in another package, unless <tt/Replaces/ is used -(see <ref id="replaces">). Currently the <tt/--force-overwrite/ flag -is enabled, downgrading it to a warning, but this will not always be -the case. -<p> - -Packages which overwrite each other's files produce behaviour which -(though deterministic) is hard for the system administrator to -understand and can easily lead to `missing' programs (for example, if -a package is installed which overwrites a file from another package, -and then it is removed again). - -<item> - -<enum> -<item> -If the package is being upgraded, call -<example> -<var/old-postrm/ <tt/upgrade/ <var/new-version/ -</example> - -<item> -If this fails, <tt/dpkg/ will attempt: -<example> -<var/new-postrm/ <tt/failed-upgrade/ <var/old-version/ -</example> -Error unwind, for both cases: -<example> -<var/old-preinst/ <tt/abort-upgrade/ <var/new-version/ -</example> - -</enum> - -This is the point of no return - if <tt/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 <tt/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, - -<enum> -<item> -<tt/dpkg/ calls: -<example> -<var/disappearer's-postrm/ <tt/disappear/ <var/overwriter/ <var/overwriter-version/ -</example> - -<item> -The package's maintainer scripts are removed. - -<item> -It is noted in the status database as being in a sane state, namely -not installed (any conffiles it may have are ignored, rather than -being removed by <tt/dpkg/). Note that disappearing packages do not -have their prerm called, because <tt/dpkg/ doesn't know in advance -that the package is going to vanish. - -</enum> - -<item> -Any files in the package we're unpacking that are also listed in the -file lists of other packages are removed from those lists. (This will -lobotomise the file list of the `conflicting' package if there is one.) - -<item> -The backup files made during installation, above, are deleted. - -<item> -The new package's status is now sane, and recorded as `unpacked'. Here -is another point of no return - if the conflicting package's removal -fails we do not unwind the rest of the installation; the conflicting -package is left in a half-removed limbo. - -<item> -If there was a conflicting package we go and do the removal actions -(described below), starting with the removal of the conflicting -package's files (any that are also in the package being installed -have already been removed from the conflicting package's file list, -and so do not get removed now). - -</enum> - -<sect1>Details of configuration -<p> - -When we configure a package (this happens with <tt/dpkg --install/, or -with <tt/--configure/), we first update the conffiles and then call: -<example> -<var/postinst/ <tt/configure/ <var/most-recently-configured-version/ -</example> -<p> - -No attempt is made to unwind after errors during configuration. -<p> - -If there is no most recently configured version <tt/dpkg/ will pass a -null argument; older versions of dpkg may pass -<tt><unknown></tt> (including the angle brackets) in this case. -Even older ones do not pass a second argument at all, under any -circumstances. - -<sect1>Details of removal and/or configration purging -<p> - -<enum> -<item> -<example> -<var/prerm/ <tt/remove/ -</example> - -<item> -The package's files are removed (except conffiles). - -<item> -<example> -<var/postrm/ <tt/remove/ -</example> - -<item> -All the maintainer scripts except the postrm are removed. -<p> - -If we aren't purging the package we stop here. Note that packages -which have no postrm and no conffiles are automatically purged when -removed, as there is no difference except for the <tt/dpkg/ status. - -<item> -The conffiles and any backup files (<tt/~/-files, <tt/#*#/ files, -<tt/%/-files, <tt/.dpkg-{old,new,tmp}/, etc.) are removed. - -<item> -<example> -<var/postrm/ <tt/purge/ -</example> - -<item> -The package's file list is removed. - -</enum> - -No attempt is made to unwind after errors during removal. - - -<sect>Configuration file handling<label id="conffiles"> - -<tt/dpkg/ can do a certain amount of automatic handling of package -configuration files. -<p> - -Whether this mechanism is appropriate depends on a number of factors, -but basically there are two approaches to any particular configuration -file. -<p> - -The easy method is to ship a best-effort configuration in the package, -and use <tt/dpkg/'s conffile mechanism to handle updates. If the user -is unlikely to want to edit the file, but you need them to be able to -without losing their changes, and a new package with a changed version -of the file is only released infrequently, this is a good approach. -<p> - -The hard method is to build the configuration file from scratch in the -<tt/postinst/ script, and to take the responsibility for fixing any -mistakes made in earlier versions of the package automatically. This -will be appropriate if the file is likely to need to be different on -each system. - -<sect1>Automatic handling of configuration files by <tt/dpkg/ -<p> - -A package may contain a control area file called <tt/conffiles/. This -file should be a list of filenames of configuration files needing -automatic handling, separated by newlines. The filenames should be -absolute pathnames, and the files referred to should actually exist in -the package. -<p> - -When a package is upgraded, during the configuration state shortly -before <tt/dpkg/ runs the package's <tt/postinst/ script, it will -process the configuration files. -<p> - -For each file it checks to see whether the version of the file -included in the package is the same as the one that was included in -the last version of the package (the one that is being upgraded -from); it also compares the version currently installed on the system -with the one shipped with the last version. -<p> - -If neither the user nor the package maintainer has changed the file, -it is left alone. If one or the other has changed their version, then -the changed version is preferred - ie, if the user edits their file, -but the package maintainer doesn't ship a different version, the -user's changes will stay, silently, but if the maintainer ships a new -version and the user hasn't edited it the new version will be -installed (with an informative message). If both have changed their -version the user is prompted about the problem and must resolve the -differences themselves. -<p> - -The comparisons are done by calculating the MD5 message digests of the -files, and storing the MD5 of the file as it was included in the most -recent version of the package. -<p> - -When a package is installed for the first time <tt/dpkg/ will install -the file that comes with it, unless that would mean overwriting a file -already on the filesystem. -<p> - -However, note that <tt/dpkg/ will <em/not/ replace a conffile file -that was removed by the user (or by a script). This is necessary -because for some programs' configuration files a missing file produces -an effect hard or impossible to achieve in another way, so that a -missing file needs to be kept that way if the user did it. -<p> - -Note that a package should <em/not/ modify a <tt/dpkg/-handled -conffile in its maintainer scripts. Doing this will lead to <tt/dpkg/ -asking the user confusing and possibly dangerous questions when the -package is upgraded. - -<sect2>Fully-featured maintainer script configuration handling -<p> - -For files which contain site-specific information such as thep -hostname and networking details and so forth, it is better to create -the file in the package's <tt/postinst/ script. -<p> - -This will typically involve examining the state of the rest of the -system to determine values and other information, and may involve -prompting the user for some information which can't be obtained some -other way. -<p> - -When using this method there are a number of important issues which -should be considered: -<p> - -The package's <tt/postinst/ should be written so that - - -<sect>Dangling references -<p> - -<sect1>Would dangle to conffiles<label id="conffiles"> -<p> - -There would be a dangling xref here. Instead I've just put this dummy -text in. - -<sect1>Would dangle to descriptions<label id="descriptions"> -<p> - -There would be a dangling xref here. Instead I've just put this dummy -text in. - -</article> diff --git a/scripts/Makefile.in b/scripts/Makefile.in index 4cc50235..4103c695 100644 --- a/scripts/Makefile.in +++ b/scripts/Makefile.in @@ -47,8 +47,8 @@ MAN8 = update-rc.d start-stop-daemon update-alternatives install-info \ SBIN = update-rc.d start-stop-daemon update-alternatives install-info \ dpkg-scanpackages dpkg-divert cleanup-info LIB = controllib.pl -ELISP = dpkg-changelog-mode.el -CHGLGS= cl-dpkg +ELISP = debian-changelog-mode.el +CHGLGS= cl-debian INSTALL = @INSTALL@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ @@ -79,7 +79,7 @@ INSTALL_DATA = @INSTALL_DATA@ all: $(EXC) $(SBIN) $(CHGLGS) clean: - rm -f $(EXC) $(SBIN) core *.new + rm -f $(EXC) $(SBIN) $(CHGLGS) core *.new distclean: clean rm -f Makefile *.orig *~ *.~* ./#*# i386elf-hello-world.gz diff --git a/scripts/cl-dpkg.pl b/scripts/cl-debian.pl similarity index 100% rename from scripts/cl-dpkg.pl rename to scripts/cl-debian.pl diff --git a/scripts/cl-dpkg b/scripts/cl-dpkg deleted file mode 100755 index 8fdb2460..00000000 --- a/scripts/cl-dpkg +++ /dev/null @@ -1,143 +0,0 @@ -#!/usr/bin/perl -# -# Options: -# -v<version> -# changes since <version> - -$dpkglibdir= "/usr/lib/dpkg"; -$version= '1.3.0'; # This line modified by Makefile - -$controlfile= 'debian/control'; -$changelogfile= 'debian/changelog'; -$fileslistfile= 'debian/files'; -$varlistfile= 'debian/substvars'; - -push(@INC,$dpkglibdir); -require 'controllib.pl'; - -$progname= "parsechangelog/$progname"; - -$since=''; - -sub usageversion { - print STDERR -"Debian GNU/Linux parsechangelog/dpkg $version. Copyright (C) 1996 -Ian Jackson. This is free software; see the GNU General Public Licence -version 2 or later for copying conditions. There is NO warranty. - -Usage: parsechangelog/dpkg [-v<versionsince] | -h -"; -} - -while (@ARGV) { - $_=shift(@ARGV); - if (m/^-v(.+)$/) { - $since= $1; - } elsif (m/^-h$/) { - &usageversion; exit(0); - } else { - &usageerr("unknown option or argument \`$_'"); - } -} - -%mapkv=(); # for future use -$i=100;grep($fieldimps{$_}=$i--, - qw(Source Version Distribution Urgency Maintainer Date Changes)); -$i=1;grep($urgencies{$_}=$i++, - qw(low medium routine high urgent emergency)); - -$expect='first heading'; - -while (<STDIN>) { - s/\s*\n$//; -# printf(STDERR "%-39.39s %-39.39s\n",$expect,$_); - if (m/^(\w[-+0-9a-z.]+) \(([^\(\) \t]+)\)((\s+[-0-9a-z]+)+)\;/i) { - if ($expect eq 'first heading') { - $f{'Source'}= $1; - $f{'Version'}= $2; - $f{'Distribution'}= $3; - &error("-v<since> option specifies most recent version") if - $2 eq $since; - $f{'Distribution'} =~ s/^\s+//; - } elsif ($expect eq 'next heading or eof') { - last if $2 eq $since; - $f{'Changes'}.= " .\n"; - } else { - &clerror("found start of entry where expected $expect"); - } - $rhs= $'; $rhs =~ s/^\s+//; - undef %kvdone; - for $kv (split(/\s*,\s*/,$rhs)) { - $kv =~ m/^([-0-9a-z]+)\=\s*(.*\S)$/i || - &clerror("bad key-value after \`;': \`$kv'"); - $k=(uc substr($1,0,1)).(lc substr($1,1)); $v=$2; - $kvdone{$k}++ && &clwarn("repeated key-value $k"); - if ($k eq 'Urgency') { - $v =~ m/^([-0-9a-z]+)((\s+.*)?)$/i || - &clerror("badly formatted urgency value, at changelog "); - $newurg= lc $1; - $newurgn= $urgencies{lc $1}; $newcomment= $2; - $newurgn || - &clwarn("unknown urgency value $newurg - comparing very low"); - if (defined($f{'Urgency'})) { - $f{'Urgency'} =~ m/^([-0-9a-z]+)((\s+.*)?)$/i || - &internerr("urgency >$f{'Urgency'}<"); - $oldurg= lc $1; - $oldurgn= $urgencies{lc $1}; $oldcomment= $2; - } else { - $oldurgn= -1; - $oldcomment= ''; - } - $f{'Urgency'}= - (($newurgn > $oldurgn ? $newurg : $oldurg). - $oldcomment. - $newcomment); - } elsif (defined($mapkv{$k})) { - $f{$mapkv{$k}}= $v; - } elsif ($k =~ m/^X[BCS]+-/i) { - # Extensions - XB for putting in Binary, - # XC for putting in Control, XS for putting in Source - $f{$k}= $v; - } else { - &clwarn("unknown key-value key $k - copying to XS-$k"); - $f{"XS-$k"}= $v; - } - } - $expect= 'start of change data'; $blanklines=0; - $f{'Changes'}.= " $_\n .\n"; - } elsif (m/^\S/) { - &clerror("badly formatted heading line"); - } elsif (m/^ \-\- (\S.*\S) ((\w+\,\s*)?\d{1,2}\s+\w+\s+\d{4}\s+\d{1,2}:\d\d:\d\d\s+[-+]\d{4}(\s+\([^\\\(\)]\))?)$/) { - $expect eq 'more change data or trailer' || - &clerror("found trailer where expected $expect"); - $f{'Maintainer'}= $1 unless defined($f{'Maintainer'}); - $f{'Date'}= $2 unless defined($f{'Date'}); -# $f{'Changes'}.= " .\n $_\n"; - $expect= 'next heading or eof'; - last if $since eq ''; - } elsif (m/^ \-\-/) { - &clerror("badly formatted trailer line"); - } elsif (m/^\s{2,}\S/) { - $expect eq 'start of change data' || $expect eq 'more change data or trailer' || - &clerror("found change data where expected $expect"); - $f{'Changes'}.= (" .\n"x$blanklines)." $_\n"; $blanklines=0; - $expect= 'more change data or trailer'; - } elsif (!m/\S/) { - next if $expect eq 'start of change data' || $expect eq 'next heading or eof'; - $expect eq 'more change data or trailer' || - &clerror("found blank line where expected $expect"); - $blanklines++; - } else { - &clerror("unrecognised line"); - } -} - -$expect eq 'next heading or eof' || die "found eof where expected $expect"; - -$f{'Changes'} =~ s/\n$//; -$f{'Changes'} =~ s/^/\n/; - -&outputclose; - -sub clerror { &error("$_[0], at changelog line $."); } -sub clwarn { &warn("$_[0], at changelog line $."); } diff --git a/scripts/dpkg-changelog-mode.el b/scripts/debian-changelog-mode.el similarity index 64% rename from scripts/dpkg-changelog-mode.el rename to scripts/debian-changelog-mode.el index 5b003a71..aae0548c 100644 --- a/scripts/dpkg-changelog-mode.el +++ b/scripts/debian-changelog-mode.el @@ -1,4 +1,4 @@ -;; dpkg-changelog.el --- change log maintenance for dpkg-style changelogs +;; debian-changelog.el --- change log maintenance for Debian-style changelogs ;; Keywords: maint @@ -22,32 +22,33 @@ (require 'add-log) -(defvar dpkg-changelog-urgencies - '((?l."LOW") (?m."MEDIUM") (?h."HIGH")) - "alist of keystrokes vs. urgency values dpkg-changelog-urgency ^c^u.") +(defvar debian-changelog-urgencies + '((?l."low") (?m."medium") (?h."HIGH")) + "alist of keystrokes vs. urgency values debian-changelog-urgency ^c^u.") -(defvar dpkg-changelog-distributions +(defvar debian-changelog-distributions '((?s."stable") (?u."unstable") (?c."contrib") (?n."non-free") (?e."experimental")) - "alist of keystrokes vs. distribution values for dpkg-changelog-distribution ^c^d.") + "alist of keystrokes vs. distribution values for debian-changelog-distribution ^c^d.") -(defvar dpkg-changelog-mode-map nil - "Keymap for dpkg changelog major mode.") -(if dpkg-changelog-mode-map +(defvar debian-changelog-mode-map nil + "Keymap for Debian changelog major mode.") +(if debian-changelog-mode-map nil - (setq dpkg-changelog-mode-map (make-sparse-keymap)) - (define-key dpkg-changelog-mode-map "\C-c\C-a" 'dpkg-changelog-add-entry) - (define-key dpkg-changelog-mode-map "\C-c\C-f" 'dpkg-changelog-finalise-last-version) - (define-key dpkg-changelog-mode-map "\C-c\C-c" 'dpkg-changelog-finalise-and-save) - (define-key dpkg-changelog-mode-map "\C-c\C-v" 'dpkg-changelog-add-version) - (define-key dpkg-changelog-mode-map "\C-c\C-d" 'dpkg-changelog-distribution) - (define-key dpkg-changelog-mode-map "\C-c\C-u" 'dpkg-changelog-urgency) - (define-key dpkg-changelog-mode-map "\C-c\C-e" - 'dpkg-changelog-unfinalise-last-version)) - -(defun dpkg-changelog-add-entry () - "Add a new change entry to a dpkg-style changelog." + (setq debian-changelog-mode-map (make-sparse-keymap)) + (define-key debian-changelog-mode-map "\C-c\C-a" 'debian-changelog-add-entry) + (define-key debian-changelog-mode-map "\C-c\C-f" + 'debian-changelog-finalise-last-version) + (define-key debian-changelog-mode-map "\C-c\C-c" 'debian-changelog-finalise-and-save) + (define-key debian-changelog-mode-map "\C-c\C-v" 'debian-changelog-add-version) + (define-key debian-changelog-mode-map "\C-c\C-d" 'debian-changelog-distribution) + (define-key debian-changelog-mode-map "\C-c\C-u" 'debian-changelog-urgency) + (define-key debian-changelog-mode-map "\C-c\C-e" + 'debian-changelog-unfinalise-last-version)) + +(defun debian-changelog-add-entry () + "Add a new change entry to a debian-style changelog." (interactive) - (if (eq (dpkg-changelog-finalised-p) t) + (if (eq (debian-changelog-finalised-p) t) (error "most recent version has been finalised - use ^c^e or ^c^v")) (goto-char (point-min)) (re-search-forward "\n --") @@ -58,7 +59,7 @@ (insert " * ") (save-excursion (insert "\n"))) -(defun dpkg-changelog-headervalue (arg re alist) +(defun debian-changelog-headervalue (arg re alist) (let (a b v k (lineend (save-excursion (end-of-line) (point)))) (save-excursion @@ -78,28 +79,28 @@ (if arg nil (insert (cdr v)))) (if arg (goto-char a)))) -(defun dpkg-changelog-urgency (arg) +(defun debian-changelog-urgency (arg) "Without argument, prompt for a key for a new urgency value (using -dpkg-changelog-urgencies). With argument, delete the current urgency +debian-changelog-urgencies). With argument, delete the current urgency and position the cursor to type a new one." (interactive "P") - (dpkg-changelog-headervalue + (debian-changelog-headervalue arg "\\;[^\n]* urgency=\\(\\sw+\\)" - dpkg-changelog-urgencies)) + debian-changelog-urgencies)) -(defun dpkg-changelog-distribution (arg) +(defun debian-changelog-distribution (arg) "Without argument, prompt for a key for a new distribution value (using -dpkg-changelog-distributions). With argument, delete the current distribution +debian-changelog-distributions). With argument, delete the current distribution and position the cursor to type a new one." (interactive "P") - (dpkg-changelog-headervalue + (debian-changelog-headervalue arg ") \\(.*\\)\\;" - dpkg-changelog-distributions)) + debian-changelog-distributions)) -(defun dpkg-changelog-finalised-p () - "Check whether the most recent dpkg-style changelog entry is +(defun debian-changelog-finalised-p () + "Check whether the most recent debian-style changelog entry is finalised yet (ie, has a maintainer name and email address and a release date." (save-excursion @@ -118,10 +119,10 @@ release date." nil) ("finalisation line has bad format (not ` -- maintainer <email> date')")))) -(defun dpkg-changelog-add-version () - "Add a new version section to a dpkg-style changelog file." +(defun debian-changelog-add-version () + "Add a new version section to a debian-style changelog file." (interactive) - (let ((f (dpkg-changelog-finalised-p))) + (let ((f (debian-changelog-finalised-p))) (and (stringp f) (error f)) (or f (error "previous version not yet finalised"))) (goto-char (point-min)) @@ -133,30 +134,30 @@ release date." (let ((pkg (read-string "Package name: ")) (ver (read-version "New version (including any revision): "))) (concat pkg " (" ver ") unstable; urgency=" - (cdr (car dpkg-changelog-urgencies))))))) + (cdr (car debian-changelog-urgencies))))))) (insert headstring "\n\n * ") (save-excursion (if (re-search-backward "\;[^\n]* urgency=\\(\\sw+\\)" (point-min) t) (progn (goto-char (match-beginning 1)) (delete-region (point) (match-end 1)) - (insert (cdr (car dpkg-changelog-urgencies)))))) + (insert (cdr (car debian-changelog-urgencies)))))) (save-excursion (insert "\n\n --\n\n")))) -(defun dpkg-changelog-finalise-and-save () - "Finalise, if necessary, and then save a dpkg-style changelog file." +(defun debian-changelog-finalise-and-save () + "Finalise, if necessary, and then save a debian-style changelog file." (interactive) - (let ((f (dpkg-changelog-finalised-p))) + (let ((f (debian-changelog-finalised-p))) (and (stringp f) (error f)) - (or f (dpkg-changelog-finalise-last-version))) + (or f (debian-changelog-finalise-last-version))) (save-buffer)) -(defun dpkg-changelog-finalise-last-version () +(defun debian-changelog-finalise-last-version () "Remove the `finalisation' information (maintainer's name and email address and release date) so that new entries can be made." (interactive) (or add-log-full-name (setq add-log-full-name (user-full-name))) (or add-log-mailing-address (setq add-log-mailing-address user-mail-address)) - (and (dpkg-changelog-finalised-p) (dpkg-changelog-unfinalise-last-version)) + (and (debian-changelog-finalised-p) (debian-changelog-unfinalise-last-version)) (save-excursion (goto-char (point-min)) (re-search-forward "\n --\\([ \t]*\\)") @@ -170,11 +171,11 @@ address and release date) so that new entries can be made." (error (concat "expected newline after date from " dp))) (delete-char 1))) -(defun dpkg-changelog-unfinalise-last-version () +(defun debian-changelog-unfinalise-last-version () "Remove the `finalisation' information (maintainer's name and email address and release date) so that new entries can be made." (interactive) - (if (dpkg-changelog-finalised-p) nil + (if (debian-changelog-finalised-p) nil (error "most recent version is not finalised")) (save-excursion (goto-char (point-min)) @@ -183,18 +184,22 @@ address and release date) so that new entries can be made." (end-of-line) (delete-region dels (point))))) -(defun dpkg-changelog-mode () - "Major mode for editing dpkg-style change logs. -Runs `dpkg-changelog-mode-hook'." +(defun debian-changelog-mode () + "Major mode for editing Debian-style change logs. +Runs `debian-changelog-mode-hook' if it exists. + +Key bindings: + +\\{dpkg-changelog-mode-map}" (interactive) (kill-all-local-variables) (text-mode) - (setq major-mode 'dpkg-changelog-mode - mode-name "dpkg changelog" + (setq major-mode 'debian-changelog-mode + mode-name "Debian changelog" left-margin 2 - fill-prefix " " + fill-prefix " " fill-column 74) - (use-local-map dpkg-changelog-mode-map) + (use-local-map debian-changelog-mode-map) ;; Let each entry behave as one paragraph: (set (make-local-variable 'paragraph-start) "\\*") (set (make-local-variable 'paragraph-separate) "\\*\\|\\s-*$|\\S-") @@ -203,6 +208,6 @@ Runs `dpkg-changelog-mode-hook'." ;; is grouped with what follows. (set (make-local-variable 'page-delimiter) "^\\<") (set (make-local-variable 'version-control) 'never) - (run-hooks 'dpkg-changelog-mode-hook)) + (run-hooks 'debian-changelog-mode-hook)) -(provide 'dpkg-changelog) +(provide 'debian-changelog) diff --git a/scripts/dpkg-parsechangelog.pl b/scripts/dpkg-parsechangelog.pl index e9967947..a663cd32 100644 --- a/scripts/dpkg-parsechangelog.pl +++ b/scripts/dpkg-parsechangelog.pl @@ -3,7 +3,7 @@ $dpkglibdir= "."; $version= '1.3.0'; # This line modified by Makefile -$format='dpkg'; +$format='debian'; $changelogfile='debian/changelog'; @parserpath= ("/usr/local/lib/dpkg/parsechangelog", "$dpkglibdir/parsechangelog"); diff --git a/scripts/dpkg-source.1 b/scripts/dpkg-source.1 index 5b674732..fe9f73ae 100644 --- a/scripts/dpkg-source.1 +++ b/scripts/dpkg-source.1 @@ -143,7 +143,9 @@ This option is understood by Specifies the format of the changelog. By default the format is read from a special line near the bottom of the changelog (see the programmers' manual) or failing that defaults to -.BR dpkg . +.BR debian , +the standard format described in the +.IR "dpkg programmers' manual" . This option is understood by .BR dpkg-source ", " dpkg-gencontrol " and " dpkg-genchanges . .SH DPKG-SOURCE OPTIONS @@ -387,8 +389,7 @@ not matter, since .BR $ ", " { " and " } are not legal in package names or version numbers. .SH SEE ALSO -.B dpkg -.IR "programmers' manual" , +.IR "dpkg programmers' manual" , .IR "Debian policy manual" , .BR dpkg\-deb (8), .BR dpkg (8), diff --git a/scripts/dpkg-source.pl b/scripts/dpkg-source.pl index 634a8248..ac729910 100644 --- a/scripts/dpkg-source.pl +++ b/scripts/dpkg-source.pl @@ -382,8 +382,7 @@ if ($opmode eq 'build') { defined($c2= open(CPIO,"-|")) || &syserr("fork for cpio"); if (!$c2) { open(STDIN,"<&GZIP") || &syserr("reopen gzip for cpio"); - open(STDERR,"| egrep -v '^[0-9]+ blocks\$' >&2") || - &syserr("reopen stderr for cpio to grep out blocks message"); + &cpiostderr; exec('cpio','-0t'); &syserr("exec cpio"); } $/= "\0"; @@ -394,7 +393,7 @@ if ($opmode eq 'build') { $fn =~ m/\n/ && &error("tarfile contains object with newline in its name ($pname)"); $slash= substr($fn,length($expectprefix),1); - (($slash || '/' || $slash eq '') && + (($slash eq '/' || $slash eq '') && substr($fn,0,length($expectprefix)) eq $expectprefix) || &error("tarfile contains object ($pname) not in expected directory". " ($expectprefix)"); @@ -529,6 +528,32 @@ if ($opmode eq 'build') { } } + $execmode= 0777 & ~umask; + (@s= stat('.')) || &syserr("cannot stat \`.'"); + $dirmode= $execmode | ($s[2] & 02000); + $plainmode= $execmode & ~0111; + $fifomode= ($plainmode & 0222) | (($plainmode & 0222) << 1); + for $fn (@filesinarchive) { + $fn= substr($fn,length($expectprefix)+1); + $fn= "$newdirectory/$fn"; + (@s= lstat($fn)) || &syserr("cannot stat extracted object \`$fn'"); + $mode= $s[2]; + if (-d _) { + $newmode= $dirmode; + } elsif (-f _) { + $newmode= ($mode & 0111) ? $execmode : $plainmode; + } elsif (-p _) { + $newmode= $fifomode; + } elsif (!-l _) { + &internerr("unknown object \`$fn' after extract (mode ". + sprintf("0%o",$mode).")"); + } +printf STDERR "mode %07o newmode %07o %s\n",$mode,$newmode,$fn; + next if ($mode & 07777) == $newmode; + chmod($newmode,$fn) || + &syserr(sprintf("cannot change mode of \`%s' to 0%o from 0%o", + $fn,$newmode,$mode)); + } exit(0); } @@ -556,17 +581,23 @@ sub erasedir { sub extracttar { &forkgzipread("$dscdir/$tarfile"); - defined($c2= fork) || &syserr("fork for tar -x"); + defined($c2= fork) || &syserr("fork for cpio -i"); if (!$c2) { - open(STDIN,"<&GZIP") || &syserr("reopen gzip for tar -x"); - exec('tar','-xf','-'); &syserr("exec tar -x"); + open(STDIN,"<&GZIP") || &syserr("reopen gzip for cpio -i"); + &cpiostderr; + exec('cpio','-Hustar','-im','--no-preserve-owner'); &syserr("exec cpio -i"); } close(GZIP); - $c2 == waitpid($c2,0) || &syserr("wait for tar -x"); - $? && subprocerr("tar -x"); + $c2 == waitpid($c2,0) || &syserr("wait for cpio -i"); + $? && subprocerr("cpio -i"); &reapgzip; } +sub cpiostderr { + open(STDERR,"| egrep -v '^[0-9]+ blocks\$' >&2") || + &syserr("reopen stderr for cpio to grep out blocks message"); +} + sub setfile { my ($varref)= @_; &error("repeated file type - files ".$$varref." and $file") if length($$varref); diff --git a/version.h b/version.h index 4dcc9737..85d37bc9 100644 --- a/version.h +++ b/version.h @@ -1 +1 @@ -#define DPKG_VERSION "1.3.2" /* This line modified by Makefile */ +#define DPKG_VERSION "1.3.3" /* This line modified by Makefile */