Guidelines for Creating and Maintaining Debian Packages Ian Jackson based on the source package guidelines by Ian Murdock Revision: 21st September 1994 =============================================================================== This document describes the steps that must be taken in the preparation of a Debian package. All submissions to be included in the Debian distribution and all packages wishing to be considered for Debian `contrib' availability _must_ follow the guidelines and standards listed in this document. =========================================================================== Important consideration - Copyright ----------------------------------- There is one _very_ important consideration to make before proceeding: do you, the packager, understand the copyright of the package that you wish to submit? PLEASE study the copyright of your submission VERY CAREFULLY and UNDERSTAND IT before proceeding! Ensure that distribution is possible in binary and source form without restrictions on modification, redistribution and for-profit use of the package. All submissions to be included in the distribution proper _must_ be free of such restrictions or they cannot be included. Submissions for `contrib' availability, however, may be allowed to deviate from this requirement; we want the maximum amount of software to be available in `dpkg' format for Debian users, so in certain circumstances it will be allowable to have ``shareware'' and other non-free software optionally available as `contrib' packages. It is important to note that these packages will be _optional_ additions to the Debian system and that the Debian system itself will remain completely free of such packages. When in doubt, send mail to me (see above for address). Be prepared to provide me with the copyright. Software covered by the GPL, public domain software and BSD-like copyrights are safe; be wary of the phrases ``commercial use prohibited'' and ``distribution restricted''. EVERY package submission _must_ be accompanied by verbatim copy of its copyright (with the exceptions of public domain packages and those covered by the UCB BSD licence or the GNU GPL or LGPL; in these cases simply indicate which is appropriate). See below. =========================================================================== Requirements for the content of the package ------------------------------------------- The following requirements apply to the source and binary packages equally; when files have been installed they should conform to the requirements contained here. * The location of installed files _must_ comply fully with the Linux Filesystem Standard. The latest version of this document can be found alongside this Debian source package guidelines. Specific questions about following the standard can be addressed to Daniel Quinlan . * All directories should be mode 755, or (for group-writeability) 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, then it should be owned by the group that needs write access to it. Use common sense in assigning permissions and ownerships to directories, and make sure that what is done is secure if it is ``non-standard''. * In general, normal binaries should be mode 755 and owned by root.root. If there is a good reason to use a different mode or ownership, then feel free to do so, but do try to be as consistent as possible with the rest of the system. * setuid/setgid binaries should normally be mode 4755/2755 and owned by the appropriate user/group. * Library files should generally be installed as mode 644 and owner root.root; however, if the package requires different permissions or ownerships to function correctly, then they should obviously be used instead. * Manual pages should be mode 644 and owned by root.root. The nroff source must be installed. Do not install a pre-formatted cat page. Only use manual sections 1 to 9 -- see the FSSTND for more details. * Info documents should be mode 644, owned by root.root, and `gzipped' when installed. The package must call `install-info' to ensure that its Info document(s) are properly listed in the `dir' file (for binary packages this should be done by the postinst script). For example, install-info --quiet /usr/info/foobar.info Their entries should be deinstalled by the prerm script, for example, install-info --quiet --remove /usr/info/foobar.info If install-info cannot find a description entry in the Info file you will have to supply one; see the manpage for install-info(8) for details. * If a package contains any shared libraries you will have to invoke `ldconfig' in both the postinstall and prerm scripts, to ensure that the library links are updated correctly. See ldconfig(8) for details. * Any other documentation that comes with the package should be installed at the discretion of the package maintainer. Text documentation should be mode 644, owned by root.root, installed in /usr/doc and `gzipped' unless it is very small. If a subdirectory of /usr/doc is warranted, then please feel free to create one. Please do not install PostScript, DVI or large textual documentation to /usr/doc; however, please do upload such documentation as a separate package so that it can be made available via FTP with the distribution in a `doc' directory. If a user has the need for the documentation they can easily get it from there. Create a file named /usr/doc/copyright/ 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 licence (BSD copyright), please say so instead of including a copy of the licence. The files GPL, LGPL and BSD will be available in the /usr/doc/copyright directory for you to refer to. /usr/doc/copyright/ should not normally be compressed. ALL the authorship and copyright information from the original source package must be included in the /usr/doc/copyright/ file. * Please check with the base system maintainer (Ian Murdock) before using users or groups other than `root' and others specified in this document. * Any example files (for example, sample configuration files) should be placed in /usr/doc/examples. If the file is normally a hidden file, such as `.emacs', then please call it `dot.emacs' to avoid confusion. Again, feel free to create a subdirectory. * All symbolic links should be relative, not absolute. Absolute links, in general, cause problems when a filesystem is not mounted where it ``normally'' resides (for example, when mounted via NFS). In certain cases, however, relative links may also cause similar problems (for example, if /usr is mounted on /foo/bar, and /foo/bar/spool is a link to ../spool it will not find it); in this case, feel free to use absolute links, but they should be used only when necessary. I have generally made links into /etc and /var absolute and all other links relative. There may be other cases in which absolute links are necessary. Therefore, in the Makefile, do not do (even though it is easier): install: all [...] ln -fs /usr/bin/gcc /usr/bin/cc [...] Instead, do: ln -fs gcc /usr/bin/cc or ( cd /usr/bin ; ln -fs gcc cc ) Please do not create hard links in the manual page directories; use symbolic links or files that `.so' (roff for `source') others instead. * All command scripts should have a #! line naming the shell to be used to interpret them. In the case of Perl scripts this should be #!/usr/bin/perl or sometimes #!/bin/perl, as follows: if the script is a critical one that may be called when the /usr partition is unmounted or broken it should use /bin/perl. Otherwise (especially if the script is not specifically targetted at Debian) it should use Perl's standard location, /usr/bin/perl. * Generally the following compilation parameters should be used: CC = gcc CFLAGS = -O2 LDFLAGS = -s (and -N, if appropriate; see below) All installed binaries should be stripped, hence -s. `-N' should only be used on binaries that are very small (less than 8K with the `-N' option, roughly) and are not likely to have multiple instances in memory. Do not use `-N' on daemons, no matter how small they are. It is up to the package maintainer to decide what compilation options are best for the package. Certain binaries (such as computational- intensive programs) may function better with certain flags; 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. =========================================================================== Creating the source package --------------------------- * The source package should contain a file `debian.rules', containing at least the following targets: build clean binary They are to be invoked in the package top level directory. + The `build' target should do the noninteractive configuration and compilation of the package. If a package has an interactive pre-build configuration routine the source package should be built *after* this has taken place. + The `binary' target of debian.rules should be all that is necessary for the user to build the binary package that is shipped as part of the Debian system. The binary package should be placed in a *.deb file in the parent of the package's top level directory, and created using dpkg. See the below for details on how to construct binary packages. + The `clean' target should undo the effects of `build' and/or `binary', except that it should leave alone any ../-.deb file created by a run of `binary'. In the case of `binary' you must ensure that all binaries are installed in the proper locations and with the correct permissions and ownerships. Ensure that any appropriate documentation is installed along with any appropriate examples and that man pages and Info documents are installed. debian.rules should start with #!/usr/bin/make -f and be executable. It is a good idea to arrange for it not to fail obscurely when invoked in the wrong directory. + Other targets may exist in debian.rules. We recommend using `source' and `diff' to generate the Debianised source tarfile and the Debianisation patch file respectively (conventionally in ../foo-.tar.gz and ../foo-.diff.gz respectively). The `install' target, for installing into a running system direct from the Debianised source tree, is now no longer required. * If you need to edit a package's top-level Makefile: edit the *.in files in packages where `configure' scripts are used and generate the Makefile, etc. from them rather than editing the generated files directly. This allows the user to reconfigure the package if necessary. Do _not_ simply configure the package and edit the generated Makefile! This makes it impossible for someone else to reconfigure the package. * Please document your changes to the source package so that future package maintainers know what has been changed. Record your changes for Debian in a file called debian.README in the source package's top-level directory, and include relevant information such as your name, electronic mail address, date, etc. If changes to the source code are made, then please use a `define'. If it is a change required to compile or function under Linux in general, then use `LINUX'; if it is a cosmetic or functional change, then use `DEBIAN'. * Archive the source package using `tar'. Use `gzip -9' to compress it. Source packages should be named in the form: -.tar.gz Example: `fileutils-3.9-3.tar.gz' NB, here is the full Debian version number, in the form - (see below), but the tarfile should unpack into a directory named - (again, see the section below on version numbering). NOTE: Do not use the `z' option to `tar'! This will not result in optimal compression! Instead, do this: # tar cvf foo-1.2.3-4.tar foo-1.2.3 # gzip -9 foo-1.2.3-4.tar * Make a context diff against the original package: # diff --context --recursive -P foo-1.0.orig/ foo-1.0/ Context diffs should compressed with `gzip -9' and be named in the form: -.diff.gz Example: `fileutils-3.9-3.diff.gz' You may find the above two things easier to automate with the help of targets in debian.rules. If so, the targets to use are `source' and `diff' for the debianised source tarfile and the debianisation patch, respectively. Note also that the package and patch filenames do NOT need to fit in MSDOS 8+3. They will be made available under an alternative 8+3 name in the archive by the archive maintainer, using a symlink. =========================================================================== Creating the binary package --------------------------- The `binary' target of the source package's debian.rules file should do the following things: * Create an empty subdirectory of the source package's directory (deleting it first if necessary), and install the files belonging to this package in that directory. For example, the subdirectory might be called `debian-tmp' and would probably contain directories debian-tmp/usr/bin, debian-tmp/usr/lib, etc. * Ensure that all the files under debian-tmp have the correct permissions and ownerships. * Create a subdirectory of debian-tmp called DEBIAN. This directory contains the package control information, including at the very least the master information file named `control'. Please see below for details of the syntax and semantics of the files required and allowed here. * Run dpkg to create the binary package, using something like dpkg --build debian-tmp This will create a file debian-tmp.deb, from the debian-tmp directory. Rename this file to ../-.deb. When the `binary' target has done all this the -.deb file in the containing directory is the binary distribution. This file may be uploaded to FTP sites, etc. * If a single source package corresponds to several binary packages there should usually be a debian.rules file with a single `binary' target to generate all the binary packages involved, all as *.deb files in the parent directory of that containing the sources. In this case you should choose binary package names which are meant to make clear the close relationship between the various binary package and which source package the binary packages came from (e.g., texidoc, texinfo). Place the appropriate binary package name in the Name field of the control file (not the source package name); you should consider whether the other binary packages that come from the same source tree should be mentioned in the Depends, Recommended or Optional fields. You should retain the source package version numbering in the VERSION field - ie, the version number should be the same for the Debianised source tree and all the binary packages generated from it. See below for details of version numbers. Meanings of the binary package control information files -------------------------------------------------------- Each binary package contains, as well as the files which make up the package itself, a set of text files that control the way the packaging tools handle the package. When creating the package using the tools these files are placed in a DEBIAN directory as described above. See the packaging tools spec for details of how these files are stored in the .deb package file. The control information files are: control Master package control information file conffiles List of package configuration files preinst Package pre-installation script postinst Package post-installation script prerm Package pre-removal script postrm Package post-removal script Of these, only `control' is required. The various installation scripts, and the configuration files list, will only be used if they are present. * Master control file format: The `control' file contains a number of fields. Each field begins with a tag, such as `PACKAGE' or `VERSION' (case insensitive), followed by a colon, and the body of the field. Fields are delimited only by field tags. In other words, field text may be multiple lines in length, but the installation tools will generally join lines when processing the body of the field. The required fields in the control file are the following: PACKAGE: VERSION: PACKAGE_REVISION: MAINTAINER: DESCRIPTION: There is but one restriction on the format of control file fields: The value of `PACKAGE' will be used to generate filenames by the installation tools, and therefore should be a valid filename prefix (i.e., no embedded slashes), and not contain any whitespace. The MAINTAINER should be in the format Joe Bloggs . The VERSION and PACKAGE_REVISION fields should be the version number of the package. For most packages, which are not written specifically for Debian, this should be in the form VERSION: PACKAGE_REVISION: where is the original portable package's version number in whatever form the program's author uses, and indicates which `debianisation' this is (this should usually be a plain number, or perhaps two numbers separated by a full stop). The optional fields in the control file are the following: DEPENDS: RECOMMENDED: OPTIONAL: CONFLICTS: See below for details of the syntax and semantics of these fields. An example of a `control' file would be: PACKAGE: emacs VERSION: 19.22 PACKAGE_REVISION: 2 MAINTAINER: Daniel Quinlan DESCRIPTION: The extensible, customizable, self-documenting, real-time display editor DEPENDS: emcsmisc, emcselc1, emcselc2 RECOMMENDED: emcselz1, emcselz2, emcsinfo OPTIONAL: emcsetc CONFLICTS: emacs_nox In this case, the `emacs' package will contain the binary with X support, and `emacs_nox' contains the binary without X support. The control file for `emacs_nox' would contain a `CONFLICTS: emacs' line accordingly. * Configuration file list format: The contents of `conffiles' is simply a list of files in the package. When installing the package the installation tools frontend will update these using a ``foolproof'' upgrade mechanism. This will ensure that package-specific configuration files are not overwritten when a package is upgraded, unless the user wishes the installation tools to do so. Typically, files listed in conffiles are package-specific configuration files, which (according to the Linux Filesystem Standard) are stored in /etc. For example, the `sendmail' package may contain the file `/etc/sendmail.cf', which we do not wish to overwrite automatically when the user upgrades the sendmail package. Only those files listed in DEBIAN/conffiles will be updated intelligently when a package is upgraded; all other files in the package will be overwritten by the upgrade process. The exact procedure used for configuration file updates is covered in the binary package tools specification. This information will probably only be of interest to the maintainers of packages with sophisticated configuration requirements, including those involving prompting the user for information. Maintainers of packages whose configuration files will be functional as shipped and will probably need little or no local editing should simply list the configuration files in the `conffiles' control file and need read no further. conffiles should almost certainly list all the files your package has in /etc. There may also be other files somewhere that the user is expected to edit, which should also be included. Note, though, that the FSSTND specifies that configuration files must be in /etc. For example, the TCP/IP package might use a conffiles which contains /etc/hosts /etc/networks /etc/host.conf /etc/resolv.conf and so on. * Installation script format: The files `preinst', `postinst', `prerm', and `postrm' are optional (bash or perl) scripts. As the names imply, if these scripts exist they will be executed before installing the package, after installation, before package removal, and after removal, respectively. 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. These scripts should avoid producing output which it is unecessary for the user to see, and should rely on the frontend to stave off boredom on the part of a user installing many packages. This means, amongst other things, using the --quiet option on install-info. They should return a zero exit status for success, or a nonzero one for failure. Note that if a script is a #!/bin/sh script it should probably start with `set -e', to avoid continuing after errors - see bash(1) for details. If these scripts exist they should be left in the DEBIAN directory with execute permission enabled, and should contain an appropriate #! line, such as #!/bin/bash for a bash script or #!/bin/perl for a Perl script (see above). * The meaning of DEPENDS, RECOMMENDED, OPTIONAL and CONFLICTS The DEPENDS field lists packages that are required for this package to provide a significant amount of functionality. The package maintenance software will not allow a package to be installed without also installing packages listed in its DEPENDS field, and will run the postinst scripts of packages listed in DEPENDS fields before those of the packages which depend on them, and run the prerm scripts before. The RECOMMENDED field lists packages that would be found together with this one in all but unusual installations. The package maintenance software will warn the user if they install a package without those listed in its RECOMMENDED field. The syntax of DEPENDS and RECOMMENDED is a list of groups of alternative packages. Each group is a list of packages separated by vertical bar (or `pipe') symbols, `|'. The groups are separated by commas. Each package is a package name optionally followed by a version number specification in parentheses. A version number may start with a `>', in which case any later version will match, and may specify or omit the Debian packaging revision (separated by a hyphen). Commas are to be read as `AND', and pipes as `OR', with pipes binding more tightly. The OPTIONAL 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 OPTIONAL related packages, but may use the information in the OPTIONAL field to assist the user during package selection. The CONFLICTS field lists packages that conflict with this one, for example by containing files with the same names (an example would be Smail vs. Sendmail). The package maintenance software will not allow conflicting packages to be installed. Two conflicting packages should each include a CONFLICTS line mentioning the other. The syntax of OPTIONAL and CONFLICTS is a list of package names, separated by commas (and optional whitespace). In the CONFLICTS field, the comma should be read as `OR'.