diff options
Diffstat (limited to 'doc/guidelines.texi')
| -rw-r--r-- | doc/guidelines.texi | 1936 |
1 files changed, 1936 insertions, 0 deletions
diff --git a/doc/guidelines.texi b/doc/guidelines.texi new file mode 100644 index 000000000..78662e4d4 --- /dev/null +++ b/doc/guidelines.texi @@ -0,0 +1,1936 @@ +\input texinfo @c -*-texinfo-*- +@setfilename guidelines.info + +@set DATE 26th January 1996 + +@setchapternewpage off + +@iftex +@center @titlefont{Debian GNU/Linux Packaging Guidelines} +@tex +\vskip2pt \hrule height 2pt width \hsize \vskip2pt +@end tex +@sp 0.5 +@center @value{DATE} +@end iftex + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Guidelines: (guidelines). How to make Debian packages. +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@node Top, Additional Information, (dir), (dir) + +@ifinfo +@top Debian GNU/Linux Packaging Guidelines +@end ifinfo + + This file documents the steps that must be taken in the preparation +of a Debian GNU/Linux package. All submissions to be included in the +distribution proper and all packages to be considered for @file{contrib} +or @file{non-free} availability @emph{must} conform to the guidelines +and standards described in this document or they cannot be included or +made available at the archive with the distribution. + + Please read the Guidelines carefully. If you have comments or +questions, please contact @code{debian-devel@@pixar.com}. If you are +planning on going further than just contributing a package (i.e., if +you plan to maintain it for an extended period of time or if you are +generally interested in becoming more involved in the Project), you +should join the @code{debian-devel} mailing list. For more details, +read @file{info/mailing-lists.txt}, available at any Debian GNU/Linux +archive. + + (This file was last updated on @value{DATE}. Please check the most +recent @file{dpkg} package at any Debian GNU/Linux archive for a +potentially more up to date copy.) + +@menu +* Additional Information:: Where other info is to be found. +* Package Copyright:: A few words about the importance of + understanding the package copyright. +* Package Content:: Requirements for the package content. +* Source Package:: Creating the source package. +* Binary Package:: Creating the binary package. +* Control Files:: The binary package control files. +* Appendix:: More specific details about some aspects. +@end menu + + + +@node Additional Information, Package Copyright, Top, Top +@unnumbered Additional Information + + These Guidelines are intended to be fairly general. More specific +information is available about certain aspects of building packages, +such as how to use the features of Init under Debian GNU/Linux and how +to interact with some more technical details of dpkg's operation. This +information can be found in the directory @file{doc/package-developer} +at any Debian GNU/Linux archive. At the time of this writing, the +following documents are available: + +@table @file +@item virtual-package-names-list.text +The list of virtual package names currently in use, together with the +procedure for getting new virtual package names allocated. +@item auto-deconfiguration.txt +How dpkg can sometimes automatically deconfigure packages in order to +do bulk installations smoothly. +@item dpkg-essential-flag.txt +How to tell dpkg a package is essential and should not be removed. +(This is for the use of base system packages only.) +@item dpkg-disappear-replace.txt +What happens when a package appears to have been completely replaced. +@end table + + In the future, we hope also to make available: + +@table @file +@item copyright.txt +How to choose a good copyright notice to attach to new programs. +@item version-ordering.txt +The algorithm with which packages' version numbers are compared. +@end table + + Also, you should download the sample files and the sample package +(GNU Hello) available in @file{standards/samples}. You may use any +of this material as a starting point for new packages. The following +sample files, incidentally, are available: + +@itemize @bullet +@item debian.README +@item debian.control +@item debian.postinst +@item debian.postrm +@item debian.rules +@end itemize + +Some more detailed information about certain topics is available in the +appendix to this document (@pxref{Appendix}). + + +@node Package Copyright, Package Content, Additional Information, Top +@unnumbered Package Copyright + + Please study the copyright of your submission @emph{carefully} +and @emph{understand it} before proceeding! If you have doubts or +questions, please ask! + + In order to understand how we classify and distribute certain +packages, it is important to understand the distinction between being +freely available and being freely redistributable. + + Being @dfn{freely available}, quite simply, means that the software +can be made available freely, at least for non-commercial purposes and +in its original, unmodified form. This includes packages made available +freely that have restrictions on non-commercial use, redistribution of +modifications, etc. Being freely available, therefore, has nothing to +do with being able to modify and redistribute the software. It only +means that you can get a copy of the software without having to pay +(and it does not necessarily mean that you can @emph{use} the software +without having to pay---shareware is an example of freely available +software). + + @dfn{freely redistributable}, while generally being freely available, +goes beyond just being freely available. Freely redistributable means +that that the software, in addition to being able to be made available +freely, must be able to be freely modified and redistributed without +restriction. + + All submissions to be included in the distribution proper @emph{must} +be freely redistributable. + + In addition to the distribution, the Project maintains two separate +archives of software packages with the distribution: the @file{contrib} +archive and the @file{non-free} archive. + + @file{contrib} is an archive of user-contributed packages that are +not maintained by the Project, packages that were once maintained by the +Project but that are no longer actively maintained, and packages that +are maintained by the Project but that are not yet considered ready for +inclusion in the distribution proper (i.e., ALPHA and BETA packages). +As above, all submissions for inclusion in the @file{contrib} archive +@emph{must} be freely redistributable. + + @file{non-free} is an archive of packages with either restrictive or +unclear terms of copying or modification. If a package has @emph{any} +restrictions on modification or redistribution, it can not be included +in the distribution or @file{contrib} archive. It can only be included +in the @file{non-free} archive, and then only if it is freely available. + + In summary, in order to be included in the distribution proper or the +@file{contrib} archive, a package must be @emph{freely redistributable}. +Anyone must be able to make copies of it, modify it, redistribute it with +their modifications in place, include it on a CD-ROM, or generally sell +it. To be included in the @file{non-free} archive, a package may have +restrictions, as long as the package remains @emph{freely available}. We +must be available to make it available freely at the archive, and anyone +must be able to make copies of it and use it for at least non-commercial, +personal purposes. Software that will typically be included in +@file{non-free} are software that does not allow commercial distribution, +software that does not allow modification or redistribution of +modifications, commercial ``demos'', and ``shareware''. + + When in doubt, send mail to @file{iwj10@@cus.cam.ac.uk} and +@file{imurdock@@debian.org}. Be prepared to provide us with the +copyright statement. Software covered by the GPL, public domain +software and BSD-like copyrights are safe; be wary of the phrases +``commercial use prohibited'' and ``distribution restricted''. + + Every package submission @emph{must} be accompanied by verbatim copy +of its copyright (with the exceptions of public domain packages and +those covered by the UCB BSD licence or the GNU GPL or LGPL; in these +cases simply indicate which is appropriate). This information must be +included in a file installed to the directory @file{/usr/doc/copyright}. +See below for details. + + + +@node Package Content, Source Package, Package Copyright, Top +@unnumbered Package Content + + The following requirements apply equally to both the binary and +source packages. In either case, when files have been installed, +they must conform to the requirements described in this section. + + The primary rule in Debian GNU/Linux is to follow the Linux @dfn{File +System Standard} (@dfn{FSSTND}). The location of installed files +@emph{must} comply @emph{fully} with the FSSTND. The latest version of +this document can be found alongside the Guidelines or at +@file{tsx-11.mit.edu} in @file{/pub/linux/docs/linux-standards/fsstnd}. +Specific questions about following the standard should be addressed to +Daniel Quinlan, the FSSTND coordinator, at @code{quinlan@@yggdrasil.com}. + + In addition to the FSSTND, all Debian GNU/Linux packages must follow +the guidelines below. + +@itemize @bullet +@item +Directories should be mode 755 or (for group-writability) mode 2775, +with the exception of special ``system'' directories that need to be +another mode. The ownership of the directory should be consistent with +its mode---if a directory is mode 2775, it should be owned by the group +that needs write access to it, of course. Use common sense in assigning +permissions and ownerships to directories, and make sure that what is +done is secure if it is ``non-standard''. + +@item +Normal binaries should be mode 755 and owned by @code{root.root}. If +there is a good reason to use a different mode or ownership, you may do +so, but you must try to be as consistent as possible with the rest of +the system. If you need to use a different mode or ownership, please +discuss it with @code{imurdock@@debian.org}. + +@item +Setuid binaries should normally be mode 4755 (not 4711!) and, of course, +owned by the appropriate user. + +@item +Setgid binaries should normally be mode 2755 (not 2711!) and, of course, +owned by the appropriate group. + +@item +Library files should generally be mode 644 and owned by +@code{root.root}. If the package requires different permissions +or ownerships to function correctly, they should be used instead. + +@item +Manual pages should be mode 644 and owned by @code{root.root}. The +@file{nroff} source must be installed. You should @emph{not} install a +preformatted ``cat page'', and you should only use sections 1 to 9---see +the FSSTND for more details. If no manual page is available for a +particular program, utility or function and this is reported as a bug on +debian-bugs, a symbolic link from the requested manual page to the +@file{undocumented}(7) manual page should be provided. This symbolic +link can be created from @file{debian.rules} like this: + +@smallexample +ln -s ../man7/undocumented.7 debian-tmp/usr/man/man[1-9]/the_requested_manpage.[1-9] +@end smallexample + +Do not close the bug report until a proper manpage is available. You +may forward the complaint to the upstream maintainers, and mark the bug +as forwarded in the Debian bug tracking system. The GNU Project do not +in general consider the lack of a manpage to be a bug, but we do - if +they tell you to go away leave the bug open anyway. + +@item +Info documents should be mode 644, owned by @code{root.root}, and +compressed with @file{gzip -9} when installed. The package must call +@file{install-info} to update the Info @file{dir} file. This should +be done in the post-installation script (@file{postinst}), like this: + +@smallexample +install-info --quiet /usr/info/foobar.info +@end smallexample + +The entries should be removed by the pre-removal script (@file{prerm}), +like this: + +@smallexample +install-info --quiet --remove /usr/info/foobar.info +@end smallexample + +It is also a good idea to specify a section for the Info @file{dir} +entry. This is done with the @file{--section} switch. To determine +which section to use, you should use look at @file{/usr/info/dir} on +your system and choose the most relevant (or create a new section if +none of the current sections are relevant). + +If @file{install-info} cannot find a description entry in the Info file +you will have to supply one. See @file{install-info}(8) for details. + +@item +If a package contains any shared libraries you will have to invoke +@file{ldconfig} in both the @file{postinst} and @file{prerm} scripts +to correctly update the library links. See @file{ldconfig}(8) for +details. + +@item +Any additional documentation that comes with the package can be +installed at the discretion of the package maintainer. Text +documentation should be mode 644, owned by @code{root.root}, installed +to @file{/usr/doc}, and compressed with @file{gzip -9} unless it is small. + +If a subdirectory of @file{/usr/doc} is warranted, please do create one. +Please do not install DVI, PostScript, or large textual documentation in +the same package; upload such documentation as a separate package +(installing its files in @file{/usr/doc}) so that it can be made +available with the distribution. If a user has the need for the +documentation, they can easily get it from the archive, CD-ROM, etc., +but it should not take up disk space on the machines of the user who do +not need or want it installed. + +@item +Create a file named @file{/usr/doc/copyright/<@i{package}>} which gives +details of the authorship and copyright of the package. If the package +is distributed under the GNU General Public Licence, the GNU Library +General Public Licence or the Regents of the University of California at +Berkeley (BSD) licence, please say so instead of including a copy of the +licence. The files @file{BSD}, @file{GPL}, and @file{LGPL} will be +available in the @file{/usr/doc/copyright} directory for you to refer +to. @file{/usr/doc/copyright/<@i{package}>} should not be compressed. + +@emph{All} authorship and copyright information from the original source +package must be included in the @file{/usr/doc/copyright/<@i{package}>} +file. + +@item +Any example files (for example, sample configuration files) should +be placed in the directory @file{/usr/doc/examples}. If the file is +normally a hidden file, such as @file{.emacs}, then please call it +@file{dot.emacs}, to avoid confusion. Again, you may create a +subdirectory if it is needed. + +@item +All symbolic links should be relative, not absolute. Absolute links, +in general, cause problems when a file system is not mounted where it +``normally'' resides (for example, when mounted via NFS). In certain +cases, however, relative links may also cause similar problems. I +have generally made links into @file{/etc} and @file{/var} absolute +and all other links relative. There may be other cases in which +absolute links are necessary. + +Therefore, in the @file{Makefile} or @file{debian.rules}, do not do: +@smallexample +install: all + [...] + ln -fs /usr/bin/gcc /usr/bin/cc + [...] +@end smallexample +Instead, do: +@smallexample +ln -fs gcc /usr/bin/cc +@end smallexample +or +@smallexample +( cd /usr/bin ; ln -fs gcc cc ) +@end smallexample + +Please do not create hard links in the manual page directories. In +these cases, you should use relative symbolic links or files that +@file{.so} (roff for `source') others instead. + +@item +All command scripts should have a @code{#!} line naming the shell to be +used to interpret them. + +@item +In the case of Perl scripts this should be @code{#!/usr/bin/perl} or +sometimes @code{#!/bin/perl}, as follows: if the script is a critical +one that may be called when the @file{/usr} partition is unmounted or +broken it should use @file{/bin/perl}. Otherwise (especially if the +script is not specifically targetted at Debian) it should use Perl's +standard location, @file{/usr/bin/perl}. + +@item +Generally the following compilation parameters should be used: + +@display + CC = gcc + CFLAGS = -O2 -g -Wall # sane warning options vary between programs + LDFLAGS = # none (or -N, if appropriate; see below) + install -s (or strip) +@end display + +Note that all installed binaries should be stripped, either by using the +@code{-s} flag to @file{install}, or by calling @file{strip} on the +binaries after they have been copied into the @file{debian-tmp} but +before the tree is made into a package. + +Make sure that you do not link with @code{-g}, as this makes a.out +compilers produce huge statically linked binaries. The @code{-g} flag +is useful on compilation so that you have available a full set of +debugging symbols in your built source tree, in case anyone should file +a bug report involving (for example) a core dump. + +@code{-N} should only be used on binaries that are very small (less than +8K with the @code{-N} option, roughly) and are not likely to have +multiple instances in memory. Do not use @code{-N} on daemons, no +matter how small they are. + +It is up to the package maintainer to decide what compilation options +are best for the package. Certain binaries (such as +computationally-intensive programs) may function better with certain +flags (@code{-O3}, for example); feel free to use them. Please use good +judgment here. Don't add flags for the sake of adding flags; only add +flags if there is good reason to do so. + +@item +Please make sure that you use only released versions of shared libraries +to build your packages; otherwise other users will not be able to run +your binaries properly. Producing source packages that depend on +unreleased compilers is also usually a bad idea. + +@item +Logfiles should usually be named @file{/var/log/<package>}, or +@file{/var/log/<package>.<something>} if you have several logfiles. It +may be appropriate to create a directory. Make sure that any logfiles +are rotated occasionally so that they don't grow indefinitely; the best +way to do this is to use @file{savelog} from the cron package in an +@file{/etc/cron.daily}, @file{/etc/cron.weekly} or +@file{/etc/cron.monthly} script. + + +@item +Please check with the base system maintainer (Ian Murdock) before using +users or groups other than @code{root} and others specified in this +document. +@end itemize + + + +@node Source Package, Binary Package, Package Content, Top +@unnumbered Source Package + + The source package should contain a file called @file{debian.rules} +which contains at least the following targets, to be invoked in the top +level directory: + +@smallexample +build +binary +clean +@end smallexample + +@file{debian.rules} should start with + +@smallexample +#!/usr/bin/make -f +@end smallexample + +@noindent and be executable. It is a good idea to arrange for it not +to fail obscurely when invoked in the wrong directory, for example by +testing for the existence of a file in the source directory. + +@itemize @bullet +@item +The @file{build} target should perform all non-interactive configuration +and compilation of the package. If a package has an interactive +pre-build configuration routine, the source package should be built +@emph{after} this has taken place. + + For some packages, notably ones where the same source tree is +compiled in different ways to produce two binary packages, the +@file{build} target does not make much sense. For these packages it is +good enough to provide two (or more) targets (@file{build-a} and +@file{build-b} or whatever) for each of the ways of building the +package, and a @file{build} target that does nothing. The @file{binary} +target will have to build the package in each of the possible ways and +make the binary package out of each. + +@item +The @file{binary} target of @file{debian.rules} should be all that is +necessary for the user to build the binary package. The binary package +should be created using @file{dpkg} and placed in the parent of the top +level directory. The next section describes how to construct binary +packages from the @file{binary} target. + +@item +The @file{clean} target should undo the effects of the @file{build} +target and the @file{binary} target, except that it should leave alone +any @file{../<@i{package}>-<@i{version}>.deb} file created by a run of +@file{binary}. + +@item +Additional targets may exist in @file{debian.rules}. We recommend using +@file{source} and @file{diff} targets to build the Debianised source +package and the Debianisation context diff, respectively. These files +should be placed in @file{../foo-<@i{version}>.tar.gz} and +@file{../foo-<@i{version}>.diff.gz}. The @file{install} target, for +installing into a running system direct from the Debianised source +tree, is no longer required. The sample @file{debian.rules} provides +@file{source} and @file{diff} targets that should work with little or +no alteration, providing that the package-specific variables at the top +of the script have been properly defined. + +@item +If you need to edit a @file{Makefile} where @file{configure} scripts +are used, you should edit the @file{.in} files rather than editing +the @file{Makefile} directly. This allows the user to reconfigure +the package if necessary. You should @emph{not} configure the package +and edit the generated @file{Makefile}! This makes it impossible for +someone else to later reconfigure the package. + +@item +Please document your changes to the source package so that future +package maintainers know what has been changed. To do this, include +a description of your changes in the @file{debian.README} (which, as +described above, should already contain authorship and copyright +information!) and include relevant information such as your name, +electronic mail address, date, etc. The @file{debian.README} file +should also document any `unusual' packages which must be installed for +this one to compile. + +@item +If changes to the source code are made that are applicable to Linux +systems or systems in general please try to get them included in the +upstream version of the package by supplying the upstream authors with +the changes in whatever form they prefer. + +If changes to the source code are made, please use a @file{define}. If +they are changes required to compile or function under Linux in general, +use @file{LINUX}. If it is a cosmetic or functional change, use +@file{DEBIAN}. + +@item +Create the source package using @file{tar}, and use @file{gzip -9} to +compress it. Source packages should be named in the form +<@i{package}>-<@i{version}>.tar.gz---for example, +@file{fileutils-3.9-3.tar.gz}. + +NB, here @code{<@i{version}>} is the full Debian version number, in the +form @code{<@i{original_version}>-<@i{debian_revision}>} (see below), +but the tarfile should unpack into a directory named +@code{<@i{package}>-<@i{original_version}>} (again, see the section +below on version numbering). + +@item +Create the context diff against the original package using @file{diff +-cNr}, and use @file{gzip -9} to compress it. Context diffs should be +named in the form <@i{package}>-<@i{version}>.diff.gz---for example, +@file{fileutils-3.9-3.diff.gz}. +@end itemize + + Please note that the package and patch filenames do @emph{not} need +to fit in MS-DOS 8+3. They will be made available under an alternative +8+3 name in the archive by the archive maintainer, using a symlink. + + + +@node Binary Package, Control Files, Source Package, Top +@unnumbered Binary Package + + The @file{binary} target of the source package @file{debian.rules} +file should do the following (see the sample @file{debian.rules} +for an implementation that you are free to modify and use in your own +packages, of course): + +@itemize @bullet +@item +Create an empty directory in the top-level directory of the source +package (deleting it first, if necessary), and install the files +belonging to this package in that directory. For example, the directory +could be called @file{debian-tmp} and would probably contain directories +@file{debian-tmp/usr/bin}, @file{debian-tmp/usr/lib}, etc. +(@file{debian-tmp} is the name traditionally used, and it is used in +the sample @file{debian.rules} file, so we will use that name in the +Guidelines.) + +@item +Make sure that all the files under @file{debian-tmp} have the correct +ownerships and permissions (@pxref{Package Content}, for more information +about file locations, ownerships, and permissions.) + +@item +Create a subdirectory of @file{debian-tmp} called @file{DEBIAN}. This +directory contains the package control information, including at the +very least the master information file named @file{control}. The next +section describes the semantics and syntax of the files required and +allowed here. + +@item +Run @file{dpkg} to create the binary package, using something like + +@smallexample +dpkg --build debian-tmp +@end smallexample + +This will create a file called @file{debian-tmp.deb}, from the +@file{debian-tmp} directory. You should rename this file to +@file{../<@i{package}>-<@i{version}>.deb} after it is built. + +After the @file{binary} target has done all this, the +@file{<@i{package}>-<@i{version}>.deb} file in the parent directory is +the binary distribution. This file may be distributed and installed on +any Debian GNU/Linux system with @file{dpkg} in the same manner and +using the same methods as all packages are installed to the system. + +@item +If a single source package corresponds to several binary packages, there +should usually be a @file{debian.rules} file with a single @file{binary} +target that builds all the binary packages involved and move all packages +to the parent directory of that containing the source package. + +In this case, you should choose binary package names which are meant to +make clear the close relationship between the binary packages and which +source package the binary packages came from (for example, the +@file{texinfo} source package build two binary packages: @file{texidoc} +and @file{texinfo}). You should place the appropriate binary package +name in the @file{Package} field of the control file (not the source +package name), and you should consider whether the other binary packages +that come from the same source tree should be mentioned in the +@file{Depends}, @file{Recommends} or @file{Suggests} fields. You +should put the source package name in the @file{Source} field. + +You should retain the source package version numbering in the +@file{Version} field, if possible---the version number should be the +same for the Debianised source tree and all the binary packages +generated from it. It is more important, though, that the version +numbers sort correctly. See below for details of version numbers. +@end itemize + + + +@node Control Files, Appendix, Binary Package, Top +@unnumbered Control Files + + Each binary package contains, in addition to the files that comprise +the actual package, a set of text files that control how @file{dpkg} +installs, configures, upgrades, removes, etc. the package. These files +are called @dfn{control files}. When creating the package, the control +files should placed in a directory called @file{DEBIAN}, as described +earlier (@pxref{Binary Package}, for further information). + +The control information files are: + +@table @code +@item control +The master package control information file. +@item conffiles +A list of package configuration files. +@item preinst +The package pre-installation script. +@item postinst +The package post-installation script. +@item prerm +The package pre-removal script. +@item postrm +The package post-removal script. +@end table + + Of these, only @file{control} is required. The various installation +scripts, and the configuration files list, will only be used if they are +present. + +@menu +* control:: +* conffiles:: +* Installation and Removal Scripts:: +* Dependencies and Conflicts:: +* Package Classification Fields:: +@end menu + +@node control, conffiles, Control Files, Control Files +@unnumberedsec control + + The @file{control} file contains a number of fields. Each field +begins with a field name, such as @file{Package} or @file{Version} +(case insensitive), followed by a colon and optionally some spaces or +tabs (a single space is conventional). Then comes the body of the +field, which may be several lines long; each continuation line must +start with at least one space or tab. (These are the same rules as +apply to RFC822 mail headers.) Blank lines are not permitted in the +control file. + + The required fields in the control file are the following: + +@table @code +@item Package +The name of the package. +@item Description +The description of the package. How to write an extended and more +usefull description field can be found in @pxref{How to write the Description control file field}. +@item Maintainer +The name and e-mail address of the maintainer of the package. +@item Version +The version number in the format +@code{<@i{original_version}>-<@i{debian_revision}>}. +@end table + + Each field has a particular format and meaning for the package +installation tools. + +The value of @file{Package} should be the name of the package. +Package names must start with an alphanumeric, must be at least two +characters, and may contain only alphanumerics and the characters +- + . @@ : = % _ (that is, hyphen, plus, stop, at, colon, equals, +percent and underscore). They are not case sensitive. + + The @code{Maintainer} field should be in the form + +@smallexample +Joe J. Bloggs <jbloggs@@foo.com> +@end smallexample + +@noindent Note that this will not be useable as an email address if +the name given contains full stop characters, because of a silly +restriction in the Internet mail standards. If you want to use this +as an email address in a program you should check for full stops and +change the string to the form @code{jbloggs@@foo.com (Joe J. Bloggs)} +if you find any. + + The @code{Version} field should be the version number of the +package. For most packages which are not written specifically for +Debian, this should be in the form + +@smallexample +Version: <@i{original_version}>-<@i{debian_revision}> +@end smallexample + +@noindent where @file{<@i{original_version}>} is the original package +version number in whatever form the original package uses and +@file{<@i{debian_revision}>} indicates which ``debianisation'' this is +(this should usually be a plain number or perhaps a two numbers +separated by a full stop, and should be incremented each time the +package is changed or updated). + + Packages which are written specifically for Debian do not have a +@i{debian_revision}, and their version number should simply be +@i{version} (which should not contain any hyphens, to avoid +confusion). + + There is an ordering imposed on version numbers, described in +@file{version-ordering.txt}. This ordering is designed to `do the right +thing' in most circumstances; if your package has an version number in +an unusual format you may need to reformat it somewhat to get the +ordering right. This is important because @file{dpkg} is (for example) +reluctant to downgrade packages. + + The optional fields in the control file are the following: + +@table @code +@item Depends +The names of prerequisite packages. +@item Recommends +The names of related, recommended packages. +@item Suggests +The names of related, optional packages. +@item Conflicts +The names of packages which conflict with this package. +@item Provides +The names of virtual packages which this package provides. +@item Priority +The `priority' of the package, as shown and used by @file{dselect}. +@item Section +The `section' of the package, as shown and used by @file{dselect}, and +used as a location for the package in the distribution. +@item Essential +A boolean field used by the base packages. +@item Pre-Depends +Used by base packages to ensure that (for example) shared libraries are +present befoore they are upgraded. +@item Source +Gives the name of the source package when several binary packages are +generated from a single source tree. +@end table + +@noindent See below for details of the semantics and syntax of these +fields. Most packages will need at least a @code{Depends} field. + + An example of a @file{control} file would be: + +@smallexample +Package: smail +Version: 3.1.29.1-13 +Maintainer: Ian Jackson <iwj10@@cus.cam.ac.uk> +Recommends: pine | mailx | elm | emacs | mail-user-agent +Suggests: metamail +Depends: cron, libc5 +Conflicts: sendmail +Provides: mail-transport-agent +Description: Electronic mail transport system. + Smail is the recommended mail transport agent (MTA) for Debian. + . + An MTA is the innards of the mail system - it takes messages from + user-friendly mailer programs and arranges for them to be delivered + locally or passed on to other systems as required. + . + In order to make use of it you must have one or more user level + mailreader programs such as elm, pine, mailx or Emacs (which has Rmail + and VM as mailreaders) installed. If you wish to send messages other + than just to other users of your system you must also have appropriate + networking support, in the form of IP or UUCP. +@end smallexample + + In this case, @file{mail-user-agent} is a virtual package +representing any user mailer program; the actual package names +@file{pine} is quoted for the reasons described in +@file{dependency-ordering.txt}, and the others because older versions +of those packages do not have the appropriate @file{Provides} field. + +@node conffiles, Installation and Removal Scripts, control, Control Files +@unnumberedsec conffiles + + The contents of @file{conffiles} is simply a list of configuration +files in the package. When installing the package, @file{dpkg} uses +an intelligent method to update these files. This will ensure that +package-specific configuration files are not overwritten when a package +is upgraded, unless the user wishes the installation tools to do so. + + Typically, files listed in conffiles are package-specific +configuration files, which (according to the Linux Filesystem Standard) +are stored in @file{/etc}. For example, the @code{sendmail} package may +contain the file @file{/etc/sendmail.cf}, which we do not wish to +overwrite automatically when the user upgrades the sendmail package. +Only those files listed in @file{DEBIAN/conffiles} will be updated +intelligently when a package is upgraded; all other files in the package +will be overwritten by the upgrade process. + + Configuration files which will be functional as shipped and will +probably need little or no local editing should simply be listed the +@file{conffiles} file; in this case you need read no further. + + For packages whose configuration files will need modification on +most systems there are two sensible approaches. Which one is chosen +depends on how hard the configuration problem is and how much time the +package maintainer has available. + + One option is for you to ship a minimal `best-effort' file in +@file{/etc}, and list the file in @file{conffiles}. This will mean that +the user will have to go and edit the file themselves to get the package +to work properly, of course. The next time they upgrade the package, if +you haven't changed the file version, their old file will be left in +place. If you have modified your version then the user will get a +prompt asking them which version of the file they want, theirs or yours. +They will then usually have to resolve the discrepancies manually. + + The other option is to be preferred, if you can do it: do not put a +copy of the configuration file in the package at all. Instead, you +check in the postinst whether the file exists, and if it doesn't you +prompt the user for the information you need to create a good one. This +is obviously harder work. + + You also have to remember that you will have to keep up with your +package's changes: if you discover a bug in the program which generates +the configuration file, or if the format of the file changes from one +version to the next, you will have to arrange for the postinst script to +do something sensible---usually this will mean editing the installed +configuration file to remove the problem or change the syntax. You will +have to do this very carefully, since the user may have changed the +file, perhaps to fix the very problem that your script is trying to deal +with---you will have to detect these situations and deal with them +correctly. + + If you do go down this route it's probably a good idea to make the +program that generates the configuration file(s) a separate program in +@file{/usr/sbin}, by convention called @i{package}@code{config}, and +then run that if appropriate from the post-installation script. The +@i{package}@code{config} program should not unquestioningly overwrite an +existing configuration---if its mode of operation is geared towards +setting up a package for the first time (rather than any arbitrary +reconfiguration later) you should have it check whether the +configuration already exists, and require a @code{--force} flag to +overwrite it. + + @file{conffiles} should almost certainly list all the files contained +in your package in the @file{/etc} directory. There may also be other +files somewhere that the user is expected to edit, which should also be +included. Note, however, that the FSSTND specifies that configuration +files must be in @file{/etc}. No Debian package should contain +configuration files in @file{/usr/etc}, and all programs should refer to +configuration files in @file{/etc}. + +@noindent For example, the TCP/IP package might use a conffiles which contains + +@smallexample +/etc/init.d/netbase +/etc/gateways +/etc/protocols +/etc/services +/etc/hosts.allow +/etc/hosts.deny +/etc/rpc +@end smallexample + +@noindent and so on; the files + +@smallexample +/etc/hosts +/etc/inetd.conf +/etc/host.conf +/etc/networks +/etc/resolv.conf +@end smallexample + +@noindent might be generated by an interactive configuration program, +and would then not be included in the package or listed in the +@file{conffiles}. + +@node Installation and Removal Scripts, Dependencies and Conflicts, conffiles, Control Files +@unnumberedsec Installation and Removal Scripts + + The scripts @file{preinst}, @file{postinst}, @file{prerm}, and +@file{postrm} are optional (Bash or Perl) scripts. As the names +would indicate, if these scripts exist, they will be executed before +installing the package, after installation, before package removal, +and after removal, respectively. + + They are given arguments which indicate the precise situation and +action being performed---see @file{maintainer-script-args.txt} for +details of exactly when each of the scripts is invoked and what its +arguments are. Extra arguments and situations may be added later, so +you should not test the number of arguments to your script to determine +the situation, and you should choose the sense of your `if it is this +then do this otherwise do that' tests carefully. + + These scripts can be used to perform any site-specific package +configuration. + + Because the scripts will be exectued by the dpkg front-end, it is +guaranteed that the scripts will be executed interactively. User input +from the scripts should be read from standard input, not the user's +terminal. Similarly, output should be sent to standard output. + + If your maintainer scripts need to prompt for passwords and/or do +@i{full-screen} interaction should do these things to and from +@file{/dev/tty}, since @file{dpkg} will at some point redirect scripts' +standard input and output so that it can log the installation process. +Likewise, because these scripts may be executed with standard output +redirected into a pipe for logging purposes, Perl scripts should set +unbuffered output by setting @code{$|=1} so that the output is printed +immediately rather than being buffered. + + The scripts must be idempotent, and they must clean up after +themselves properly. Ie, they must do the right thing if run multiple +times, even if previous runs failed halfway through. This is so that if +any errors occur, or if the @file{dpkg} run is interrupted, the user can +recover by rerunning @file{dpkg}, and/or by upgrading to a new version +and then rerunning the failed operation. + + These scripts should avoid producing output which it is unnecessary +for the user to see and should rely on @file{dpkg} to stave off boredom +on the part of a user installing many packages. This means, amongst +other things, using the @file{--quiet} option on @file{install-info}. + + Packages should try to minimise the amount of prompting they need to +do, and they should ensure that the user will only every be asked each +question once. This means that packages should try to use appropriate +shared configuration files (such as @file{/etc/papersize} and +@file{/etc/news/server}), rather than each prompting for their own list +of required pieces of information. + + It also means that an upgrade should not ask the same questions +again, unless the user has used @code{dpkg --purge} to remove the +package's configuration. The answers to configuration questions should +be stored in an appropriate place in @file{/etc} so that the user can +modify them, and how this has been done should be documented. + + If a package has a vitally important piece of information to pass to +the user (such as "don't run me as I am, you must edit the following +configuration files first or you risk your system emitting +badly-formatted messages"), it should display this in the +@file{postinst} script and prompt the user to hit Return to acknowledge +the message. Copyright messages do not count as vitally important (they +belong in @file{/usr/doc/copyright}; neither do instructions on how to +use a program (these should be in on line documentation, where all the +users can see them). + + They should return a zero exit status for success, or a nonzero one +for failure. Note that if a script is a @code{#!/bin/sh} script it +should probably start with @code{set -e}, to avoid continuing after +errors---see @file{bash}(1) for details. Perl scripts should check for +errors when making calls such as @code{open}, @code{print}, +@code{close}, @code{rename} and @code{system}. + + If these scripts exist they should be left in the @file{DEBIAN} +directory with execute permission enabled and should contain an +appropriate @code{#!} line, such as @code{#!/bin/bash} for a +@code{bash} script or @code{#!/bin/perl} for a Perl script (see +above). + +@node Dependencies and Conflicts, Package Classification Fields, Installation and Removal Scripts, Control Files +@unnumberedsec Conflicts, Depends, Suggests, Recommends and Provides + + The @file{Depends} field lists packages that are required for this +package to provide a significant amount of functionality. The package +maintenance software will not allow a package to be installed without +also installing packages listed in its @code{Depends} field, and will +run the @code{postinst} scripts of packages listed in @code{Depends} +fields before those of the packages which depend on them, and run the +@code{prerm} scripts before. + + Packages containing dynamically-linked executable binaries (this +includes almost all C programs) should include a @file{Depends} field +which mentions the shared C library required for the program to run. +For a.out binaries linked against @file{libc.so.4} the relevant package +name is @file{libc} (for the a.out stable 0.93 tree) or @file{libc4} +(for the unstable development 1.1 tree); for ELF binaries linked against +@file{libc.so.5} the relevant package name is @file{libc5}. + + The @code{Recommends} field lists packages that would be found +together with this one in all but unusual installations. The user-level +package maintenance program @file{dselect} will warn the user if they +select a package without those listed in its @code{Recommends} field. +Note that @code{Recommends} fields do not currently have any implications +for the order in which the maintainer scripts are run. + + The @code{Suggests} field lists packages that are related to this one +and can perhaps enhance its usefulness, but without which installing +this package is perfectly reasonable. The package maintenance software +will not moan at the user for not selecting @code{Suggests} related +packages, but may use the information in the @code{Suggests} field to +assist the user during package selection. + + The syntax of @code{Depends}, @code{Recommends} and @code{Suggests} +is a list of groups of alternative packages. Each group is a list of +packages separated by vertical bar (or `pipe') symbols, @code{|}. The +groups are separated by commas. Each package is a package name +optionally followed by a version number specification in parentheses. A +version number may start with a @code{>=}, in which case that version or +any later will match, or @code{<=} for that version or any earlier +version. A version number starting with a @code{>>} or @code{<<} will +respectively match any later or earlier version. If a version number or +a version number starting with @code{=} is specified an exact match is +required. Commas are to be read as `AND', and pipes as `OR', with pipes +binding more tightly. + + Versions of dpkg before 1.0.9 used @code{<} and @code{>} for +@code{<=} and @code{>=} (these are still supported for backward +compatibility), and did not support @code{<<} and @code{>>}. + + The @code{Conflicts} field lists packages that conflict with this +one, for example by containing files with the same names (an example +would be Smail vs. Sendmail). The package maintenance software will not +allow conflicting packages to be installed. Two conflicting packages +should each include a @code{Conflicts} line mentioning the other. + + The syntax of @code{Conflicts} is a list of package names (with +optional version numbers), separated by commas (and optional +whitespace). In the @code{Conflicts} field the comma should be read as +`OR'. + + The @code{Provides} field lists the names of any `virtual packages' +of which this packages is to be considered an instantiation. Virtual +packages are used to allow packages to refer to a service they require +(such as the availability of @file{/usr/sbin/sendmail}) without having +to know the names of all the relevant packages. The virtual package +names defined in @code{Provides} fields may be used in other packages' +@code{Depends}, @code{Recommends}, @code{Suggests} and @code{Conflicts} +fields. For more information about how to use virtual packages and +which virtual package names to use read @pxref{Virtual dependencies} and +@file{doc/package-developer/virtual-package-names-list.text}. + + The syntax of @code{Provides} is a list of package names separated by +commas (and optional whitespace). + +@node Package Classification Fields, , Dependencies and Conflicts, Control Files +@unnumberedsec Priority, Section and Essential + + The @code{Priority} and @code{Section} fields are used by +@file{dselect} when displaying the list of packages to the user. There +is no need to put them into a package, since these are usually set by +the distribution maintainers in the @file{Packages} file. + + However, if a user installs a package which is not part of the +standard distribution, or without downloading and updating from a new +@file{Packages} file, the information about the priority and section of +a package will be absent, and the @file{dselect} package listing will +have the package listed under `unclassified'. It is permissible for a +package to include @code{Section} or @code{Priority} fields to improve +this; however, if you do this you should make sure you keep the +information up to date so that users are not shown conflicting +information. The @code{Section} field can also be used by the +distribution maintainers as a suggestion about which section you think +is most appropriate for your package. + + The values for the @code{Section} and @code{Priority} fields should be +determined by the distribution maintainers; if you don't know what to +put in them just leave them out. You can add them later, if you like, +but remember that you'll then have to reissue your package if the +distribution maintainers change the classification of your package. + + The @code{Essential} field should only appear in packages in the +installation's base system. If it is set to @code{yes} then @file{dpkg} +will not remove the package even if asked to, and will make certain +minor modifications to its installation procedures. The only other +legal value is @code{no}, which is equivalent to the absence of the +field. + +@appendix +@node Appendix, , Control Files, Top +@unnumbered Appendix +@comment node-name, next, previous, up +@menu +* configuration files -- /etc/skel vs /usr/doc/examples:: +* How to write the Description control file field:: +* Configuration of init:: +* Maintainer script arguments and how @file{dpkg} does things:: +* Mail processing packages:: +* Virtual dependencies:: +@end menu + +@node configuration files -- /etc/skel vs /usr/doc/examples, How to write the Description control file field, Appendix, Appendix +@comment node-name, next, previous, up +@unnumberedsec configuration files -- /etc/skel vs /usr/doc/examples + +There seems to be a certain amount of confusion about @file{/etc/skel} +and @file{/usr/doc/examples}. The most important thing to remember is +the following: + +Files in @file{/etc/skel} will @emph{automatically} be copied into +@emph{new} user accounts by @file{adduser}. They should not +be referenced there by any program. Files in @file{/usr/doc/examples} +should not be installed automatically. + +Therefore, if the program in question need a dotfile to exist in advance +in @file{$HOME} to work @emph{sensibly} that dotfile should be installed +in @file{/etc/skel} (and listed in conffiles; @pxref{conffiles}). + +However, programs that require dotfiles in order to operate sensibly +(dotfiles that they do not create themselves automatically, that is) are +a bad thing, and that programs should be configured by the Debian +default installation as close to normal as possible. + +Therefore, if a program in a Debian package needs to be configured in +some way in order to operate sensibly that configuration should be done +in a site-wide global configuration file elsewhere in @file{/etc} (and +that file should be listed in conffiles). Only if the program doesn't +support a site-wide default configuration should a default per-user file +be placed in @file{/etc/skel} (and listed in conffiles; +@pxref{conffiles}). + +The idea is as follows: + +The sysadmin should ideally not have to do any configuration other than +that done @w{(semi-)}automatically by the postinst script. + +However, if they wish to change their configuration themselves +(because the configuration they want is beyond the scope of the +autoconfiguration, or because the autoconfiguration doesn't exist yet, +or because they just want to do it themselves for any reason) then +@file{/usr/doc/examples} exists as @emph{documentation} for their benefit. + +The only time these files should be read are by the sysadmin using their +favourite editor or pager, or @emph{perhaps} (in very complex packages) +by the postinst as a template to build on or modify. + +@file{/etc/skel} is part of the @emph{implementation} of this +configuration. It contains the files that are copied into new user +accounts. It should probably be as empty as we can make it. + +Examples: +@table @code +@item .profile +@file{/etc/skel} should not contain a @file{.profile} file. Anything +that needs to be done there should be done in @file{/etc/profile}. +Anything that should not go in @file{/etc/profile} (users can't avoid +running @file{/etc/profile}) probably should not be in the default +configuration. bash has generally good default behaviour. + +@item .bash_logout +Likewise, bash functions perfectly happily without a +@file{.bash_logout}, so none should be provided, since anything in it is +a deviation from the sensible default behaviour. + +@item .xsession +@file{/etc/skel} should not contain a @file{.xsession}. @file{xdm}'s +system-wide startup file @file{/usr/lib/X11/xdm/Xsession} supports a +system-wide default user configuration (which should probably be +@file{/etc/X11/Xsession} or some such) which may be overridden by +@file{.xsession} in the user's home directory. Therefore there is no +need for a @file{.xsession} to be installed by default and none should +be provided. + +Instead, a sensible @file{/etc/X11/Xsession} should be provided, and if +desired this can be used as a template by users who wish to install +their own configuration, or alternatively a more comprehensive example +with much commented-out interesting stuff could be put in +@file{/usr/doc/examples}. + +If the sysadmin wishes to change the system-wide default they should +probably do this by editing @file{/etc/X11/Xsession} rather than +creating the file in @file{/etc/skel}, because the former will affect +all user accounts that haven't explicitly overridden things by creating +their own file while the latter will only affect new accounts. + +All the configuration necessary for a program to function should be +provided. Therefore sysadmins will not need to go through +@file{/usr/doc/examples} while editing configuration files in +@file{/etc} except in extreme cases (like INN) where the configuration +was too difficult to do automatically. + +@item site-wide defaults +Site-wide defaults should not go in @file{/etc/skel}. In the case of +twm, for example, the system-wide default should be in +@file{/etc/X11/system.twmrc}. (The default location for this in X11R5, +btw, is in @file{/usr/lib/X11} somewhere, but we can't put it on +@file{/usr} because of CDROM distributions, etc - hence the FSSTND's +mandate to put configuration files in @file{/etc}.) + +@item .twmrc +There should be no @file{.twmrc} file in @file{/etc/skel}. You can have +one in @file{/usr/doc/examples} if you @emph{like}, but why bother if +@file{system.twmrc} is a good example (and indeed is the one the user is +using before they create their own)? + +@item m4 +@file{/usr/doc/examples} isn't mainly for example @emph{configuration +files}. It's for any kind of example file distributed with a package. +For example, GNU m4 comes with a whole pile of example m4 macro scripts, +which is exactly what @file{/usr/doc/examples} is for. +@end table + +Summary + +Files that should be installed in new user accounts should be in +@file{/etc/skel}, as that will ensure that they @emph{are} installed in +new user accounts! However, we should try to avoid the need for this. + +@file{/usr/doc/examples} is just what it says: documentation in the form +of examples. If a sysadmin is required to go and read these files for +their system to work they should be told about it. For example, here +is what the Smail postinst script says right at the start: + +@smallexample +I can do certain kinds of automatic configuration of your +mail system, by asking you a number of questions. Later you +may to confirm and/or correct your answers. In any case, +comprehensive information on configuring Smail is in +smail(5) and in /usr/doc/examples/smail and +/usr/doc/smail-admin-guide. +@end smallexample + +@node How to write the Description control file field, Configuration of init, configuration files -- /etc/skel vs /usr/doc/examples, Appendix +@unnumberedsec How to write the Description control file field + +The format of the @code{Description} field is as follows: + +@smallexample +Description: <single line synopsis> + <extended description over several lines> +@end smallexample + +The extended description has several kinds of line: + +@itemize @bullet +@item +Those starting with a single space are part of a paragraph. Successive +lines of this form will be word-wrapped when displayed. The leading +space will usually be stripped off. + +@item +Those starting with two or more spaces. These will be displayed +verbatim. If the display cannot be panned horizontally the displaying +program will linewrap them `hard' (ie, without taking account of word +breaks). If it can they will be allowed to trail off to the right. +None, one or two initial spaces may be deleted, but the number of spaces +deleted from each line will be the same (so that you can have indenting +work correctly, for example). + +@item +Those containing a single space followed by a single full stop +character. These are rendered as blank lines. This is the @emph{only} +way to get a blank line - see below. + +@item +Those containing a space, a full stop and some more characters. These +are for future expansion. @emph{Do not} use them. +@end itemize + +IMPORTANT and not so important TIPS: + +@itemize @bullet +@item +@emph{Always} start extended description lines with at least @emph{one} +whitespace character. Fields in the control file and in the Packages +file are separated by field names starting in the first column, just as +in RFC822. Forgetting the whitespace will cause @file{dpkg-deb} +(>=0.93.23) to produce a syntax error when trying to build the package. +If you force it to build anyway @file{dpkg} will refuse to install the +resulting mess. + +@item +@emph{Do not} include any completely @emph{empty} lines. These separate +different records in the Packages file, and are forbidden in control +files. See the previous paragraph for what happens if you get this +wrong. + +@item +The single line synopsis should be kept brief - certainly under 80 +characters. @file{dselect} displays the @emph{first 49} characters if +you're using an 80-column terminal. + +@item +Do not include the package name in the synopsis line. The display +software knows how to display this already, and you do not need to +state it. Remember that in many situations the user may only see the +synopsis line - make it as informative as you can. + +@item +The extended description should describe what the package does and how +it relates to the rest of the system (in terms of, for example, which +subsystem it is which part of). + +@item +Put important information first, both in the synopis and extended +description. Sometimes only the first part of the synopsis or of the +description will be displayed. You can assume that there will usually +be a way to see the whole extended description. + +@item +You may include information about dependencies and so forth in the +extended description, if you wish. + +@item +Do not use tab characters. Their effect is not predictable. +@end itemize + +Example control file for Smail: + +@smallexample +Package: smail +Version: 3.1.29.1-13 +Maintainer: Ian Jackson <iwj10@@cus.cam.ac.uk> +Recommends: pine | mailx | elm | emacs | mail-user-agent +Suggests: metamail +Depends: cron, libc5 +Conflicts: sendmail +Provides: mail-transport-agent +Description: Electronic mail transport system. + Smail is the recommended mail transport agent (MTA) for Debian. + . + An MTA is the innards of the mail system - it takes messages from + user-friendly mailer programs and arranges for them to be delivered + locally or passed on to other systems as required. + . + In order to make use of it you must have one or more user level + mailreader programs such as elm, pine, mailx or Emacs (which has Rmail + and VM as mailreaders) installed. If you wish to send messages other + than just to other users of your system you must also have appropriate + networking support, in the form of IP or UUCP. +@end smallexample + +@node Configuration of init, Maintainer script arguments and how @file{dpkg} does things, How to write the Description control file field, Appendix +@unnumberedsec Configuration of init + +The @file{/etc/init.d} directory contains the scripts executed by +init(8) when init state (or "runlevel") is changed. This includes the +boot process, when the multi-user state begins. Several of these +scripts are included with init and are intended to be executed +@emph{once}, usually at boot time. An example is +@file{/etc/init.d/boot}, which is executed at boot time to check and +mount file systems, activate swap, load kernel modules, etc.--everything +that needs to be done before the multi-user state begins. +@file{/etc/init.d} also contains the scripts that are executed when +entering runlevel 0 (halt), runlevel 1 (single-user) and runlevel 6 +(reboot). + +Packages can (and should) place scripts in @file{/etc/init.d} to start +or stop services at boot time or during a change of runlevel. These +scripts should be named @file{/etc/init.d/}<package>, and they should +accept one of two arguments: "start", which starts the services, or +"stop", which stops the services. These scripts should ensure that they +will behave sensibly if invoked with "start" when the service is already +running, or with "stop2 when it isn't---the best way to achieve this is +often to use @file{start-stop-daemon}. + +This script should not fail obscurely when the configuration files +remain but the package has been removed, as the default in dpkg is to +leave configuration files on the system after the package has been +removed. Only when it is executed with the `--purge' option will dpkg +remove configuration files. Therefore, you should include a `test' +statement at the top of the script, like this: + +@smallexample +test -f <program-executed-later-in-script> || exit 0 +@end smallexample + +These scripts should be referenced, when appropriate, by symbolic links +in the @file{/etc/rc?.d} directories, as below. + +When changing runlevels, init looks in the directory @file{/etc/rc<n>.d} +for the scripts it should execute, where <n> is the runlevel that is +being changed to. Please note that the "scripts" in @file{/etc/rc?.d} +are not actually scripts; they are symbolic links, referencing actual +scripts in @file{/etc/init.d}. For simplicity, we refer to them as +"scripts". + +First, the scripts prefixed with a "K" are executed, followed by the +scripts prefixed with an "S". The "K" scripts are responsible for +killing certain services and the "S" scripts for starting certain +services upon @emph{entering} the runlevel. For example, if we are +changing from runlevel 2 to runlevel 3, init will first execute all of +the "K" prefixed scripts it finds in @file{/etc/rc3.d} (to kill +services), and then all of the "S" prefixed scripts it finds in +@file{/etc/rc3.d} (to start services). The "K" scripts will execute the +file it references with an argument of "stop", and the "S" scripts will +execute this file with an argument of "start". + +After the "K" or "S" prefix, there should be a number specified, and +this number should be between 00 and 99. The number determines the +order in which the scripts are run. For example, the "K20" scripts will +be executed before the "K30" scripts. You can use this number to make +sure that a certain service is started before another. For example, on +some machines, the program @file{setserial} may need to properly set an +IRQ before the @file{ppp} program uses a modem to connect to a network. +In this case, the script that runs @file{setserial} should have a lower +number than the script that starts @file{ppp} so that it runs first: + +@smallexample +@file{/etc/rc2.d/S10setserial} +@file{/etc/rc2.d/S20ppp} +@end smallexample + +If it does not matter when or in which order the script is run, use the +number "20". If it does, then you should talk to the maintainer of the +@code{sysvinit} package or post to @code{debian-devel}, and they will +help you choose a number. + +In Debian GNU/Linux, we try to ship our software in as much of a +"default" state as possible. Therefore, unless there is a good reason +for doing differently, we ask that you start and stop the services in +each of the multi-user state runlevels (2, 3, 4, and 5). If a service +needs to be stopped before a file system can be unmounted (an example is +process accounting or quota services), then be sure to stop them in the +halt runlevel (0), the single-user runlevel (1) and the reboot runlevel +(6). + +The system administrator will have the opportunity to customize +runlevels by simply adding, moving, or removing the symbolic links in +@file{/etc/rc?.d}. This is why we default to running everything in the +multi-user state--a reasonable default--and the administrator can easily +customize init to be as complex and sophisticated as he or she wants it +to be beyond this. + +We provide a script, @file{update-rc.d}, to make it easier for package +maintainers to arrange for the proper creation and removal of +@file{/etc/rc?.d} symbolic links from their postinst and postrm scripts. +You should use this script to make changes to @file{/etc/rc?.d} and +@emph{never} include any @file{/etc/rc.?.d} symbolic links in the actual +archive. + +@itemize @bullet +@item +In the postinst script, you need only do the following to setup +@file{/etc/rc?.d}. You should redirect standard output to +@file{/dev/null}, as @file{update-rc.d} produces insignificant output: + +@smallexample +update-rc.d <package> default >/dev/null +@end smallexample + +where <package> is the name of the file as it appears in +@file{/etc/init.d}. It will use the default number of "20", as +mentioned above. If you need to use a different number, you can specify +it after "default": + +@smallexample +update-rc.d <package> default 30 >/dev/null +@end smallexample + +@item +In the postrm script, you need only do the following @emph{if and only +if} it is called with the `purge' argument: + +@smallexample +if [ purge = "$1" ] +then + update-rc.d <package> remove >/dev/null +fi +@end smallexample +@end itemize + +@unnumberedsubsec Important Note: + +@emph{Do not} include the @file{/etc/rc?.d/*} symbolic links in the +archive! @emph{This will cause problems!} You should create them with +update-rc.d, as above. + +@emph{Do not} include the @file{/etc/rc?.d/*} symbolic links in +conffiles! @emph{This will cause problems!} @emph{Do}, however, +include the @file{/etc/init.d} scripts in conffiles. + + +@unnumberedsubsec Example: + +The process accounting package wants to make sure that process +accounting is started at boot time and that it is stopped before the +system is halted, enters the single-user state, or is rebooted (so +that the @file{/var} file system can be properly unmounted). It puts +a script that does this in @file{/etc/init.d}, naming the script +appropriately "acct". This script accepts one of two arguments: +either "start", which starts process accounting, or "stop", which +stops it. To ensure that it does not fail obscurely when the +configuration files remain but the package has been removed, we +include a `test' statement at the top of the script: + +@smallexample +#! /bin/sh +# +# Start process accounting. +. /etc/init.d/functions +test -f /usr/sbin/accton || exit 0 +case "$1" in + start) + echo "Starting process accounting" + /usr/sbin/accton /var/account/pacct + ;; + stop) + echo "Stopping process accounting" + /usr/sbin/accton + ;; + *) + echo "Usage: /etc/init.d/acct @{start|stop@}" + exit 1 +esac +exit 0 +@end smallexample + +You may find a skeletal script from which to base your @file{/etc/init.d} +scripts in @file{/etc/init.d/skeleton}. + +We want to stop then (re)start process accounting when entering a +multi-user state--runlevels 2, 3, 4, and 5--and we want to stop it when +leaving such a state--runlevels 0 (halt), 1 (single) and 6 (reboot). +These are good defaults, and we accomplish this by including the +following in the postinst: + +@smallexample +update-rc.d acct default >/dev/null +@end smallexample + +When the user removes the acct packages with the `--purge' option, we +want to make sure the @file{/etc/rc?.d} symbolic links are properly +removed, so we include the following in the postrm: + +@smallexample +update-rc.d acct remove >/dev/null +@end smallexample + +Otherwise, the @file{/etc/rc?.d} symbolic links will remain on the system +along with @file{/etc/init.d/acct} script. + +@node Maintainer script arguments and how @file{dpkg} does things, Mail processing packages, Configuration of init, Appendix +@unnumberedsec Maintainer script arguments and how @file{dpkg} does things + +This appendix describes exactly how maintainer scripts are called, with +what arguments, in what order, and what @file{dpkg} does in between. + +In all cases version numbers are <version>-<revision>, if the package +has both, or just <version>. @code{upgrade} is used even when the new +version number looks lower than the old. + + +@unnumberedsubsec Summary + +@smallexample +<new preinst> install +<new preinst> install <old-version> +<new preinst> upgrade <old-version> +<old preinst> abort-upgrade <new-version> + +<postinst> configure +<old postinst> abort-upgrade <new version> +<conflictor's postinst> abort-remove in-favour <package> <new version> +<deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> + +<prerm> remove +<old prerm> upgrade <new version> +<new prerm> failed-upgrade <old-vppersion> +<conflictor's prerm> remove in-favour <package> <new version> +<deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> + +<postrm> remove +<postrm> purge +<old postrm> upgrade <new-version> +<new postrm> failed-upgrade <old-version> +<new postrm> abort-install +<new postrm> abort-install <old-version> +<new postrm> abort-upgrade <old-version> +<disappearer's postrm> disappear <overwriter> <new version> +@end smallexample + + +@unnumberedsubsec Details of unpack phase of installation or upgrade + +The procedure on installation/upgrade/overwrite/disappear (ie, when +running @code{dpkg --unpack}, or the unpack stage of @code{dpkg +--install}) is as follows. In each case if an error occurs the actions +in are general run backwards - this means that the maintainer scripts +are run with different arguments in reverse order. These are the `error +unwind' calls listed below. + +@enumerate +@item +@noindent @enumerate a +@item +If a version the package is already +installed, call +@smallexample +<old prerm> upgrade <new version> +@end smallexample +@item +If this gives an error (ie, a non-zero exit status), dpkg will +attempt instead: +@smallexample +<new prerm> failed-upgrade <old-version> +@end smallexample +@noindent error unwind, for both the above cases: +@smallexample +<old postinst> abort-upgrade <new version> +@end smallexample +@end enumerate +@item +If a `conflicting' package is being removed at the same time: +@noindent @enumerate a +@item +If any packages depended on that conflicting package and +@code{--auto-deconfigure} is specified, call, for each such package: +@smallexample +<deconfigured's prerm> deconfigure \ + in-favour <package-being-installed> <version> \ + removing <conflicting-package> <version> +@end smallexample +@noindent error unwind: +@smallexample +<deconfigured's postinst> abort-deconfigure \ + in-favour <package-being-installed-but-failed> <version> + removing <conflicting-package> <version> +@end smallexample +The deconfigured packages are marked as requiring configuration, so +that if --install is used they will be configured again if possible. +@item +To prepare for removal of the conflicting package, call: +@smallexample +<conflictor's prerm> remove in-favour <package> <new version> +@end smallexample +@noindent error unwind: +@smallexample +<conflictor's postinst> abort-remove in-favour <package> <new version> +@end smallexample +@end enumerate +@item +@noindent @enumerate a +@item +If the package is being upgraded, call +@smallexample +<new preinst> upgrade <old-version> +@end smallexample +@item +otherwise, if the package had some configuration files from a previous +version installed (ie, it is in the conffiles-only state): +@smallexample +<new preinst> install <old-version> +@end smallexample +@item +otherwise (ie, the package was completely purged): +@smallexample +<new preinst> install +@end smallexample +@noindent error unwind versions, respectively: +@smallexample +<new postrm> abort-upgrade <old-version> +<new postrm> abort-install <old-version> +<new postrm> abort-install +@end smallexample +@end enumerate +@item +The new package's files are unpacked, overwriting any that may be on the +system already, for example any from the old package or from another +package (backups of the old files are left around, and if anything goes +wrong dpkg will attempt to put them back as part of the error unwind). +@item +@noindent @enumerate a +@item +If the package is being upgraded, call +@smallexample +<old postrm> upgrade <new-version> +@end smallexample +@item +If this fails, dpkg will attempt: +@smallexample +<new postrm> failed-upgrade <old-version> +@end smallexample +@noindent error unwind, for both cases: +@smallexample +<old preinst> abort-upgrade <new-version> +@end smallexample +@end enumerate +This is the point of no return - if dpkg gets this far, it won't back +off past this point if an error occurs. This will leave the package in +a fairly bad state, which will require a successful reinstallation to +clear up, but it's when dpkg starts doing things that are irreversible. +@item +Any files which were in the old version of the package but not in the +new are removed. +@item +The new file list replaces the old. +@item +The new maintainer scripts replace the old. +@item +Any packages all of whose files have been overwritten during the +installation, and which aren't required for dependencies, are considered +to have been removed. For each such package, +@noindent @enumerate a +@item +dpkg calls: +@smallexample +<disappearer's postrm> disappear <overwriter> <new version> +@end smallexample +@item +The package's maintainer scripts are removed. +@item +It is noted in the status database as being in a sane state, namely not +installed (any conffiles it may have are ignored). Note that +disappearing packages do not have their prerm called, because dpkg +doesn't know in advance that the package is going to vanish. +@end enumerate +@item +Any files in the package we're unpacking that are also listed in the +file lists of other packages are removed from those lists. (This will +lobotomise the file list of the `conflicting' package if there is one.) +@item +The backup files made at 4. are deleted. +@item +The new package's status is now sane, and recorded as `unpacked'. Here +is another point of no return - if the conflicting package's removal +fails we do not unwind the rest of the installation; the conflicting +package is left in a half-removed limbo. +@item +If there was a conflicting package we go and do the removal actions, +starting from point 2. of the removal, below. +@end enumerate + + +@unnumberedsubsec Details of configuration + +When we configure a package (this happens with @code{dpkg --install}, or with +@code{--configure}), we first update the conffiles and then call: +@smallexample +<postinst> configure <most-recently-configured-version> +@end smallexample + +No attempt is made to unwind after errors during configuration. + + +@unnumberedsubsec Details of removal and/or configration purging + +@enumerate +@item +@smallexample +<prerm> remove +@end smallexample +@item +The package's files are removed (except conffiles). +@item +@smallexample +<postrm> remove +@end smallexample +@item +All the maintainer scripts except the postrm are removed. + +If we aren't purging the package we stop here. Note that packages which +have no postrm and no conffiles are automatically purged when removed, +as there is no difference except for the dpkg status. + +@item +The conffiles and any backup files (@samp{~}-files, @samp{#*#} files, +@samp{%}-files, .dpkg-@{old,new,tmp@}, etc.) are removed. +@item +@smallexample +<postrm> purge +@end smallexample +@item +The package's file list is removed. +@end enumerate +No attempt is made to unwind after errors during removal. + +@node Mail processing packages, Virtual dependencies, Maintainer script arguments and how @file{dpkg} does things, Appendix +@unnumberedsec Mail processing packages + +Debian packages which process electronic mail (whether mail-user-agents +(MUA) or alternative mail-transport-agents (MTA)) @emph{must} make sure +that they are compatible with the configuration decisions below. +Failure to do this may result in lost mail, broken @code{From:} lines, +and other serious brain damage! + +@itemize @bullet +@item +The mail spool is @file{/var/spool/mail} and the interface to send a +mail message is @file{/usr/sbin/sendmail} (as per the FSSTND). The mail +spool is part of the base and not part of the MTA package. + +@item +Mailboxes are locked using the @file{.lock} lockfile convention, rather +than fcntl, flock or lockf. + +@item +Mailboxes are generally 660 @file{<user>.mail} unless the user has +chosen otherwise. A MUA may remove a mailbox (unless it has nonstandard +permissions) in which case the MTA or another MUA must recreate it if +needed. Mailboxes must be writeable by group mail. + +@item +The mail spool is 2775 mail.mail, and MUA's need to be setgid mail to do +the locking mentioned above (and obviously need to avoid accessing other +users' mailboxes using this privilege). + +@item +@file{/etc/aliases} is the source file for the system mail aliases (e.g. +postmaster, usenet, etc.) - it is the one which the sysadmin and +postinst scripts may edit. + +@item +The convention of writing `forward to <address>' in the mailbox itself +is not supported. Use a @file{.forward} file instead. + +@item +The location for the @file{rmail} program used by UUCP for incoming mail +is @file{/usr/sbin/rmail}, as per the FSSTND. Likewise, @file{rsmtp}, +for receiving batch-SMTP-over-UUCP, is in @file{/usr/sbin/rsmtp} if it +is supported. + +@item +Smail is not using HoneyDanBer UUCP, whose uux apparently accepts -a and +-g options. + +@item +If you need to know what name to use (for example) on outgoing news and +mail messages which are generated locally, you should use the file +@file{/etc/mailname}. It will contain the portion after the username +and @samp{@@} sign for email addresses of users on the machine (followed +by a newline). +@end itemize + +A package should check for the existence of this file. If it exists it +should use it without comment @footnote{An MTA's prompting configuration +script may wish to prompt the user even if it finds this file exists.}. +If it does not exist it should prompt the user for the value and store +it in @file{/etc/mailname} as well as using it in the package's +configuration. The prompt should make it clear that the name will not +just be used by that package. E.g., in the same situation the INN +package says: + +@smallexample +Please enter the `mail name' of your system. This is the hostname +portion of the address to be shown on outgoing news and mail messages. +The default is `$syshostname', your system's host name. +Mail name [`$syshostname']: +@end smallexample +($syshostname is the output of `hostname --fqdn'). + +@node Virtual dependencies, , Mail processing packages, Appendix +@comment node-name, next, previous, up +@unnumberedsec Virtual dependencies + +Virtual packages are in the same namespace as real packages, and may +have the same name. The meaning of a virtual package in a +dependency/conflicts list is exactly that of listing all the real +packages which state that they are an instantiation of that virtual +package. + +This is done with a new Provides field in the control file, with a +syntax much like the Conflicts field. + +The idea is that we can have something like: +@smallexample +Package: elm +Depends: mta + +Package: smail +Provides: mta +Conflicts: mta + +Package: sendmail +Provides: mta +Conflicts: mta +@end smallexample +@noindent The result is equivalent to elm having said +@smallexample +Package: elm +Depends: smail | sendmail +@end smallexample + +(There'll be a special case to say that a package may conflict with a +virtual package which it provides - clearly ...) + +If there are both a real and a virtual package of the same name then +the dependency may be satisfied (or the conflict caused) by either the +real package or any of the virtual packages which provide it. This is +so that, for example, supposing we have +@smallexample +Package: lout +Optional: ghostview +@end smallexample +(this is a fictional example - the Lout package should not mention +ghostview), and someone else comes up with a nice PostScript +previewer, then they can just say +@smallexample +Package: marvelpostview +Provides: ghostview +@end smallexample +and all will work in the interim (until, say, the Lout maintainer +changes things). + +If a dependency or a conflict has a version number attached then only +real packages will be considered to see whether the relationship is +satisfied (or prohibited, for a conflict) - it is assumed that a real +package which provides virtual package is not of the `right' version. +If there is demand it can be arranged that a package which provides a +virtual package may mention a version number, though this is unlikely to +be helpful: +@smallexample +Provides: mta (2.0) +@end smallexample + +If you want to specify which of a set of real packages should be the +default to satisfy a particular dependency on a virtual package, you can +simply list the real package as alternative before the virtual one: +@smallexample +Package: xbaseR6 +Recommended: xsvga | x-server +Provides: x-base, xr6shlib + +Package: xsvga +Recommended: x-base +Provides: x-server + +Package: x8514 +Recommended: x-base +Provides: x-server +@end smallexample + +Virtual package names should generally not be used in the names of +@file{/etc/init.d} scripts, configuration files, logfiles, and so on, so +that several programs providing the same virtual package name can be +installed. + +@bye |