From a3a649ad7268e5709cb3a84cd37c7adeba71cf35 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:31:52 +0000 Subject: [PATCH] Manually added patch 125 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-127 --- DebianDoc_SGML/Format/LaTeX.pm | 10 + debian/changelog | 7 +- debian/control | 2 + perl-policy.sgml | 5 +- policy.sgml | 2812 +++++++++++++++++++++++++++++++- 5 files changed, 2804 insertions(+), 32 deletions(-) diff --git a/DebianDoc_SGML/Format/LaTeX.pm b/DebianDoc_SGML/Format/LaTeX.pm index 51c4748..24e34e3 100644 --- a/DebianDoc_SGML/Format/LaTeX.pm +++ b/DebianDoc_SGML/Format/LaTeX.pm @@ -468,6 +468,8 @@ sub _sdata output( $DebianDoc_SGML::Format::Driver::sdata_mapping{ $_[0] } ) if defined( $DebianDoc_SGML::Format::Driver::sdata_mapping{ $_[0] } ); } + +my $in_quote=0; sub _sani { ( $_ ) = @_; @@ -498,7 +500,15 @@ sub _sani # s/----/---/g; # quotes + if ($in_quote && /\"/) { + s/\"/\'\'/; + $in_quote=0; + } s/\"(.*?)\"/\`\`$1\'\'/g; + if (/\"/) { # quotes left + s/\"/\`\`/; + $in_quote=1; + } # dots should be ellipsis "..." s/\.\.\./\\dots /g; diff --git a/debian/changelog b/debian/changelog index d7eb454..180c169 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,4 +1,4 @@ -debian-policy (3.5.4.1) unstable; urgency=low +debian-policy (3.5.5.0) unstable; urgency=low * Fixed up incorrect entries in the changelog (there was an erroneous 3.5.0.1 revision which never happened; it has now been correctly @@ -31,8 +31,11 @@ debian-policy (3.5.4.1) unstable; urgency=low * Correction to meaning of Standards-Version closes: Bug#97072 * Split section 12.8 (X Window System) into subsections for readability * Plug-ins != shared libraries (at last) closes: Bug#66023 + * Add packaging manual remnants to policy document as appendices, and + mention this in control file closes: Bug#95906 + * Clarification in Perl policy closes: Bug#98712 - -- + -- Julian Gilbey Fri, 1 Jun 2001 10:37:52 +0100 debian-policy (3.5.4.0) unstable; urgency=low diff --git a/debian/control b/debian/control index e657f4e..c6aaa66 100644 --- a/debian/control +++ b/debian/control @@ -18,3 +18,5 @@ Description: Debian Policy Manual and related documents - Authoritative list of virtual package names - Paper about libc6 migration - Policy checklist for upgrading your packages + It also replaces the old Packaging Manual; most of the still-relevant + content is now included as appendices to the Policy Manual. diff --git a/perl-policy.sgml b/perl-policy.sgml index edf8e4f..8edf3d7 100644 --- a/perl-policy.sgml +++ b/perl-policy.sgml @@ -12,7 +12,7 @@ Brendan O'Dea bod@debian.org - version 1.19 + version 1.20 This document describes the packaging of Perl within the Debian @@ -342,7 +342,8 @@ $(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr a minimum version of the perl package used to build the module, and must additionally depend on the expansion of - perlapi-$Config{version}. + perlapi-$Config{version} using + the Config module.

diff --git a/policy.sgml b/policy.sgml index 0a2a161..39de67d 100644 --- a/policy.sgml +++ b/policy.sgml @@ -43,13 +43,13 @@ This manual describes the policy requirements for the Debian - GNU/Linux distribution. This includes the structure and - contents of the Debian archive and several design issues of the - operating system, as well as technical requirements that each - package must satisfy to be included in the distribution. The - policy package itself is maintained by a group of maintainers - that have no editorial powers. At the moment, the list of - maintainers is: + GNU/Linux distribution. This includes the structure and + contents of the Debian archive and several design issues of + the operating system, as well as technical requirements that + each package must satisfy to be included in the distribution. + The policy package itself is maintained by a group of + maintainers that have no editorial powers. The current list + of maintainers is:

Julian Gilbey jdg@debian.org

@@ -1083,7 +1083,7 @@ /debian/doc/package-developer/debconf_specification.txt.gz or on your local mirror.

- 2.5% of Debian packages [see ] currently use debconf to prompt the user at @@ -4180,16 +4180,7 @@ libbar 1 bar1 (>= 1.0-1) removed by the postinst and prerm maintainer scripts and not be included in the .deb archive. These scripts must not fail if - either of these operations fail. -

- In the future, it may be possible to tell - dpkg not to unpack files matching certain - patterns, so that the directories can be included in - the .deb packages and system administrators - who do not wish these directories in - /usr/local do not need to have them.) -

- + either of these operations fail.

@@ -5696,9 +5687,9 @@ strip --strip-unneeded your-lib already exists.

- The Debian base distribution provides the - tempfile and mktemp utilities - for use by scripts for this purpose.

+ The Debian base system provides the tempfile + and mktemp utilities for use by scripts for + this purpose.

@@ -5925,7 +5916,7 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq /usr/share/doc/package/examples if they are examples, and should be perfectly ordinary dpkg-handled files (not - conffiles). + configuration files).

@@ -5943,7 +5934,9 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq conffile must be tagged as conflicting with each other. (This is an instance of the general rule about not sharing files. Note that neither alternatives - nor diversions are likely to be appropriate in this case.) + nor diversions are likely to be appropriate in this case; + in particular, dpkg does not handle diverted + conffiles well.)

@@ -6309,10 +6302,8 @@ done

If a program needs to specify an architecture specification - string in some place, the following format should be used: - -arch-os - + string in some place, the following format should be + used: arch-os

The following architectures and operating systems are currently recognised by dpkg-archictecture. @@ -6327,7 +6318,7 @@ done openbsd. Use of gnu in this string is reserved for the GNU/Hurd operating system.

- + .

@@ -7565,5 +7556,2770 @@ fi changelog.Debian.gz.

 + + + Introduction and scope of these appendices + +

+ These appendices are taken essentially verbatim from the + now-deprecated Packaging Manual, version 3.2.1.0. They are + the chapters which are likely to be of use to package + maintainers and which have not already been included in the + policy document itself. They have not yet been checked to + ensure that they are compatible with the contents of policy, + and if there are any contradictions, the version in the main + policy document takes precedence. The remaining chapters of + the old Packaging Manual have also not been read in detail to + ensure that there are not parts which have been left out. + Both of these will be done in due course. +

+ +

+ dpkg is a suite of programs for creating binary + package files and installing and removing them on Unix + systems. +

+ dpkg is targetted primarily at Debian + GNU/Linux, but may work on or be ported to other + systems. +

+ +

+ +

+ The binary packages are designed for the management of + installed executable programs (usually compiled binaries) and + their associated data, though source code examples and + documentation are provided as part of some packages.

+ +

+ This manual describes the technical aspects of creating Debian + binary packages (.deb files). It documents the + behaviour of the package management programs + dpkg, dselect et al. and the way + they interact with packages.

+ +

+ It also documents the interaction between + dselect's core and the access method scripts it + uses to actually install the selected packages, and describes + how to create a new access method.

+ +

+ This manual does not go into detail about the options and + usage of the package building and installation tools. It + should therefore be read in conjuction with those programs' + manpages. +

+ +

+ The utility programs which are provided with dpkg + for managing various system configuration and similar issues, + such as update-rc.d and + install-info, are not described in detail here - + please see their manpages. +

+ +

+ It does not describe the policy requirements imposed + on Debian packages, such as the permissions on files and + directories, documentation requirements, upload procedure, and + so on. You should see the Debian packaging policy manual for + these details. (Many of them will probably turn out to be + helpful even if you don't plan to upload your package and make + it available as part of the distribution.) +

+ +

+ It is assumed that the reader is reasonably familiar with the + dpkg System Administrators' manual. + Unfortunately this manual does not yet exist. +

+ +

+ The Debian version of the FSF's GNU hello program is provided + as an example for people wishing to create Debian + packages. The Debian debmake package is + recommended as a very helpful tool in creating and maintaining + Debian packages. However, while the tools and examples are + helpful, they do not replace the need to read and follow the + Policy and Programmer's Manual.

+ + + Binary packages (from old + Packaging Manual) + + +

+ The binary package has two main sections. The first part + consists of various control information files and scripts used + by dpkg when installing and removing. See . +

+ +

+ The second part is an archive containing the files and + directories to be installed. +

+ +

+ In the future binary packages may also contain other + components, such as checksums and digital signatures. The + format for the archive is described in full in the + deb(5) manpage. +

+ + + Creating package files - + dpkg-deb + + +

+ All manipulation of binary package files is done by + dpkg-deb; it's the only program that has + knowledge of the format. (dpkg-deb may be + invoked by calling dpkg, as dpkg + will spot that the options requested are appropriate to + dpkg-deb and invoke that instead with the same + arguments.) +

+ +

+ In order to create a binary package you must make a + directory tree which contains all the files and directories + you want to have in the filesystem data part of the package. + In Debian-format source packages this directory is usually + debian/tmp, relative to the top of the package's + source tree. +

+ +

+ They should have the locations (relative to the root of the + directory tree you're constructing) ownerships and + permissions which you want them to have on the system when + they are installed. +

+ +

+ With current versions of dpkg the uid/username + and gid/groupname mappings for the users and groups being + used should be the same on the system where the package is + built and the one where it is installed. +

+ +

+ You need to add one special directory to the root of the + miniature filesystem tree you're creating: + DEBIAN. It should contain the control + information files, notably the binary package control file + (see ). +

+ +

+ The DEBIAN directory will not appear in the + filesystem archive of the package, and so won't be installed + by dpkg when the package is installed. +

+ +

+ When you've prepared the package, you should invoke: + + dpkg --build directory + +

+ +

+ This will build the package in + directory.deb. (dpkg knows + that --build is a dpkg-deb option, so + it invokes dpkg-deb with the same arguments to + build the package.) +

+ +

+ See the manpage for details of how + to examine the contents of this newly-created file. You may find the + output of following commands enlightening: + + dpkg-deb --info filename.deb + dpkg-deb --contents filename.deb + dpkg --contents filename.deb + + To view the copyright file for a package you could use this command: + + dpkg --fsys-tarfile filename.deb | tar xof usr/doc/\*copyright | less + +

+ + + + + Package control information files + + +

+ The control information portion of a binary package is a + collection of files with names known to dpkg. + It will treat the contents of these files specially - some + of them contain information used by dpkg when + installing or removing the package; others are scripts which + the package maintainer wants dpkg to run. +

+ +

+ It is possible to put other files in the package control + area, but this is not generally a good idea (though they + will largely be ignored). +

+ +

+ Here is a brief list of the control info files supported by + dpkg and a summary of what they're used for. +

+ +

+ + control + + +

+ This is the key description file used by + dpkg. It specifies the package's name + and version, gives its description for the user, + states its relationships with other packages, and so + forth. See . +

+ +

+ It is usually generated automatically from information + in the source package by the + dpkg-gencontrol program, and with + assistance from dpkg-shlibdeps. See .

+ + + postinst, preinst, postrm, + prerm + + + +

+ These are exectuable files (usually scripts) which + dpkg runs during installation, upgrade + and removal of packages. They allow the package to + deal with matters which are particular to that package + or require more complicated processing than that + provided by dpkg. Details of when and + how they are called are in . +

+ +

+ It is very important to make these scripts + idempotent. + +

+ That means that if it runs successfully or fails + and then you call it again it doesn't bomb out, + but just ensures that everything is the way it + ought to be. +

+ This is so that if an error occurs, the + user interrupts dpkg or some other + unforeseen circumstance happens you don't leave the + user with a badly-broken package. +

+ +

+ The maintainer scripts are guaranteed to run with a + controlling terminal and can interact with the user. + If they need to prompt for passwords, do full-screen + interaction or something similar you should do these + things to and from /dev/tty, since + dpkg will at some point redirect scripts' + standard input and output so that it can log the + installation process. Likewise, because these scripts + may be executed with standard output redirected into a + pipe for logging purposes, Perl scripts should set + unbuffered output by setting $|=1 so that the + output is printed immediately rather than being + buffered. +

+ +

+ Each script should return a zero exit status for + success, or a nonzero one for failure.

+ + + conffiles + + + +

+ This file contains a list of configuration files which + are to be handled automatically by dpkg + (see ). Note that not necessarily + every configuration file should be listed here.

+ + + shlibs + + + +

+ This file contains a list of the shared libraries + supplied by the package, with dependency details for + each. This is used by dpkg-shlibdeps + when it determines what dependencies are required in a + package control file. The shlibs file format + is described on . +

+ + +

+ + + + The main control information file: control + +

+ The most important control information file used by + dpkg when it installs a package is + control. It contains all the package's `vital + statistics'. +

+ +

+ The binary package control files of packages built from + Debian sources are made by a special tool, + dpkg-gencontrol, which reads + debian/control and debian/changelog to + find the information it needs. See for + more details. +

+ +

+ The fields in binary package control files are: + + +

Package (mandatory)

+ + +

Version (mandatory)

+ +

Architecture + (mandatory) + +

+ This field should appear in all packages, though + dpkg doesn't require it yet so that + old packages can still be installed. +

+ +

+ + +

Depends, + Provides et al.

+ + +

Essential

+ + +

Maintainer

+ + +

Section, + Priority

+ + +

Source

+ + +

Description

+ + +

+ Installed-Size +

+ + + +

+ A description of the syntax of control files and the purpose + of these fields is available in . +

+ + + + Time Stamps +

+ Maintainers are encouraged to preserve the modification + times of the upstream source files in a package, as far as + is reasonably possible. + +

+ The rationale is that there is some information conveyed + by knowing the age of the file, for example, you could + recognize that some documentation is very old by looking + at the modification time, so it would be nice if the + modification time of the upstream source would be + preserved. +

+ +

+ + + + + Source packages (from old Packaging Manual) + +

+ The Debian binary packages in the distribution are generated + from Debian sources, which are in a special format to assist + the easy and automatic building of binaries. +

+ +

+ There was a previous version of the Debian source format, + which is now being phased out. Instructions for converting an + old-style package are given in the Debian policy manual. +

+ + + Tools for processing source packages + +

+ Various tools are provided for manipulating source packages; + they pack and unpack sources and help build of binary + packages and help manage the distribution of new versions. +

+ +

+ They are introduced and typical uses described here; see + for full + documentation about their arguments and operation. +

+ +

+ For examples of how to construct a Debian source package, + and how to use those utilities that are used by Debian + source packages, please see the hello example + package. +

+ + + + dpkg-source - packs and unpacks Debian source + packages + + +

+ This program is frequently used by hand, and is also + called from package-independent automated building scripts + such as dpkg-buildpackage. +

+ +

+ To unpack a package it is typically invoked with + + dpkg-source -x .../path/to/filename.dsc + +

+ +

+ with the filename.tar.gz and + filename.diff.gz (if applicable) in + the same directory. It unpacks into + package-version, and if + applicable + package-version.orig, in + the current directory. +

+ +

+ To create a packed source archive it is typically invoked: + + dpkg-source -b package-version + +

+ +

+ This will create the .dsc, .tar.gz and + .diff.gz (if appropriate) in the current + directory. dpkg-source does not clean the + source tree first - this must be done separately if it is + required. +

+ +

+ See also .

+ + + + + + dpkg-buildpackage - overall package-building + control script + + +

+ dpkg-buildpackage is a script which invokes + dpkg-source, the debian/rules + targets clean, build and + binary, dpkg-genchanges and + pgp to build a signed source and binary + package upload. +

+ +

+ It is usually invoked by hand from the top level of the + built or unbuilt source directory. It may be invoked with + no arguments; useful arguments include: + + -uc, -us + +

+ Do not PGP-sign the .changes file or the + source package .dsc file, respectively.

+ + -ppgp-command + +

+ Invoke pgp-command instead of finding + pgp on the PATH. + pgp-command must behave just like + pgp.

+ + -rroot-command + +

+ When root privilege is required, invoke the command + root-command. root-command + should invoke its first argument as a command, from + the PATH if necessary, and pass its + second and subsequent arguments to the command it + calls. If no root-command is supplied + then dpkg-buildpackage will take no + special action to gain root privilege, so that for + most packages it will have to be invoked as root to + start with.

+ + -b, -B + +

+ Two types of binary-only build and upload - see + . +

+ + +

+ + + + + dpkg-gencontrol - generates binary package + control files + + +

+ This program is usually called from debian/rules + (see ) in the top level of the source + tree. +

+ +

+ This is usually done just before the files and directories in the + temporary directory tree where the package is being built have their + permissions and ownerships set and the package is constructed using + dpkg-deb/ + +

+ This is so that the control file which is produced has + the right permissions +

+ . +

+ +

+ dpkg-gencontrol must be called after all the + files which are to go into the package have been placed in + the temporary build directory, so that its calculation of + the installed size of a package is correct. +

+ +

+ It is also necessary for dpkg-gencontrol to + be run after dpkg-shlibdeps so that the + variable substitutions created by + dpkg-shlibdeps in debian/substvars + are available. +

+ +

+ For a package which generates only one binary package, and + which builds it in debian/tmp relative to the top + of the source package, it is usually sufficient to call + dpkg-gencontrol. +

+ +

+ Sources which build several binaries will typically need + something like: + + dpkg-gencontrol -Pdebian/tmp-pkg -ppackage + The -P tells + dpkg-gencontrol that the package is being + built in a non-default directory, and the -p + tells it which package's control file should be generated. +

+ +

+ dpkg-gencontrol also adds information to the + list of files in debian/files, for the benefit of + (for example) a future invocation of + dpkg-genchanges.

+ + + + + dpkg-shlibdeps - calculates shared library + dependencies + + +

+ This program is usually called from debian/rules + just before dpkg-gencontrol (see ), in the top level of the source tree. +

+ +

+ Its arguments are executables. + +

+ In a forthcoming dpkg version, + dpkg-shlibdeps would be required to be + called on shared libraries as well. +

+

+ They may be specified either in the locations in the + source tree where they are created or in the locations + in the temporary build tree where they are installed + prior to binary package creation. +

+ for which shared library dependencies should + be included in the binary package's control file. +

+ +

+ If some of the found shared libraries should only + warrant a Recommends or Suggests, or if + some warrant a Pre-Depends, this can be achieved + by using the -ddependency-field option + before those executable(s). (Each -d option + takes effect until the next -d.) +

+ +

+ dpkg-shlibdeps does not directly cause the + output control file to be modified. Instead by default it + adds to the debian/substvars file variable + settings like shlibs:Depends. These variable + settings must be referenced in dependency fields in the + appropriate per-binary-package sections of the source + control file. +

+ +

+ For example, the procps package generates two + kinds of binaries, simple C binaries like ps + which require a predependency and full-screen ncurses + binaries like top which require only a + recommendation. It can say in its debian/rules: + + dpkg-shlibdeps -dPre-Depends ps -dRecommends top + + and then in its main control file debian/control: + + ... + Package: procps + Pre-Depends: ${shlibs:Pre-Depends} + Recommends: ${shlibs:Recommends} + ... + +

+ +

+ Sources which produce several binary packages with + different shared library dependency requirements can use + the -pvarnameprefix option to override + the default shlib: prefix (one invocation of + dpkg-shlibdeps per setting of this option). + They can thus produce several sets of dependency + variables, each of the form + varnameprefix:dependencyfield, + which can be referred to in the appropriate parts of the + binary package control files. +

+ + + + + + dpkg-distaddfile - adds a file to + debian/files + + +

+ Some packages' uploads need to include files other than + the source and binary package files. +

+ +

+ dpkg-distaddfile adds a file to the + debian/files file so that it will be included in + the .changes file when + dpkg-genchanges is run. +

+ +

+ It is usually invoked from the binary target of + debian/rules: + + dpkg-distaddfile filename section priority + + The filename is relative to the directory where + dpkg-genchanges will expect to find it - this + is usually the directory above the top level of the source + tree. The debian/rules target should put the + file there just before or just after calling + dpkg-distaddfile. +

+ +

+ The section and priority are passed + unchanged into the resulting .changes file. See + . +

+ + + + dpkg-genchanges - generates a .changes upload + control file + + +

+ This program is usually called by package-independent + automatic building scripts such as + dpkg-buildpackage, but it may also be called + by hand. +

+ +

+ It is usually called in the top level of a built source + tree, and when invoked with no arguments will print out a + straightforward .changes file based on the + information in the source package's changelog and control + file and the binary and source packages which should have + been built. +

+ + + + dpkg-parsechangelog - produces parsed representation of + a changelog + + +

+ This program is used internally by + dpkg-source et al. It may also occasionally + be useful in debian/rules and elsewhere. It + parses a changelog, debian/changelog by default, + and prints a control-file format representation of the + information in it to standard output. +

+ + + dpkg-architecture - + information about the build and host system + + +

+ This program can be used manually, but is also invoked by + dpkg-buildpackage or debian/rules to set + to set environment or make variables which specify the build and + host architecture for the package building process. +

+ + + + The Debianised source tree + + +

+ The source archive scheme described later is intended to + allow a Debianised source tree with some associated control + information to be reproduced and transported easily. The + Debianised source tree is a version of the original program + with certain files added for the benefit of the + Debianisation process, and with any other changes required + made to the rest of the source code and installation + scripts. +

+ +

+ The extra files created for Debian are in the subdirectory + debian of the top level of the Debianised source + tree. They are described below. +

+ + debian/rules - the main building + script + + +

+ This file is an executable makefile, and contains the + package-specific recipies for compiling the package and + building binary package(s) out of the source. +

+ +

+ It must start with the line #!/usr/bin/make -f, + so that it can be invoked by saying its name rather than + invoking make explicitly. +

+ +

+ Since an interactive debian/rules script makes it + impossible to autocompile that package and also makes it + hard for other people to reproduce the same binary + package, all required targets have to be + non-interactive. At a minimul, required targets are the + ones called by dpkg-buildpackage, namely, + clean, binary, binary-arch, and + build. It also follows that any target that these + targets depend on must also be non-interactive. +

+ +

+ The targets which are required to be present are: + + build + +

+ This should perform all non-interactive + configuration and compilation of the package. If a + package has an interactive pre-build configuration + routine, the Debianised source package should be + built after this has taken place, so that it can be + built without rerunning the configuration. +

+ +

+ For some packages, notably ones where the same + source tree is compiled in different ways to produce + two binary packages, the build target + does not make much sense. For these packages it is + good enough to provide two (or more) targets + (build-a and build-b or whatever) + for each of the ways of building the package, and a + build target that does nothing. The + binary target will have to build the + package in each of the possible ways and make the + binary package out of each. +

+ +

+ The build target must not do anything + that might require root privilege. +

+ +

+ The build target may need to run + clean first - see below. +

+ +

+ When a package has a configuration routine that + takes a long time, or when the makefiles are poorly + designed, or when build needs to run + clean first, it is a good idea to + touch build when the build process is + complete. This will ensure that if debian/rules + build is run again it will not rebuild the + whole program. +

+ + + binary, binary-arch, + binary-indep + + +

+ The binary target should be all that is + necessary for the user to build the binary + package. All these targets are required to be + non-interactive. It is split into two parts: + binary-arch builds the packages' output + files which are specific to a particular + architecture, and binary-indep builds + those which are not. +

+ +

+ binary should usually be a target with + no commands which simply depends on + binary-arch and + binary-indep. +

+ +

+ Both binary-* targets should depend on + the build target, above, so that the + package is built if it has not been already. It + should then create the relevant binary package(s), + using dpkg-gencontrol to make their + control files and dpkg-deb to build + them and place them in the parent of the top level + directory. +

+ +

+ If one of the binary-* targets has + nothing to do (this will be always be the case if + the source generates only a single binary package, + whether architecture-dependent or not) it + must still exist, but should always + succeed. +

+ +

+ describes how to construct + binary packages. +

+ +

+ The binary targets must be invoked as + root. +

+ + + clean + + +

+ This should undo any effects that the + build and binary targets + may have had, except that it should leave alone any + output files created in the parent directory by a + run of binary. This target is required + to be non-interactive. +

+ +

+ If a build file is touched at the end + of the build target, as suggested + above, it must be removed as the first thing that + clean does, so that running + build again after an interrupted + clean doesn't think that everything is + already done. +

+ +

+ The clean target must be invoked as + root if binary has been invoked since + the last clean, or if + build has been invoked as root (since + build may create directories, for + example). +

+ + + get-orig-source (optional) + + +

+ This target fetches the most recent version of the + original source package from a canonical archive + site (via FTP or WWW, for example), does any + necessary rearrangement to turn it into the original + source tarfile format described below, and leaves it + in the current directory. +

+ +

+ This target may be invoked in any directory, and + should take care to clean up any temporary files it + may have left. +

+ +

+ This target is optional, but providing it if + possible is a good idea. +

+ + + +

+ The build, binary and + clean targets must be invoked with a current + directory of the package's top-level directory. +

+ + +

+ Additional targets may exist in debian/rules, + either as published or undocumented interfaces or for the + package's internal use. +

+ +

+ The architecture we build on and build for is determined by make + variables via dpkg-architecture (see ). You can + get the Debian architecture and the GNU style architecture + specification string for the build machine as well as the host + machine. Here is a list of supported make variables: + + +

DEB_*_ARCH (the Debian architecture)

+ + +

DEB_*_GNU_TYPE (the GNU style architecture + specification string)

+ + +

DEB_*_GNU_CPU (the CPU part of DEB_*_GNU_TYPE)

+ + +

DEB_*_GNU_SYSTEM (the System part of + DEB_*_GNU_TYPE)

+ +

+ +

+ where * is either BUILD for specification of + the build machine or HOST for specification of the machine + we build for. +

+ +

+ Backward compatibility can be provided in the rules file + by setting the needed variables to suitable default + values, please refer to the documentation of + dpkg-architecture for details. +

+ +

+ It is important to understand that the DEB_*_ARCH + string does only determine which Debian architecture we + build on resp. for. It should not be used to get the CPU + or System information, the GNU style variables should be + used for that. +

+ + + + debian/control + + +

+ This file contains version-independent details about the + source package and about the binary packages it creates. +

+ +

+ It is a series of sets of control fields, each + syntactically similar to a binary package control file. + The sets are separated by one or more blank lines. The + first set is information about the source package in + general; each subsequent set describes one binary package + that the source tree builds. +

+ +

+ The syntax and semantics of the fields are described below + in . +

+ +

+ The general (binary-package-independent) fields are: + + +

Source (mandatory)

+ + +

Maintainer

+ + +

+ Section and + Priority + (classification, mandatory) +

+ + +

+ Build-Depends et + al. (source package interrelationships) +

+ + +

+ Standards-Version +

+ + + +

+ The per-binary-package fields are: + + +

Package (mandatory)

+ + +

+ Architecture + (mandatory)

+ + +

Description

+ + +

+ Section and + Priority (classification)

+ + +

Essential

+ + +

+ Depends et + al. (binary package interrelationships) +

+ + + +

+ These fields are used by dpkg-gencontrol to + generate control files for binary packages (see below), by + dpkg-genchanges to generate the + .changes file to accompany the upload, and by + dpkg-source when it creates the .dsc + source control file as part of a source archive. +

+ +

+ The fields here may contain variable references - their + values will be substituted by + dpkg-gencontrol, dpkg-genchanges + or dpkg-source when they generate output + control files. See for details. +

+ +

User-defined fields + + +

+ Additional user-defined fields may be added to the + source package control file. Such fields will be + ignored, and not copied to (for example) binary or + source package control files or upload control files. +

+ +

+ If you wish to add additional unsupported fields to + these output files you should use the mechanism + described here. +

+ +

+ Fields in the main source control information file with + names starting X, followed by one or more of + the letters BCS and a hyphen -, will + be copied to the output files. Only the part of the + field name after the hyphen will be used in the output + file. Where the letter B is used the field + will appear in binary package control files, where the + letter S is used in source package control + files and where C is used in upload control + (.changes) files. +

+ +

+ For example, if the main source information control file + contains the field + + XBS-Comment: I stand between the candle and the star. + + then the binary and source package control files will contain the + field + + Comment: I stand between the candle and the star. + +

+ + + + + debian/changelog + + +

+ This file records the changes to the Debian-specific parts of the + package + +

+ Though there is nothing stopping an author who is also + the Debian maintainer from using it for all their + changes, it will have to be renamed if the Debian and + upstream maintainers become different + people. +

+ . +

+ +

+ It has a special format which allows the package building + tools to discover which version of the package is being + built and find out other release-specific information. +

+ +

+ That format is a series of entries like this: + + package (version) distribution(s); urgency=urgency + + * change details + more change details + * even more change details + + -- maintainer name and email address date + +

+ +

+ package and version are the source + package name and version number. +

+ +

+ distribution(s) lists the distributions where + this version should be installed when it is uploaded - it + is copied to the Distribution field in the + .changes file. See . +

+ +

+ urgency is the value for the Urgency + field in the .changes file for the upload. See + . It is not possible to specify an + urgency containing commas; commas are used to separate + keyword=value settings in + the dpkg changelog format (though there is + currently only one useful keyword, + urgency). +

+ +

+ The change details may in fact be any series of lines + starting with at least two spaces, but conventionally each + change starts with an asterisk and a separating space and + continuation lines are indented so as to bring them in + line with the start of the text above. Blank lines may be + used here to separate groups of changes, if desired. +

+ +

+ The maintainer name and email address should not + necessarily be those of the usual package maintainer. + They should be the details of the person doing + this version. The information here will be + copied to the .changes file, and then later used + to send an acknowledgement when the upload has been + installed. +

+ +

+ The date should be in RFC822 format + +

+ This is generated by the 822-date + program. +

+ ; it should include the timezone specified + numerically, with the timezone name or abbreviation + optionally present as a comment. +

+ +

+ The first `title' line with the package name should start + at the left hand margin; the `trailer' line with the + maintainer and date details should be preceded by exactly + one space. The maintainer details and the date must be + separated by exactly two spaces. +

+ +

+ An Emacs mode for editing this format is available: it is + called debian-changelog-mode. You can have this + mode selected automatically when you edit a Debian + changelog by adding a local variables clause to the end of + the changelog. +

+ + Defining alternative changelog formats + + +

+ It is possible to use a different format to the standard + one, by providing a parser for the format you wish to + use. +

+ +

+ In order to have dpkg-parsechangelog run your + parser, you must include a line within the last 40 lines + of your file matching the Perl regular expression: + \schangelog-format:\s+([0-9a-z]+)\W The part in + parentheses should be the name of the format. For + example, you might say: + + @@@ changelog-format: joebloggs @@@ + + Changelog format names are non-empty strings of alphanumerics. +

+ +

+ If such a line exists then dpkg-parsechangelog + will look for the parser as + /usr/lib/dpkg/parsechangelog/format-name + or + /usr/local/lib/dpkg/parsechangelog/format-name; + it is an error for it not to find it, or for it not to + be an executable program. The default changelog format + is dpkg, and a parser for it is provided with + the dpkg package. +

+ +

+ The parser will be invoked with the changelog open on + standard input at the start of the file. It should read + the file (it may seek if it wishes) to determine the + information required and return the parsed information + to standard output in the form of a series of control + fields in the standard format. By default it should + return information about only the most recent version in + the changelog; it should accept a + -vversion option to return changes + information from all versions present strictly + after version, and it should then be an + error for version not to be present in the + changelog. +

+ +

+ The fields are: + + +

Source

+ + +

Version (mandatory)

+ + +

+ Distribution + (mandatory) +

+ + +

Urgency (mandatory)

+ + +

+ Maintainer + (mandatory) +

+ + +

Date

+ + +

+ Changes + (mandatory) +

+ + + +

+ If several versions are being returned (due to the use + of -v), the urgency value should be of the + highest urgency code listed at the start of any of the + versions requested followed by the concatenated + (space-separated) comments from all the versions + requested; the maintainer, version, distribution and + date should always be from the most recent version. +

+ +

+ For the format of the Changes field see . +

+ +

+ If the changelog format which is being parsed always or + almost always leaves a blank line between individual + change notes these blank lines should be stripped out, + so as to make the resulting output compact. +

+ +

+ If the changelog format does not contain date or package + name information this information should be omitted from + the output. The parser should not attempt to synthesise + it or find it from other sources. +

+ +

+ If the changelog does not have the expected format the + parser should exit with a nonzero exit status, rather + than trying to muddle through and possibly generating + incorrect output. +

+ +

+ A changelog parser may not interact with the user at + all.

 + + + debian/substvars + and variable substitutions + + +

+ When dpkg-gencontrol, + dpkg-genchanges and dpkg-source + generate control files they do variable substitutions on + their output just before writing it. Variable + substitutions have the form + ${variable-name}. The optional file + debian/substvars contains variable substitutions + to be used; variables can also be set directly from + debian/rules using the -V option to the + source packaging commands, and certain predefined + variables are available. +

+ +

+ The is usually generated and modified dynamically by + debian/rules targets; in this case it must be + removed by the clean target. +

+ +

+ See for full + details about source variable substitutions, including the + format of debian/substvars.

+ + + debian/files + + +

+ This file is not a permanent part of the source tree; it + is used while building packages to record which files are + being generated. dpkg-genchanges uses it + when it generates a .changes file. +

+ +

+ It should not exist in a shipped source package, and so it + (and any backup files or temporary files such as + files.new + +

+ files.new is used as a temporary file by + dpkg-gencontrol and + dpkg-distaddfile - they write a new + version of files here before renaming it, + to avoid leaving a corrupted copy if an error + occurs +

+ ) should be removed by the + clean target. It may also be wise to + ensure a fresh start by emptying or removing it at the + start of the binary target. +

+ +

+ dpkg-gencontrol adds an entry to this file + for the .deb file that will be created by + dpkg-deb from the control file that it + generates, so for most packages all that needs to be done + with this file is to delete it in clean. +

+ +

+ If a package upload includes files besides the source + package and any binary packages whose control files were + made with dpkg-gencontrol then they should be + placed in the parent of the package's top-level directory + and dpkg-distaddfile should be called to add + the file to the list in debian/files.

+ + + debian/tmp + + +

+ This is the canonical temporary location for the + construction of binary packages by the binary + target. The directory tmp serves as the root of + the filesystem tree as it is being constructed (for + example, by using the package's upstream makefiles install + targets and redirecting the output there), and it also + contains the DEBIAN subdirectory. See . +

+ +

+ If several binary packages are generated from the same + source tree it is usual to use several + debian/tmpsomething directories, for + example tmp-a or tmp-doc. +

+ +

+ Whatever tmp directories are created and used by + binary must of course be removed by the + clean target.

 + + + + Source packages as archives + + +

+ As it exists on the FTP site, a Debian source package + consists of three related files. You must have the right + versions of all three to be able to use them. +

+ +

+ + Debian source control file - .dsc + + +

+ This file contains a series of fields, identified and + separated just like the fields in the control file of + a binary package. The fields are listed below; their + syntax is described above, in . + + +

Source

+ + +

Version

+ + +

Maintainer

+ + +

Binary

+ + +

Architecture

+ + +

+ Build-Depends et + al. (source package interrelationships) +

+ + +

+ Standards-Version

+ + +

Files

+ + + +

+ The source package control file is generated by + dpkg-source when it builds the source + archive, from other files in the source package, + described above. When unpacking it is checked against + the files and directories in the other parts of the + source package, as described below.

+ + + + Original source archive - + + package_upstream-version.orig.tar.gz + + + + + +

+ This is a compressed (with gzip -9) + tar file containing the source code from + the upstream authors of the program. The tarfile + unpacks into a directory + package-upstream-version.orig, + and does not contain files anywhere other than in + there or in its subdirectories.

+ + + + Debianisation diff - + + package_upstream_version-revision.diff.gz + + + + +

+ This is a unified context diff (diff -u) + giving the changes which are required to turn the + original source into the Debian source. These changes + may only include editing and creating plain files. + The permissions of files, the targets of symbolic + links and the characteristics of special files or + pipes may not be changed and no files may be removed + or renamed. +

+ +

+ All the directories in the diff must exist, except the + debian subdirectory of the top of the source + tree, which will be created by + dpkg-source if necessary when unpacking. +

+ +

+ The dpkg-source program will + automatically make the debian/rules file + executable (see below).

 + + + +

+ If there is no original source code - for example, if the + package is specially prepared for Debian or the Debian + maintainer is the same as the upstream maintainer - the + format is slightly different: then there is no diff, and the + tarfile is named + package_version.tar.gz and + contains a directory + package-version. +

+ + + Unpacking a Debian source package without + dpkg-source + + +

+ dpkg-source -x is the recommended way to unpack a + Debian source package. However, if it is not available it + is possible to unpack a Debian source archive as follows: + + +

+ Untar the tarfile, which will create a .orig + directory.

+ + +

Rename the .orig directory to + package-version.

+ + +

+ Create the subdirectory debian at the top of + the source tree.

+ +

Apply the diff using patch -p0.

+ +

Untar the tarfile again if you want a copy of the original + source code alongside the Debianised version.

+ + + +

+ It is not possible to generate a valid Debian source archive + without using dpkg-source. In particular, + attempting to use diff directly to generate the + .diff.gz file will not work. +

+ + Restrictions on objects in source packages + + +

+ The source package may not contain any hard links + +

+ This is not currently detected when building source + packages, but only when extracting + them. +

+ + +

+ Hard links may be permitted at some point in the + future, but would require a fair amount of + work. +

+ , device special files, sockets or setuid or + setgid files. + +

+ Setgid directories are allowed. +

+ +

+ +

+ The source packaging tools manage the changes between the + original and Debianised source using diff and + patch. Turning the original source tree as + included in the .orig.tar.gz into the debianised + source must not involve any changes which cannot be + handled by these tools. Problematic changes which cause + dpkg-source to halt with an error when + building the source package are: + +

Adding or removing symbolic links, sockets or pipes.

+ +

Changing the targets of symbolic links.

+ +

Creating directories, other than debian.

+ +

Changes to the contents of binary files.

 + Changes which cause dpkg-source to + print a warning but continue anyway are: + + +

+ Removing files, directories or symlinks. + +

+ Renaming a file is not treated specially - it is + seen as the removal of the old file (which + generates a warning, but is otherwise ignored), + and the creation of the new + one.

+ +

+ + +

+ Changed text files which are missing the usual final + newline (either in the original or the modified + source tree). +

+ + + Changes which are not represented, but which are not detected by + dpkg-source, are: + +

Changing the permissions of files (other than + debian/rules) and directories.

 + +

+ +

+ The debian directory and debian/rules + are handled specially by dpkg-source - before + applying the changes it will create the debian + directory, and afterwards it will make + debian/rules world-exectuable. +

+ + + + + Control files and their + fields (from old Packaging Manual) + + +

+ Many of the tools in the dpkg suite manipulate + data in a common format, known as control files. Binary and + source packages have control data as do the .changes + files which control the installation of uploaded files, and + dpkg's internal databases are in a similar + format. +

+ + Syntax of control files + + +

+ A file consists of one or more paragraphs of fields. The + paragraphs are separated by blank lines. Some control files + only allow one paragraph; others allow several, in which + case each paragraph often refers to a different package. +

+ +

+ Each paragraph is a series of fields and values; each field + consists of a name, followed by a colon and the value. It + ends at the end of the line. Horizontal whitespace (spaces + and tabs) may occur before or after the value and is ignored + there; it is conventional to put a single space after the + colon. +

+ +

+ Some fields' values may span several lines; in this case + each continuation line must start with a space or + tab. Any trailing spaces or tabs at the end of individual + lines of a field value are ignored. +

+ +

+ Except where otherwise stated only a single line of data is + allowed and whitespace is not significant in a field body. + Whitespace may never appear inside names (of packages, + architectures, files or anything else), version numbers or + in between the characters of multi-character version + relationships. +

+ +

+ Field names are not case-sensitive, but it is usual to + capitalise the field names using mixed case as shown below. +

+ +

+ Blank lines, or lines consisting only of spaces and tabs, + are not allowed within field values or between fields - that + would mean a new paragraph. +

+ +

+ It is important to note that there are several fields which + are optional as far as dpkg and the related + tools are concerned, but which must appear in every Debian + package, or whose omission may cause problems. When writing + the control files for Debian packages you must read + the Debian policy manual in conjuction with the details + below and the list of fields for the particular file.

+ + + List of fields + + + Package + + +

+ The name of the binary package. Package names consist of + the alphanumerics and + - . + (plus, minus and full stop). + +

+ The characters @ : = + % _ (at, colon, equals, percent + and underscore) used to be legal and are still + accepted when found in a package file, but may not be + used in new packages +

+ +

+ +

+ They must be at least two characters and must start with + an alphanumeric. In current versions of dpkg they are + sort of case-sensitive

This is a + bug.

; use lowercase package names unless + the package you're building (or referring to, in other + fields) is already using uppercase.

+ + + Version + + +

+ This lists the source or binary package's version number - + see . +

+ + + + Architecture + + +

+ This is the architecture string; it is a single word for + the Debian architecture. +

+ +

+ dpkg will check the declared architecture of + a binary package against its own compiled-in value before + it installs it. +

+ +

+ The special value all indicates that the package + is architecture-independent. +

+ +

+ In the main debian/control file in the source + package, or in the source package control file + .dsc, a list of architectures (separated by + spaces) is also allowed, as is the special value + any. A list indicates that the source will build + an architecture-dependent package, and will only work + correctly on the listed architectures. any + indicates that though the source package isn't dependent + on any particular architecture and should compile fine on + any one, the binary package(s) produced are not + architecture-independent but will instead be specific to + whatever the current build architecture is. +

+ +

+ In a .changes file the Architecture + field lists the architecture(s) of the package(s) + currently being uploaded. This will be a list; if the + source for the package is being uploaded too the special + entry source is also present. +

+ +

+ See for information how to get the + architecture for the build process. +

+ + + Maintainer + + +

+ The package maintainer's name and email address. The name + should come first, then the email address inside angle + brackets <> (in RFC822 format). +

+ +

+ If the maintainer's name contains a full stop then the + whole field will not work directly as an email address due + to a misfeature in the syntax specified in RFC822; a + program using this field as an address must check for this + and correct the problem if necessary (for example by + putting the name in round brackets and moving it to the + end, and bringing the email address forward). +

+ +

+ In a .changes file or parsed changelog data this + contains the name and email address of the person + responsible for the particular version in question - this + may not be the package's usual maintainer. +

+ +

+ This field is usually optional in as far as the + dpkg are concerned, but its absence when + building packages usually generates a warning.

+ + + Source + + +

+ This field identifies the source package name. +

+ +

+ In a main source control information or a + .changes or .dsc file or parsed + changelog data this may contain only the name of the + source package. +

+ +

+ In the control file of a binary package (or in a + Packages file) it may be followed by a version + number in parentheses. + +

+ It is usual to leave a space after the package name if + a version number is specified. +

+ This version number may be omitted (and is, by + dpkg-gencontrol) if it has the same value as + the Version field of the binary package in + question. The field itself may be omitted from a binary + package control file when the source package has the same + name and version as the binary package. +

+ + + Package interrelationship fields: + Depends, Pre-Depends, + Recommends Suggests, Conflicts, + Provides, Replaces + + +

+ These fields describe the package's relationships with + other packages. Their syntax and semantics are described + in .

+ + + Description + + +

+ In a binary package Packages file or main source + control file this field contains a description of the + binary package, in a special format. See for details. +

+ +

+ In a .changes file it contains a summary of the + descriptions for the packages being uploaded. The part of + the field before the first newline is empty; thereafter + each line has the name of a binary package and the summary + description line from that binary package. Each line is + indented by one space.

+ + + Essential + + +

+ This is a boolean field which may occur only in the + control file of a binary package (or in the + Packages file) or in a per-package fields + paragraph of a main source control data file. +

+ +

+ If set to yes then dpkg and + dselect will refuse to remove the package + (though it can be upgraded and/or replaced). The other + possible value is no, which is the same as not + having the field at all.

+ + + Section and + Priority + + +

+ These two fields classify the package. The + Priority represents how important that it is that + the user have it installed; the Section + represents an application area into which the package has + been classified. +

+ +

+ When they appear in the debian/control file these + fields give values for the section and priority subfields + of the Files field of the .changes file, + and give defaults for the section and priority of the + binary packages. +

+ +

+ The section and priority are represented, though not as + separate fields, in the information for each file in the + -Filefield of a + .changes file. The section value in a + .changes file is used to decide where to install + a package in the FTP archive. +

+ +

+ These fields are not used by by dpkg proper, + but by dselect when it sorts packages and + selects defaults. See the Debian policy manual for the + priorities in use and the criteria for selecting the + priority for a Debian package, and look at the Debian FTP + archive for a list of currently in-use priorities. +

+ +

+ These fields may appear in binary package control files, + in which case they provide a default value in case the + Packages files are missing the information. + dpkg and dselect will only use + the value from a .deb file if they have no other + information; a value listed in a Packages file + will always take precedence. By default + dpkg-gencontrol does not include the section + and priority in the control file of a binary package - use + the -isp, -is or -ip options to + achieve this effect.

+ + + Binary + + +

+ This field is a list of binary packages. +

+ +

+ When it appears in the .dsc file it is the list + of binary packages which a source package can produce. It + does not necessarily produce all of these binary packages + for every architecture. The source control file doesn't + contain details of which architectures are appropriate for + which of the binary packages. +

+ +

+ When it appears in a .changes file it lists the + names of the binary packages actually being uploaded. +

+ +

+ The syntax is a list of binary packages separated by + commas. + +

+ A space after each comma is conventional. +

+ Currently the packages must be separated using + only spaces in the .changes file.

+ + + Installed-Size + + +

+ This field appears in the control files of binary + packages, and in the Packages files. It gives + the total amount of disk space required to install the + named package. +

+ +

+ The disk space is represented in kilobytes as a simple + decimal number.

+ + + Files + + +

+ This field contains a list of files with information about + each one. The exact information and syntax varies with + the context. In all cases the the part of the field + contents on the same line as the field name is empty. The + remainder of the field is one line per file, each line + being indented by one space and containing a number of + sub-fields separated by spaces. +

+ +

+ In the .dsc (Debian source control) file each + line contains the MD5 checksum, size and filename of the + tarfile and (if applicable) diff file which make up the + remainder of the source package. + +

+ That is, the parts which are not the + .dsc. +

+ The exact forms of the filenames are described + in . +

+ +

+ In the .changes file this contains one line per + file being uploaded. Each line contains the MD5 checksum, + size, section and priority and the filename. The section + and priority are the values of the corresponding fields in + the main source control file - see . If no section or priority is + specified then - should be used, though section + and priority values must be specified for new packages to + be installed properly. +

+ +

+ The special value byhand for the section in a + .changes file indicates that the file in question + is not an ordinary package file and must by installed by + hand by the distribution maintainers. If the section is + byhand the priority should be -. +

+ +

+ If a new Debian revision of a package is being shipped and + no new original source archive is being distributed the + .dsc must still contain the Files field + entry for the original source archive + package-upstream-version.orig.tar.gz, + but the .changes file should leave it out. In + this case the original source archive on the distribution + site must match exactly, byte-for-byte, the original + source archive which was used to generate the + .dsc file and diff which are being uploaded.

+ + + + Standards-Version + + +

+ The most recent version of the standards (the + dpkg programmers' and policy manuals and + associated texts) with which the package complies. This + is updated manually when editing the source package to + conform to newer standards; it can sometimes be used to + tell when a package needs attention. +

+ +

+ Its format is the same as that of a version number except + that no epoch or Debian revision is allowed - see .

+ + + + Distribution + + +

+ In a .changes file or parsed changelog output + this contains the (space-separated) name(s) of the + distribution(s) where this version of the package should + be or was installed. Distribution names follow the rules + for package names. (See ). +

+ +

+ Current distribution values are: + + stable + +

+ This is the current `released' version of Debian + GNU/Linux. A new version is released approximately + every 3 months after the development code has + been frozen for a month of testing. Once the + distribution is stable only major bug fixes + are allowed. When changes are made to this + distribution, the release number is increased + (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc). +

+ + + unstable + +

+ This distribution value refers to the + developmental part of the Debian distribution + tree. New packages, new upstream versions of packages + and bug fixes go into the unstable directory + tree. Download from this distribution at your own + risk.

+ + + contrib + +

+ The packages with this distribution value do not meet + the criteria for inclusion in the main Debian + distribution as defined by the Policy Manual, but meet + the criteria for the contrib + Distribution. There is currently no distinction + between stable and unstable packages in the + contrib or non-free + distributions. Use your best judgement in downloading + from this Distribution.

+ + + non-free + +

+ Like the packages in the contrib seciton, + the packages in non-free do not meet the + criteria for inclusion in the main Debian distribution + as defined by the Policy Manual. Again, use your best + judgement in downloading from this Distribution.

+ + experimental + +

+ The packages with this distribution value are deemed + by their maintainers to be high risk. Oftentimes they + represent early beta or developmental packages from + various sources that the maintainers want people to + try, but are not ready to be a part of the other parts + of the Debian distribution tree. Download at your own + risk.

+ + + frozen + +

+ From time to time, (currently, every 3 months) the + unstable distribution enters a state of + `code-freeze' in anticipation of release as a + stable version. During this period of testing + (usually 4 weeks) only fixes for existing or + newly-discovered bugs will be allowed. +

+ + You should list all distributions that + the package should be installed into. Except in unusual + circumstances, installations to stable should also + go into frozen (if it exists) and + unstable. Likewise, installations into + frozen should also go into unstable.

+ + + Urgency + + +

+ This is a description of how important it is to upgrade to + this version from previous ones. It consists of a single + keyword usually taking one of the values LOW, + MEDIUM or HIGH) followed by an optional + commentary (separated by a space) which is usually in + parentheses. For example: + + Urgency: LOW (HIGH for diversions users) + +

+ +

+ This field appears in the .changes file and in + parsed changelogs; its value appears as the value of the + urgency attribute in a dpkg-style + changelog (see ). +

+ +

+ Urgency keywords are not case-sensitive.

+ + + Date + + +

+ In .changes files and parsed changelogs, this + gives the date the package was built or last edited.

+ + + Format + + +

+ This field occurs in .changes files, and + specifies a format revision for the file. The format + described here is version 1.5. The syntax of the + format value is the same as that of a package version + number except that no epoch or Debian revision is allowed + - see .

+ + + Changes + + +

+ In a .changes file or parsed changelog this field + contains the human-readable changes data, describing the + differences between the last version and the current one. +

+ +

+ There should be nothing in this field before the first + newline; all the subsequent lines must be indented by at + least one space; blank lines must be represented by a line + consiting only of a space and a full stop. +

+ +

+ Each version's change information should be preceded by a + `title' line giving at least the version, distribution(s) + and urgency, in a human-readable way. +

+ +

+ If data from several versions is being returned the entry + for the most recent version should be returned first, and + entries should be separated by the representation of a + blank line (the `title' line may also be followed by the + representation of blank line).

+ + + Filename and + MSDOS-Filename + + +

+ These fields in Packages files give the + filename(s) of (the parts of) a package in the + distribution directories, relative to the root of the + Debian hierarchy. If the package has been split into + several parts the parts are all listed in order, separated + by spaces.

+ + + Size and MD5sum + + +

+ These fields in Packages files give the size (in + bytes, expressed in decimal) and MD5 checksum of the + file(s) which make(s) up a binary package in the + distribution. If the package is split into several parts + the values for the parts are listed in order, separated by + spaces.

+ + + Status + + +

+ This field in dpkg's status file records + whether the user wants a package installed, removed or + left alone, whether it is broken (requiring + reinstallation) or not and what its current state on the + system is. Each of these pieces of information is a + single word.

+ + + Config-Version + + +

+ If a package is not installed or not configured, this + field in dpkg's status file records the last + version of the package which was successfully + configured.

+ + + Conffiles + + +

+ This field in dpkg's status file contains + information about the automatically-managed configuration + files held by a package. This field should not + appear anywhere in a package!

+ + + Obsolete fields + + +

+ These are still recognised by dpkg but should + not appear anywhere any more. + + + Revision + Package-Revision + Package_Revision + +

+ The Debian revision part of the package version was + at one point in a separate control file field. This + field went through several names.

+ + + Recommended +

Old name for Recommends

+ + + Optional +

Old name for Suggests.

+ + Class +

Old name for Priority.

+ + +

+ + + + + Configuration file handling + (from old Packaging Manual) + + +

+ dpkg can do a certain amount of automatic + handling of package configuration files. +

+ +

+ Whether this mechanism is appropriate depends on a number of + factors, but basically there are two approaches to any + particular configuration file. +

+ +

+ The easy method is to ship a best-effort configuration in the + package, and use dpkg's conffile mechanism to + handle updates. If the user is unlikely to want to edit the + file, but you need them to be able to without losing their + changes, and a new package with a changed version of the file + is only released infrequently, this is a good approach. +

+ +

+ The hard method is to build the configuration file from + scratch in the postinst script, and to take the + responsibility for fixing any mistakes made in earlier + versions of the package automatically. This will be + appropriate if the file is likely to need to be different on + each system. +

+ + Automatic handling of configuration files by + dpkg + + +

+ A package may contain a control area file called + conffiles. This file should be a list of filenames + of configuration files needing automatic handling, separated + by newlines. The filenames should be absolute pathnames, + and the files referred to should actually exist in the + package. +

+ +

+ When a package is upgraded dpkg will process + the configuration files during the configuration stage, + shortly before it runs the package's postinst + script, +

+ +

+ For each file it checks to see whether the version of the + file included in the package is the same as the one that was + included in the last version of the package (the one that is + being upgraded from); it also compares the version currently + installed on the system with the one shipped with the last + version. +

+ +

+ If neither the user nor the package maintainer has changed + the file, it is left alone. If one or the other has changed + their version, then the changed version is preferred - i.e., + if the user edits their file, but the package maintainer + doesn't ship a different version, the user's changes will + stay, silently, but if the maintainer ships a new version + and the user hasn't edited it the new version will be + installed (with an informative message). If both have + changed their version the user is prompted about the problem + and must resolve the differences themselves. +

+ +

+ The comparisons are done by calculating the MD5 message + digests of the files, and storing the MD5 of the file as it + was included in the most recent version of the package. +

+ +

+ When a package is installed for the first time + dpkg will install the file that comes with it, + unless that would mean overwriting a file already on the + filesystem. +

+ +

+ However, note that dpkg will not + replace a conffile that was removed by the user (or by a + script). This is necessary because with some programs a + missing file produces an effect hard or impossible to + achieve in another way, so that a missing file needs to be + kept that way if the user did it. +

+ +

+ Note that a package should not modify a + dpkg-handled conffile in its maintainer + scripts. Doing this will lead to dpkg giving + the user confusing and possibly dangerous options for + conffile update when the package is upgraded.

+ + + Fully-featured maintainer script configuration + handling + + +

+ For files which contain site-specific information such as + the hostname and networking details and so forth, it is + better to create the file in the package's + postinst script. +

+ +

+ This will typically involve examining the state of the rest + of the system to determine values and other information, and + may involve prompting the user for some information which + can't be obtained some other way. +

+ +

+ When using this method there are a couple of important + issues which should be considered: +

+ +

+ If you discover a bug in the program which generates the + configuration file, or if the format of the file changes + from one version to the next, you will have to arrange for + the postinst script to do something sensible - usually this + will mean editing the installed configuration file to remove + the problem or change the syntax. You will have to do this + very carefully, since the user may have changed the file, + perhaps to fix the very problem that your script is trying + to deal with - you will have to detect these situations and + deal with them correctly. +

+ +

+ If you do go down this route it's probably a good idea to + make the program that generates the configuration file(s) a + separate program in /usr/sbin, by convention called + packageconfig and then run that if + appropriate from the post-installation script. The + packageconfig program should not + unquestioningly overwrite an existing configuration - if its + mode of operation is geared towards setting up a package for + the first time (rather than any arbitrary reconfiguration + later) you should have it check whether the configuration + already exists, and require a --force flag to + overwrite it.

 + + + Alternative versions of + an interface - update-alternatives (from old + Packaging Manual) + + +

+ When several packages all provide different versions of the + same program or file it is useful to have the system select a + default, but to allow the system administrator to change it + and have their decisions respected. +

+ +

+ For example, there are several versions of the vi + editor, and there is no reason to prevent all of them from + being installed at once, each under their own name + (nvi, vim or whatever). + Nevertheless it is desirable to have the name vi + refer to something, at least by default. +

+ +

+ If all the packages involved cooperate, this can be done with + update-alternatives. +

+ +

+ Each package provides its own version under its own name, and + calls update-alternatives in its postinst to + register its version (and again in its prerm to deregister + it). +

+ +

+ See the manpage for details. +

+ +

+ If update-alternatives does not seem appropriate + you may wish to consider using diversions instead.

+ + + Diversions - overriding a + package's version of a file (from old Packaging Manual) + + +

+ It is possible to have dpkg not overwrite a file + when it reinstalls the package it belongs to, and to have it + put the file from the package somewhere else instead. +

+ +

+ This can be used locally to override a package's version of a + file, or by one package to override another's version (or + provide a wrapper for it). +

+ +

+ Before deciding to use a diversion, read to see if you really want a diversion + rather than several alternative versions of a program. +

+ +

+ There is a diversion list, which is read by dpkg, + and updated by a special program dpkg-divert. + Please see for full + details of its operation. +

+ +

+ When a package wishes to divert a file from another, it should + call dpkg-divert in its preinst to add the + diversion and rename the existing file. For example, + supposing that a smailwrapper package wishes to + install a wrapper around /usr/sbin/smail: + + if [ install = "$1" -o upgrade = "$1" ]; then + dpkg-divert --package smailwrapper --add --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + fi + Testing $1 is necessary so that the script + doesn't try to add the diversion again when + smailwrapper is upgraded. The --package + smailwrapper ensures that smailwrapper's + copy of /usr/sbin/smail can bypass the diversion and + get installed as the true version. +

+ +

+ The postrm has to do the reverse: + + if [ remove = "$1" ]; then + dpkg-divert --package smailwrapper --remove --rename \ + --divert /usr/sbin/smail.real /usr/sbin/smail + fi + +

+ +

+ Do not attempt to divert a file which is vitally important for + the system's operation - when using dpkg-divert + there is a time, after it has been diverted but before + dpkg has installed the new version, when the file + does not exist.

+ + -- 2.39.2