From 323ddcaa04c9ca5e44d8235b43f149475cbfbdcd Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:10:04 +0000 Subject: [PATCH] * Corrected typos and grammatical errors found by Sean Perry Author: jdg Date: 2001/02/15 10:57:52 * Corrected typos and grammatical errors found by Sean Perry closes: Bug#85501, #85504, #85505, #85506 closes: Bug#85508, #85510, #85511, #85514 closes: Bug#84631, #84636, #85497, #85982 closes: Bug#85986, #85993, #86001 * No longer include the old proposal document closes: Bug#84079 * Update footnote about dpkg-shlibdeps now that it uses objdump; bump up minor version number for this * Updated dpkg-shlibdeps example to use up-to-date package names (and correct dpkg-shlibdeps command line syntax) * Clarify error conditions for package installation (Bug#61801 from packaging-manual) * Add the "main" section of each distribution (got left out by accident!) (Bug#64304, #75955 from packaging-manual) * Clean version numbering string (Bug#73064 from packaging-manual) git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-80 --- debian/changelog | 23 +- debian/rules | 20 +- policy.sgml | 1661 ++++++++++++++++---------------- upgrading-checklist.html | 57 +- virtual-package-names-list.txt | 4 +- 5 files changed, 892 insertions(+), 873 deletions(-) diff --git a/debian/changelog b/debian/changelog index 32ad33f..0ecd30d 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,4 +1,4 @@ -debian-policy (3.5.0.1) unstable; urgency=low +debian-policy (3.5.1.0) unstable; urgency=low * Removed deprecated virtual package names closes: Bug#84641 * Changed rmdir postrm example (suggestion on -policy list) @@ -6,8 +6,20 @@ debian-policy (3.5.0.1) unstable; urgency=low * Corrected typos and grammatical errors found by Sean Perry closes: Bug#85501, #85504, #85505, #85506 closes: Bug#85508, #85510, #85511, #85514 - - -- + closes: Bug#84631, #84636, #85497, #85982 + closes: Bug#85986, #85993, #86001 + * No longer include the old proposal document closes: Bug#84079 + * Update footnote about dpkg-shlibdeps now that it uses objdump; bump up + minor version number for this + * Updated dpkg-shlibdeps example to use up-to-date package names (and + correct dpkg-shlibdeps command line syntax) + * Clarify error conditions for package installation + (Bug#61801 from packaging-manual) + * Add the "main" section of each distribution (got left out by + accident!) (Bug#64304, #75955 from packaging-manual) + * Clean version numbering string (Bug#73064 from packaging-manual) + + -- Julian Gilbey Thu, 15 Feb 2001 10:55:19 +0000 debian-policy (3.5.0.0) unstable; urgency=low @@ -70,8 +82,9 @@ debian-policy (3.2.1.2) unstable; urgency=low debian-policy (3.2.1.1) unstable; urgency=low * Don't compress version.ent in the doc directory (it gets bigger!) - * Incorporate the packaging manual. The minimal change in version number - i because I suspect that this version is going to be buggy. + * Incorporate the packaging manual into the policy document. The minimal + change in version number is because I suspect that this version is + going to be buggy. closes: Bug#62943, Bug#72949 * Fixed typo in menu-policy. closes: Bug#70442 * Fixed typo in policy manual closes: Bug#70634, Bug#70643 diff --git a/debian/rules b/debian/rules index bec00f8..f6da869 100755 --- a/debian/rules +++ b/debian/rules @@ -41,19 +41,17 @@ FILES_TO_CLEAN = debian/files debian/buildinfo debian/substvars \ debian/postinst debian/prerm \ version.ent policy.lout policy.lout.ld lout.li \ upgrading-checklist.text policy.text.gz \ - menu-policy.text.gz \ - policy-process.text.gz policy-process.pdf.gz \ - proposal.text.gz menu-policy.pdf.gz proposal.pdf.gz \ + menu-policy.text.gz menu-policy.pdf.gz \ + policy-process.text.gz policy-process.pdf.gz \ mime-policy.text.gz mime-policy.pdf.gz \ debconf_spec/debconf_specification.html \ debconf_spec/debconf_specification.txt.gz \ STAMPS_TO_CLEAN = stamp-policy stamp-build stamp-configure DIRS_TO_CLEAN = debian/tmp policy.html fhs \ - menu-policy.html mime-policy.html \ - proposal.html policy-process.html -SGML_FILES = policy menu-policy mime-policy proposal \ - policy-process + menu-policy.html mime-policy.html \ + policy-process.html +SGML_FILES = policy menu-policy mime-policy policy-process # Location of the source dir SRCTOP := $(shell if [ "$$PWD" != "" ]; then echo $$PWD; else pwd; fi;) @@ -68,11 +66,10 @@ LIBDIR := $(TMPTOP)/usr/share/doc-base # And with version 2.1, we have to build the text and dvi versions # ourselves :-( FHS_ARCHIVE =fhs-2.1-source.tar.gz -FHS_FILES = fhs/fhs.ps fhs/fhs.txt fhs/fhs.pdf +FHS_FILES =fhs/fhs.ps fhs/fhs.txt fhs/fhs.pdf FSSTND_FILES =FSSTND-FAQ fsstnd-1.2.dvi.gz fsstnd-1.2.ps.gz fsstnd-1.2.txt.gz POLICY_FILES =policy.text.gz policy.sgml virtual-package-names-list.text \ - upgrading-checklist.text libc6-migration.text \ - version.ent proposal.sgml proposal.text.gz \ + upgrading-checklist.text libc6-migration.text version.ent \ menu-policy.sgml menu-policy.text.gz \ mime-policy.sgml mime-policy.text.gz \ policy-process.text.gz policy-process.sgml \ @@ -172,7 +169,6 @@ stamp-policy: build (tar cf - policy.html) | (cd $(DOCDIR); tar xf -) (tar cf - menu-policy.html) | (cd $(DOCDIR); tar xf -) (tar cf - mime-policy.html) | (cd $(DOCDIR); tar xf -) - (tar cf - proposal.html) | (cd $(DOCDIR); tar xf -) (tar cf - policy-process.html) | (cd $(DOCDIR); tar xf -) sed -e 's/#PACKAGE#/$(package)/g' debian/postinst.in > debian/postinst sed -e 's/#PACKAGE#/$(package)/g' debian/prerm.in > debian/prerm @@ -186,7 +182,7 @@ stamp-policy: build debiandoc2latexpdf policy.sgml gzip -9qfv policy.pdf GZIP=-9v tar zcf policy.html.tar.gz policy.html - $(install_file) version.ent $(DOCDIR)/ + $(install_file) version.ent $(DOCDIR)/ for i in $(BYHAND_FILES); do \ $(install_file) $$i .. ; \ dpkg-distaddfile -fdebian/files `basename $$i` byhand - ; \ diff --git a/policy.sgml b/policy.sgml index 6680d8e..b01eb18 100644 --- a/policy.sgml +++ b/policy.sgml @@ -10,7 +10,7 @@ released under the terms of the GNU General Public License, version 2 or (at your option) any later. Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu - Revised November 27, 1996, David A. Morris, bweaver@debian.org + Revised November 27, 1996, David A. Morris, bweaver@debian.org New sections March 15, 1997, Christian Schwarz, schwarz@debian.org Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org Maintainer since 1997, Christian Schwarz, schwarz@debian.org @@ -19,7 +19,7 @@ contents of this document since September 1998, with the package maintainers responsible for packaging administrivia only. --> - + Debian Policy Manual @@ -28,11 +28,11 @@ ijackson@gnu.ai.mit.edu - Christian Schwarz + Christian Schwarz schwarz@debian.org - revised: David A. Morris + revised: David A. Morris bweaver@debian.org @@ -90,8 +90,8 @@

A copy of the GNU General Public License is available as /usr/share/common-licences/GPL in the Debian GNU/Linux - distribution or on the World Wide Web at - . You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. @@ -100,7 +100,7 @@ - + About this manual @@ -113,8 +113,8 @@ each package must satisfy to be included in the distribution.

- - + +

This manual also describes Debian policy as it relates to creating Debian packages. It is not a tutorial on how to build @@ -153,17 +153,17 @@ Please note that these are not mutually exclusive; selected conventions often become parts of standard - interfaces. + interfaces.

- +

Please note that the footnotes present in this manual are merely informative, and are not part of Debian policy itself.

- - + +

In this manual, the words must, should and may, and the adjectives required, @@ -248,7 +248,7 @@

The main and the non-US/main sections form - the Debian GNU/Linux distribution. + the Debian GNU/Linux distribution.

@@ -400,7 +400,7 @@

Every package in "main" and "non-US/main" must comply with the DFSG (Debian Free Software Guidelines).

- +

In addition, the packages in "main" @@ -452,7 +452,7 @@ The contrib section

Every package in "contrib" and "non-US/contrib" must - comply with the DFSG. + comply with the DFSG.

@@ -462,7 +462,7 @@

free packages which require "contrib", "non-free" - packages or packages which are not in our + packages or packages which are not in our archive at all for compilation or execution,

@@ -481,7 +481,7 @@ Packages must be placed in "non-free" or "non-US/non-free" if they are not compliant with the DFSG or are encumbered by patents or other legal issues that make their - distribution problematic. + distribution problematic.

@@ -506,7 +506,7 @@

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file - /usr/share/doc/<package-name>/copyright (see + /usr/share/doc/<package-name>/copyright (see for details).

We reserve the right to restrict files from being included @@ -599,14 +599,14 @@ Priorities - +

Each package should have a priority value, which is included in the package's control record. This information is used in the Debian package management tool to separate high-priority packages from less-important packages.

- +

The following priority levels are supported by the Debian package management system, dpkg. @@ -643,7 +643,7 @@ standard -

+

These packages provide a reasonably small but not too limited character-mode system. This is what will install by default if the user doesn't select anything @@ -655,7 +655,7 @@ optional -

+

(In a sense everything is optional that isn't required, but that's not what is meant here.) This is all the software that you might reasonably want to @@ -677,7 +677,7 @@

- +

Packages must not depend on packages with lower priority values (excluding build-time dependencies). In order to @@ -685,35 +685,35 @@ be adjusted.

- + Binary packages - +

The Debian GNU/Linux distribution is based on the Debian package management system, called dpkg. Thus, all packages in the Debian distribution must be provided in the .deb file format.

- - + + The package name - +

Every package must have a name that's unique within the Debian archive.

- +

Package names must only consist of lower case letters, digits (0-9), plus (+) or minus (-) signs, and periods (.).

- +

The package name is part of the file name of the .deb file and is included in the control field information.

- + The maintainer of a package

@@ -732,7 +732,7 @@ he/she should try to avoid having different forms of their name and email address in different Maintainer fields.

- +

If the maintainer of a package quits from the Debian project the Debian QA Group @@ -742,15 +742,15 @@ orphaned packages.

- - + + The description of a package - +

Every Debian package must have an extended description stored in the appropriate field of the control record.

- +

The description should be written so that it tells the user what they need to know to decide whether to install the @@ -762,43 +762,43 @@ not be included -- that is what the copyright file is for.

 - - + + Dependencies - +

Every package must specify the dependency information about other packages that are required for the first to work correctly.

- +

For example, a dependency entry must be provided for any shared libraries required by a dynamically-linked executable binary in a package.

- +

Packages are not required to declare any dependencies they have on other packages which are marked Essential (see below), and should not do so unless they depend on a particular version of that package.

- +

Sometimes, a package requires another package to be installed and configured before it can be installed. In this case, you must specify a Pre-Depends entry for the package.

- +

You should not specify a Pre-Depends entry for a package before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached.

 - - + + Virtual packages - +

Sometimes, there are several packages doing more-or-less the same job. In this case, it's useful to define a @@ -810,7 +810,7 @@ package. Thus, any other package requiring that function can simply depend on the virtual package without having to specify all possible packages individually.

- +

All packages should use virtual package names where appropriate, and arrange to create new ones if necessary. @@ -818,7 +818,7 @@ amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package names.

- +

The latest version of the authoritative list of virtual package names can be found on @@ -827,11 +827,11 @@ or your local mirror. In addition, it is included in the debian-policy package. The procedure for updating the list is described at the top of the file.

 - - + + Base packages - +

The packages included in the base section have a special function. They form a minimum subset of the Debian @@ -839,28 +839,28 @@ on a new system. Thus, only very few packages are allowed to go into the base section to keep the required disk usage very small.

- +

Most of these packages will have the priority value required or at least important, and many of them will be tagged essential (see below).

- +

You must not place any packages into the base section before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached.

 - - + + Essential packages - +

Some packages are tagged essential. (They have Essential: yes in their package control record.) This flag is used for packages that are essential for a system.

- +

Since these packages can not easily be removed (you'll have to specify an extra force option to @@ -870,7 +870,7 @@ prevent its premature removal, and we need to be able to remove it when it has been superseded.

- +

Since dpkg will not prevent upgrading of other packages while an essential package is in an unconfigured @@ -887,11 +887,11 @@ this has been discussed on the debian-devel mailing and a consensus about doing that has been reached.

 - - + + Maintainer scripts - +

The package installation scripts should avoid producing output which it is unnecessary for the user to see and @@ -912,7 +912,7 @@

- You should not use dpkg-divert' on a file + You should not use dpkg-divert on a file belonging to another package without consulting the maintainer of that package first.

@@ -942,13 +942,13 @@ higher. (Included in the debconf_specification files in the debian-policy package.) - You may also find this file on the FTP site + You may also find this file on the FTP site ftp.debian.org in /debian/doc/package-developer/debconf_specification.txt.gz - or your local mirror. + or your local mirror.

- 2.5% of Debian packages + 2.5% of Debian packages [] use debconf to prompt the user at install time, and this number is growing daily. The benefits of using @@ -967,7 +967,7 @@ the stabalization of the protocol these things use, the time has finally come to reflect the use of these things in policy. - +

@@ -980,7 +980,7 @@ package is unpacked or any of its dependancies or pre-dependancies are satisfied, so it must work using only the tools present in the Essential - packages. + packages.

Debconf or another tool that implements the Debian @@ -1001,7 +1001,7 @@ rather than each prompting for their own list of required pieces of information.

- +

It also means that an upgrade should not ask the same questions again, unless the user has used dpkg @@ -1010,7 +1010,7 @@ appropriate place in /etc so that the user can modify them, and how this has been done should be documented.

- +

If a package has a vitally important piece of information to pass to the user (such as "don't run me @@ -1025,7 +1025,7 @@ neither do instructions on how to use a program (these should be in on line documentation, where all the users can see them).

- +

Any necessary prompting should almost always be confined to the config or postinst @@ -1035,29 +1035,29 @@ and the postinst is called with abort-upgrade, abort-remove or abort-deconfigure.

- + Source packages - + Standards conformance - +

You should specify the most recent version of the packaging standards with which your package complies in the source package's Standards-Version field.

- +

This value will be used to file bug reports automatically if your package becomes too much out of date.

- +

The value corresponds to a version of the Debian manuals, as can be found on the title page or page headers and footers (depending on the format).

- +

The version number has four components--major and minor number and major and minor patch level. When the @@ -1087,7 +1087,7 @@

- +

You should regularly, and especially if your package has become out of date, check for the newest Policy Manual @@ -1095,11 +1095,11 @@ package complies with the new standards you should update the Standards-Version source package field and release it.

 - - + + Package relationships - +

Source packages should specify which binary packages they require to be installed or not to be installed in order to @@ -1107,7 +1107,7 @@ requires a certain compiler, then the compiler should be specified as a build-time dependency.

- +

It is not necessary to explicitly specify build-time relationships on a minimal set of packages that are always @@ -1130,7 +1130,7 @@

- Having a separate package allows one to nistall + Having a separate package allows one to install the build essential packages on a machine, as well as allowing other packages (think task packages) to bring in the build-essential @@ -1146,10 +1146,10 @@

- +

- +

When specifying the set of build-time dependencies, one should list only those packages explicitly required by the @@ -1159,7 +1159,7 @@ that dependencies change, and you should list only those you need. What others need is their business.

- +

If build-time dependencies are specified, it must be possible to build the package and produce working binaries @@ -1171,16 +1171,16 @@ produce bad or inconsistently configured packages when the relationships are properly satisfied.

- + Changes to the upstream sources - +

If changes to the source code are made that are generally applicable, they should be sent to the upstream authors in whatever form they prefer so as to be included in the upstream version of the package.

- +

If you need to configure the package differently for Debian or for Linux, and the upstream source doesn't @@ -1191,12 +1191,12 @@ the way they originally had it. You can then easily override the default in your debian/rules or wherever is appropriate.

- +

You should make sure that the configure utility detects the correct architecture specification string (refer to for details).

- +

If you need to edit a Makefile where GNU-style configure scripts are used, you @@ -1206,18 +1206,18 @@ not configure the package and edit the generated Makefile! This makes it impossible for someone else to later reconfigure the package.

 - - + + Documenting your changes - +

You should document your changes and updates to the source package properly in the debian/changelog file. (Note that mistakes in changelogs are usually best rectified by making a new changelog entry rather than "rewriting history" by editing old changelog entries)

- +

In non-experimental packages you must only use a format for debian/changelog which is supported by the most @@ -1229,11 +1229,11 @@ the parser and its manpage may be distributed under the GNU GPL, just as the rest of dpkg is.)

 - - + + Error trapping in makefiles - +

When make invokes a command in a makefile (including your package's upstream makefiles and the @@ -1244,7 +1244,7 @@ don't do anything about it then errors are not detected and make will blithely continue after problems.

- +

Every time you put more than one shell command (this includes using a loop) in a makefile command you @@ -1256,11 +1256,11 @@ conditionals you should include a separate set -e command at the start of every makefile command that's actually one of these miniature shell scripts.

 - - + + Obsolete constructs and libraries - +

The include file <varargs.h> is provided to support end-users compiling very old software; @@ -1268,7 +1268,7 @@ execution of software which has been linked against it (either old programs or those such as Netscape which are only available in binary form).

- +

Debian packages should be ported to include <stdarg.h> and ncurses when @@ -1279,7 +1279,7 @@ Control files and their fields -

+

Many of the tools in the package management suite manipulate data in a common format, known as control files. Binary and source packages have control data as do the .changes @@ -1287,17 +1287,17 @@ 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 @@ -1306,14 +1306,14 @@ 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, @@ -1322,18 +1322,18 @@ relationships.

-

+

Field names are not case-sensitive, but it is usual to capitalize 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 @@ -1342,33 +1342,34 @@ the Debian policy manual in conjunction with the details below and the list of fields for the particular file.

 - + List of fields

- This list here is not supposed to be exhaustive. Typically - only fields for whom policy exists are mentioned here. + This list here is not supposed to be exhaustive. Most fields + are dealt with elsewhere in this document and in the + packaging manual.

Package -

+

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

-

+

They must be at least two characters long and must start with an alphanumeric character. The use of lowercase package names is strongly recommended 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 .

@@ -1387,17 +1388,17 @@ 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 @@ -1405,13 +1406,13 @@ for package names. (See ).

-

+

Current distribution values are: stable -

+

This is the current `released' version of Debian GNU/Linux. Once the distribution is stable only major bug fixes @@ -1420,7 +1421,7 @@ (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).

- + unstable

@@ -1444,7 +1445,7 @@ be allowed.

- + experimental

@@ -1460,18 +1461,28 @@ There are several sections in each distribution. Currently, these sections are: - + + main + +

+ The packages in this section are those in the + main Debian distribution. They are all free + (according to the Debian free software + guidelines) and meet any other criteria for + inclusion described in this manual.

+ + contrib

The packages in this section do not meet the criteria for inclusion in the main Debian - distribution as defined by the Policy Manual, - but are otherwise free, as defined by the Debian - free software guidelines.

+ distribution as defined by this manual, but are + otherwise free, as defined by the Debian free + software guidelines.

 - + non-free

@@ -1481,7 +1492,7 @@ best judgment in downloading from this Distribution.

 - + You should list all distributions that the package should be installed into. Except in unusual circumstances, installations to stable should also @@ -1491,19 +1502,19 @@

- + Version numbering -

+

Every package has a version number, in its Version control file field.

-

+

The package management system imposes an ordering on version numbers, so that it can tell whether packages are being up- or downgraded and so that package system front end applications @@ -1513,17 +1524,17 @@ concerned) at the beginning.

-

+

The version number format is: - &lsqbepoch:]upstream-version[-/debian-revision]. + &lsqbepoch:]upstream-version[-debian-revision]

-

+

The three components here are: epoch - +

This is a single (generally small) unsigned integer. It may be omitted, in which case zero is assumed. If it is @@ -1531,17 +1542,17 @@ contain any colons.

-

+

It is provided to allow mistakes in the version numbers of older versions of a package, and also a package's previous version numbering schemes, to be left behind.

- + upstream-version - +

This is the main part of the version. It is usually the version number of the original (`upstream') package from @@ -1552,14 +1563,14 @@ management system's format and comparison scheme.

-

+

The comparison behavior of the package management system with respect to the upstream-version is described below. The upstream-version portion of the version number is mandatory.

-

+

The upstream-version may contain only alphanumerics and the characters . + - : (full stop, plus, hyphen, colon) @@ -1568,10 +1579,10 @@ if there is no epoch then colons are not allowed.

 - + debian-revision - +

This part of the version represents the version of the modifications that were made to the package to make it a @@ -1580,7 +1591,7 @@ way.

-

+

It is optional; if it isn't present then the upstream-version may not contain a hyphen. This format represents the case where a piece of @@ -1590,13 +1601,13 @@ indication is required.

-

+

It is conventional to restart the debian-revision at 1 each time the upstream-version is increased.

-

+

The package management system will break the upstream-version and debian-revision apart at the last hyphen in @@ -1606,23 +1617,23 @@ part of the version number).

-

+

The debian-revision may contain only alphanumerics and the characters + and . (plus and full stop).

- + The upstream-version and debian-revision parts are compared by the package management system using the same algorithm:

-

+

The strings are compared from left to right.

-

+

First the initial part of each string consisting entirely of non-digit characters is determined. These two parts (one of which may be empty) are compared lexically. If a difference @@ -1631,7 +1642,7 @@ sort earlier than all the non-letters.

-

+

Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any @@ -1641,13 +1652,13 @@ as zero.

-

+

These two steps are repeated (chopping initial non-digit strings and initial digit strings off from the start) until a difference is found or both strings are exhausted.

-

+

Note that the purpose of epochs is to allow us to leave behind mistakes in version numbering, and to cope with situations where the version numbering changes. It is not there @@ -1659,7 +1670,7 @@ 2.1, 2.2, 2 and so forth).

-

+

If an upstream package has problematic version numbers they should be converted to a sane form for use in the Version field. @@ -1697,7 +1708,7 @@ dates should always use the `YYYYMMDD' format.

 - + Packaging Considerations Time Stamps @@ -1705,7 +1716,7 @@ Maintainers are encouraged to preserve the modification times of the upstream source files in a package, as far as is reasonably possible. Even though this is optional, this - is still a good idea. + is still a good idea.

The rationale is that there is some information conveyed @@ -1718,22 +1729,22 @@

- + debian/rules - the main building script -

+

This file must be an executable makefile, and contains the package-specific recipes 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 auto-compile that package and also makes it @@ -1746,9 +1757,9 @@ that any target that these targets depend on must also be non-interactive.

- -

- The targets which must be present are: + +

+ The targets which must be present are: build @@ -1760,8 +1771,8 @@ 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 @@ -1774,18 +1785,18 @@ 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 @@ -1796,10 +1807,10 @@ whole program.

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

The binary target must be all that is @@ -1811,15 +1822,15 @@ architecture, and binary-indep builds those which are not.

- -

+ +

binary may be (and commonly is) 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 @@ -1829,8 +1840,8 @@ 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, @@ -1839,25 +1850,25 @@ succeed.

-

+

The binary targets must be invoked as root.

- + clean - +

This must 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 must be - non-interactive. + non-interactive.

-

+

If a build file is touched at the end of the build target, as suggested above, it should be removed as the first thing that @@ -1866,8 +1877,8 @@ clean doesn't think that everything is already done.

- -

+ +

The clean target may need to be invoked as root if binary has been invoked since the last clean, or if @@ -1876,11 +1887,11 @@ 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 @@ -1889,32 +1900,32 @@ 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. You can get the Debian @@ -1927,7 +1938,7 @@

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

+ specification string)

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

@@ -1937,20 +1948,20 @@ 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 only determines which Debian architecture we are @@ -1959,11 +1970,11 @@ used for that.

- + debian/changelog - -

+ +

This file records the changes to the Debian-specific parts of the package @@ -1976,39 +1987,39 @@

.

- -

+ +

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: + 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. It is not possible to specify an urgency containing commas; commas @@ -2018,8 +2029,8 @@ 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 @@ -2027,8 +2038,8 @@ 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 need not necessarily be those of the usual package maintainer. They should be the details of the person doing @@ -2037,8 +2048,8 @@ to send an acknowledgement when the upload has been installed.

- -

+ +

The date should be in RFC822 format

@@ -2049,33 +2060,33 @@ numerically, with the time zone 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.

- + 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.

-

+

A changelog parser must 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 @@ -2089,7 +2100,7 @@ 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. @@ -2100,18 +2111,18 @@ 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 @@ -2129,16 +2140,16 @@ 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 @@ -2149,8 +2160,8 @@ Restrictions on objects in source packages - -

+ +

The source package may not contain any hard links

@@ -2176,8 +2187,8 @@ Descriptions of packages - the Description field - -

+ +

The description is intended to describe the program to a user who has never met it before so that they know whether they want to install it. It should also give information about the @@ -2185,24 +2196,24 @@ and others, so that the user knows why these dependencies and conflicts have been declared.

- + Notes about writing descriptions -

+

The single line synopsis should be kept brief - certainly - under 80 characters. + under 80 characters.

- -

+ +

Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line - make it as informative as you can.

- -

+ +

Do not try to continue the single line synopsis into the extended description. This will not work correctly when the full description is displayed, and makes no sense @@ -2210,13 +2221,13 @@ available.

-

+

The extended description should describe what the package does and how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).

- -

+ +

The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. @@ -2230,21 +2241,21 @@

- -

+ +

Put important information first, both in the synopsis and extended description. Sometimes only the first part of the synopsis or of the description will be displayed. You can assume that there will usually be a way to see the whole extended description.

- -

+ +

You may include information about dependencies and so forth in the extended description, if you wish.

- -

+ +

Do not use tab characters. Their effect is not predictable.

@@ -2260,13 +2271,13 @@ Introduction to package maintainer scripts -

+

It is possible to supply scripts as part of a package which the package management system will run for you when your package is installed, upgraded or removed.

-

+

These scripts should be the files preinst, postinst, prerm and postrm in the control area of the package. They must be proper executable @@ -2275,7 +2286,7 @@ readable and executable by anyone, and not world-writable.

-

+

The package management system looks at the exit status from these scripts. It is important that they exit with a non-zero status if there is an error, so that the package @@ -2287,7 +2298,7 @@ well.

-

+

It is necessary for the error recovery procedures that the scripts be idempotent: i.e., invoking the same script several times in the same situation should do no harm. If the first @@ -2297,7 +2308,7 @@ status.

-

+

When a package is upgraded a combination of the scripts from the old and new packages is called in amongst the other steps of the upgrade procedure. If your scripts are going @@ -2305,17 +2316,17 @@ may need to check the arguments to your scripts.

-

+

Broadly speaking the preinst is called before (a particular version of) a package is installed, and the postinst afterwards; the prerm before (a version of) a package is removed and the - postrm afterwards. + postrm afterwards.

- +

Programs called from maintainer scripts should not normally have a path prepended to them. Before installation is started the package management system checks to see if @@ -2367,18 +2378,18 @@ output is printed immediately rather than being buffered.

- +

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

- + Summary of ways maintainer scripts are called -

+

new-preinst install

@@ -2395,10 +2406,10 @@

old-preinst abort-upgrade new-version

- + -

+

postinst configure @@ -2424,7 +2435,7 @@ -

+

prerm remove

@@ -2453,7 +2464,7 @@ -

+

postrm remove

@@ -2488,13 +2499,13 @@ overwriter-version

- - + + Details of unpack phase of installation or upgrade -

+

The procedure on installation/upgrade/overwrite/disappear (i.e., when running dpkg --unpack, or the unpack stage of dpkg --install) is as follows. In each @@ -2502,7 +2513,7 @@ backwards - this means that the maintainer scripts are run with different arguments in reverse order. These are the `error unwind' calls listed below. - +

@@ -2516,8 +2527,8 @@

- If this gives an error (i.e., a non-zero exit - status), dpkg will attempt instead: + If the script runs but exits with a non-zero + exit status, dpkg will attempt: new-prerm failed-upgrade old-version @@ -2548,7 +2559,7 @@ deconfigured's-postinst abort-deconfigure \ in-favour package-being-installed-but-failed version \ removing conflicting-package version - + The deconfigured packages are marked as requiring configuration, so that if --install is used they will be @@ -2586,7 +2597,7 @@ new-preinst install old-version

- +

Otherwise (i.e., the package was completely purged): @@ -2615,7 +2626,7 @@ part of the error unwind).

-

+

It is an error for a package to contains files which are on the system in another package, unless Replaces is used (see ). @@ -2624,7 +2635,7 @@ always be the case.

-

+

It is a more serious error for a package to contain a plain file or other kind of non-directory where another package has a directory (again, unless @@ -2634,7 +2645,7 @@ advisable.

-

+

Packages which overwrite each other's files produce behavior which though deterministic is hard for the system administrator to understand. It can easily @@ -2649,16 +2660,16 @@

-

+

A directory will never be replaced by a symbolic links to a directory or vice versa; instead, the existing state (symlink or not) will be left alone and dpkg will follow the symlink if there is one.

 - + - +

If the package is being upgraded, call @@ -2689,7 +2700,7 @@

-

+

Any files which were in the old version of the package but not in the new are removed.

 @@ -2699,7 +2710,7 @@

The new maintainer scripts replace the old.

 - +

Any packages all of whose files have been overwritten during the installation, and which aren't required for @@ -2747,7 +2758,7 @@ deleted.

- +

The new package's status is now sane, and recorded as @@ -2773,7 +2784,7 @@ Details of configuration -

+

When we configure a package (this happens with dpkg --install, or with --configure), we first update the conffiles and then call: @@ -2782,12 +2793,12 @@

-

+

No attempt is made to unwind after errors during configuration.

-

+

If there is no most recently configured version dpkg will pass a null argument; older versions of dpkg may pass <unknown> (including the @@ -2795,11 +2806,11 @@ second argument at all, under any circumstances.

- + Details of removal and/or configuration purging -

+

@@ -2822,7 +2833,7 @@

All the maintainer scripts except the postrm are removed.

-

+

If we aren't purging the package we stop here. Note that packages which have no postrm and no conffiles are automatically purged when removed, as there is no @@ -2848,12 +2859,12 @@ removal.

 - + Declaring relationships between packages -

+

Packages can declare in their control file that they have certain relationships to other packages - for example, that they may not be installed at the same time as certain other @@ -2862,7 +2873,7 @@ if present.

-

+

This is done using the Depends, Recommends, Suggests, Enhances, Conflicts, Provides and Replaces control file fields. @@ -2870,10 +2881,10 @@

Source packages may declare relationships to binary packages, - saying that they require certain binary packages being + saying that they require certain binary packages to be installed or absent at the time of building the package.

- +

This is done using the Build-Depends, Build-Depends-Indep, Build-Conflicts, and @@ -2883,22 +2894,25 @@ Syntax of relationship fields -

+

These fields all have a uniform syntax. They are a list of package names separated by commas.

- In Depends, Recommends, Suggests, - Pre-Depends, Build-Depends and - Build-Depends-Indep(the fields which declare - dependencies of the package in which they occur on other - packages) these package names may also be lists of - alternative package names, separated by vertical bar symbols - | (pipe symbols). + In the Depends, Recommends, + Suggests, Pre-Depends, + Build-Depends and Build-Depends-Indep + control file fields of the package, which declare + dependencies on other packages, the package names listed may + also include lists of alternative package names, separated + by vertical bar symbols | (pipe symbols). In such + a case, the presence of any one of the alternative packages + is installed, that part of the dependency is considered to + be satisfied.

-

+

All the fields except Provides may restrict their applicability to particular versions of each named package. This is done in parentheses after each individual package @@ -2907,7 +2921,7 @@ described in .

-

+

The relations allowed are <<, <=, =, >= and >> for strictly earlier, earlier or equal, exactly equal, later or @@ -2918,7 +2932,7 @@ dpkg still supports them).

-

+

Whitespace may appear at any point in the version specification, and must appear where it's necessary to disambiguate; it is not otherwise significant. For @@ -2930,7 +2944,7 @@ open parenthesis.

-

+

For example: Package: metamail @@ -2938,7 +2952,7 @@ Depends: libc5 (>= 5.2.18-4), mime-support, csh | tcsh

- +

All fields that specify build-time relationships (Build-Depends, Build-Depends-Indep, @@ -2954,7 +2968,7 @@ the associated version specification are ignored completely for the purposes of defining the relationships.

- +

For example: @@ -2963,22 +2977,22 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], hurd-dev [hurd-i386], gnumach-dev [hurd-i386] -

+

- + Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends -

+

These five fields are used to declare a dependency relationship by one package on another. They appear in the depending package's control file.

-

+

All but Pre-Depends and Conflicts (discussed below) take effect only when a package is to be configured. They do not prevent a package being on @@ -2992,7 +3006,7 @@ properly.

-

+

For this reason packages in an installation run are usually all unpacked first and all configured later; this gives later versions of packages with dependencies on later @@ -3000,37 +3014,37 @@ dependencies satisfied.

-

+

Thus Depends allows package maintainers to impose an order in which packages should be configured. Depends - +

This declares an absolute dependency.

-

+

The Depends field should be used if the depended-on package is required for the depending package to provide a significant amount of functionality.

- + Recommends

This declares a strong, but not absolute, dependency.

-

+

The Recommends field should list packages that would be found together with this one in all but unusual installations.

 - + Suggests - +

This is used to declare that one package may be more useful with one or more others. Using this field @@ -3050,10 +3064,10 @@ package.

- + Pre-Depends - +

This field is like Depends, except that it also forces dpkg to complete installation @@ -3062,14 +3076,14 @@ Pre-dependency.

-

+

Pre-Depends should be used sparingly, preferably only by packages whose premature upgrade or installation would hamper the ability of the system to continue with any upgrade that might be in progress.

-

+

When the package declaring it is being configured, a Pre-Dependency will be considered satisfied only if the depending package has been correctly @@ -3077,7 +3091,7 @@ had been used.

-

+

However, when a package declaring a Pre-dependency is being unpacked the predependency can be satisfied even if the depended-on package(s) are only unpacked or @@ -3091,7 +3105,7 @@

-

+

When selecting which level of dependency to use you should consider how important the depended-on package is to the functionality of the one declaring the dependency. Some @@ -3109,13 +3123,13 @@ Conflicts and Replaces -

+

When one binary package declares a conflict with another dpkg will refuse to allow them to be installed on the system at the same time.

-

+

If one package is to be installed, the other must be removed first - if the package being installed is marked as replacing () the one on the system, or @@ -3129,13 +3143,13 @@

-

+

A package will not cause a conflict merely because its configuration files are still installed; it must be at least half-installed.

-

+

A special exception is made for packages which declare a conflict with their own package name, or with a virtual package which they provide (see below): this does not @@ -3145,19 +3159,19 @@ package providing something.

-

+

A Conflicts entry should almost never have an `earlier than' version clause. This would prevent dpkg from upgrading or installing the package which declared such a conflict until the upgrade or removal - of the conflicted-with package had been completed. + of the conflicted-with package had been completed.

- + Virtual packages - Provides -

+

As well as the names of actual (`concrete') packages, the package relationship fields Depends, Build-Depends, Build-Depends-Indep, @@ -3166,7 +3180,7 @@ mention virtual packages.

-

+

A virtual package is one which appears in the Provides control file field of another package. The effect is as if the package(s) which provide a @@ -3174,7 +3188,7 @@ everywhere the virtual package name appears.

-

+

If there are both a real and a virtual package of the same name then the dependency may be satisfied (or the conflict caused) by either the real package or any of the virtual @@ -3193,20 +3207,20 @@ and vm packages are changed to use it).

-

+

If a dependency or a conflict has a version number attached then only real packages will be considered to see whether the relationship is satisfied (or the prohibition violated, for a conflict) - it is assumed that a real package which - provides virtual package is not of the `right' version. So, - a Provides field may not contain version numbers, - and the version number of the concrete package which - provides a particular virtual package will not be looked at - when considering a dependency on or conflict with the - virtual package name. + provides the virtual package is not of the `right' version. + So, a Provides field may not contain version + numbers, and the version number of the concrete package + which provides a particular virtual package will not be + looked at when considering a dependency on or conflict with + the virtual package name.

-

+

It is likely that the ability will be added in a future release of dpkg to specify a version number for each virtual package it provides. This feature is not yet @@ -3214,42 +3228,42 @@ infrequently.

-

+

If you want to specify which of a set of real packages should be the default to satisfy a particular dependency on a virtual package, you should list the real package as an alternative before the virtual.

- - + + Replaces - overwriting files and replacing packages -

+

The Replaces control file field has two purposes, which come into play in different situations.

-

+

Virtual packages () are not considered when looking at a Replaces field - the packages declared as being replaced must be mentioned by their real names.

- + Overwriting files in other packages -

+

Firstly, as mentioned before, it is usually an error for a - package to contains files which are on the system in + package to contain files which are on the system in another package, though currently the --force-overwrite flag is enabled by default, downgrading the error to a warning,

-

+

If the overwriting package declares that it replaces the one containing the file being overwritten then dpkg will proceed, and replace the file from @@ -3257,7 +3271,7 @@ longer be listed as `owned' by the old package.

-

+

If a package is completely replaced in this way, so that dpkg does not know of any files it still contains, it is considered to have disappeared. It will @@ -3270,25 +3284,26 @@ id="mscriptsinstact">.

-

+

In the future dpkg will discard files which - overwrite those from another package which declares that - it replaces the one being installed (so that you can - install an older version of a package without problems). + would overwrite those from an already installed package + which declares that it replaces the package being + installed. This is so that you can install an older + version of a package without problems.

-

+

This usage of Replaces only takes effect when both packages are at least partially on the system at once, so that it can only happen if they do not conflict or if the conflict has been overridden.

 - + Replacing whole packages, forcing their removal -

+

Secondly, Replaces allows the packaging system to resolve which package should be removed when there is a conflict - see . This usage only @@ -3307,11 +3322,12 @@ A source package may declare a dependency or a conflict on a binary package. This is done with the control file fields Build-Depends, Build-Depends-Indep, - Build-Conflicts, and Build-Conflicts-Indep. Their - semantics is that the dependencies and conflicts they define - must be satisfied (as defined earlier for binary packages), - when one of the targets in debian/rules that the - particular field applies to is invoked. + Build-Conflicts, and + Build-Conflicts-Indep. Their semantics are that + the dependencies and conflicts they define must be satisfied + (as defined earlier for binary packages), when one of the + targets in debian/rules that the particular field + applies to is invoked. Build-Depends, Build-Conflicts @@ -3342,18 +3358,18 @@ Configuration file handling -

+

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 @@ -3362,7 +3378,7 @@ 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 @@ -3370,19 +3386,19 @@ appropriate if the file is likely to need to be different on each system.

- + Shared libraries -

+

Packages containing shared libraries must be constructed with a little care to make sure that the shared library is always available. This is especially important for packages whose shared libraries are vitally important, such as the libc.

-

+

Firstly, your package should install the shared libraries under their normal names. For example, the libgdbm1 package should install @@ -3394,7 +3410,7 @@ with this are likely to lead to problems.

-

+

Secondly, your package should include the symlink that ldconfig would create for the shared libraries. For example, the libgdbm1 package should include @@ -3420,8 +3436,8 @@ - -

+ +

Thirdly, the development package should contain a symlink for the shared library without a version number. For example, the libgdbm1-dev package should include a symlink from @@ -3435,8 +3451,8 @@ - -

+ +

Any package installing shared libraries in a directory that's listed in /etc/ld.so.conf or in one of the default library directories of ld.so (currently, these are /usr/lib @@ -3451,38 +3467,38 @@ installation and removes the links!

- - + The shlibs File Format -

+

This file is for use by dpkg-shlibdeps and is required when your package provides shared libraries.

-

+

Each line is of the form: library-name version-or-soname dependencies ...

-

+

library-name is the name of the shared library, for example libc5.

-

+

version-or-soname is the soname of the library - i.e., the thing that must exactly match for the library to be - recognized by ld.so. Usually this is major + recognized by ld.so. Usually this is the major version number of the library.

-

+

dependencies has the same syntax as a dependency field in a binary package control file. It should give details of which package(s) are required to satisfy a binary @@ -3490,7 +3506,7 @@ package. See .

-

+

For example, if the package foo contains libfoo.so.1.2.3, where the soname of the library is libfoo.so.1, and the first version of the package @@ -3502,125 +3518,128 @@

-

+

The version-specific dependency is to avoid warnings from ld.so about using older shared libraries with newer binaries.

 - + Further Technical information on shlibs - - - + What are the shlibs files? -

+

The debian/shlibs file provides a way of checking for shared library dependencies on packaged binaries. They are intended to be used by package maintainers to make their lives easier.

-

+

Other shlibs files that exist on a Debian system are

/etc/dpkg/shlibs.default

/etc/dpkg/shlibs.override

/var/lib/dpkg/info/*.shlibs

debian/shlibs.local

 - + These files are used by dpkg-shlibdeps when creating a binary package.

 - + How does dpkg-shlibdeps work? -

- dpkg-shlibdeps +

+ dpkg-shlibdeps determines the shared libraries directly - -

- Currently, it calls ldd, but in a - forthcoming version it shall call objdump - to to this. This however changes will need a couple of - changes in the way that packages are build. + +

+ It used to do this by calling ldd, but it + now calls objdump to to this. This + requires a couple of changes in the way that packages + are built.

- Suppose a binary foo directly use a library + A binary foo directly uses a library libbar if it is linked with that library. Other libraries that are needed by libbar are linked indirectly to foo, - and the dynamic linker will load the automatically - when it loads libbar. Using ldd - lists all the libraries, used directly and indirectly; - but objdump only lists the directly - linked libraries. A package only needs to depend on - the libraries it is directly linked to, since the - dependencies for those libraries should automatically - pull in the other libraries.

- + and the dynamic linker will load them automatically + when it loads libbar. Runningldd + lists all of the libraries used, both directly and + indirectly; but objdump only lists the + directly linked libraries. A package only needs to + depend on the libraries it is directly linked to, + since the dependencies for those libraries should + automatically pull in the other libraries. +

This change does mean a change in the way packages are - build though: currently dpkg-shlibdeps is only run on - binaries. But since we will now depend on the - libraries to depend on the libraries they need the - packages containing those libraries will need to run - dpkg-shlibdeps on the libraries. + build though: currently dpkg-shlibdeps is + only run on binaries. But since we will now rely on the + libraries depending on the libraries they themselves + need, the packages containing those libraries will + need to run dpkg-shlibdeps on the + libraries.

A good example where this would help us is the current - mess with multiple version of the mesa library. With - the ldd-based system every package that uses mesa need - to add a dependency on svgalib|svgalib-dummy in order - to handle the glide mesa variant. With an - objdump-based system this isn't necessary anymore and - would have saved everyone a lot of work. + mess with multiple version of the mesa + library. With the ldd-based system, every + package that uses mesa needs to add a + dependency on svgalib|svgalib-dummy in order + to handle the glide mesa variant. With an + objdump-based system this isn't necessary + anymore and would have saved everyone a lot of work.

- Another example: we could update libimlib with a new - version that supports a new graphics format called - dgf. If we use the old ldd method every package that - uses libimlib would need to be recompiled so it would - also depend on libdgf or it wouldn't run due to - missing symbols. However with the new system packages - using libimlib can depend on libimlib itself having - the dependency on libgdh and wouldn't need to be - updated. + Another example: we could update libimlib + with a new version that supports a new graphics format + called dgf. If we use the old ldd method, + every package that uses libimlib would need + to be recompiled so it would also depend on + libdgf or it wouldn't run due to missing + symbols. However with the new system, packages using + libimlib can rely on libimlib itself + having the dependency on libdgf and wouldn't + need to be updated.

- - used by the compiled binaries (and libraries, in a version - of dpkg-shlibdeps coming soon) passed through + + used by the compiled binaries and libraries passed through on its command line.

-

- For each shared library, dpkg-shlibdeps needs to know +

+ For each shared library linked to, + dpkg-shlibdeps needs to know

the package containing the library, and

the library version number,

 - -

- it scans the following files in this order. + + and it scans the following files in this order:

debian/shlibs.local

/etc/dpkg/shlibs.override

/var/lib/dpkg/info/*.shlibs

/etc/dpkg/shlibs.default

 -

+ +

- + Who maintains the various shlibs files? -

+

/etc/dpkg/shlibs.default - the maintainer @@ -3640,8 +3659,8 @@

debian/shlibs.local - the maintainer of the package

- - + + The shlibs.default file is managed by dpkg. The entries in shlibs.default that are provided by dpkg are just there to @@ -3651,14 +3670,14 @@ How to use dpkg-shlibdeps and - the shlibs files? + the shlibs files - + If your package doesn't provide a shared library -

+

Put a call to dpkg-shlibdeps into your debian/rules file. If your package contains only binaries (e.g. no scripts) use: @@ -3673,9 +3692,9 @@ If your package provides a shared library -

+

Create a debian/shlibs file and let - debian/rules install it in the control area: + debian/rules install it in the control area: install -m644 debian/shlibs debian/tmp/DEBIAN @@ -3688,33 +3707,33 @@ debian/shlibs.local -

+

This file is intended only as a temporary fix if your binaries depend on a library which doesn't provide its own /var/lib/dpkg/info/*.shlibs file yet.

-

+

Let's assume you are packaging a binary foo. Your - output in building the package might look like this. + output in building the package might look like this. $ ldd foo - libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 - libc.so.5 => /lib/libc.so.5.2.18 - libX11.so.6 => /usr/X11R6/lib/libX11.so.6.0 + libbar.so.1 => /usr/X11R6/lib/libbar.so.1.0 (0x4001e000) + libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x4002c000) + libc.so.6 => /lib/libc.so.6 (0x40114000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) And when you ran dpkg-shlibdeps - $ dpkg-shlibdeps -o foo - dpkg-shlibdeps: warning: unable to find dependency information - for shared library libbar + $ dpkg-shlibdeps -O foo + dpkg-shlibdeps: warning: unable to find dependency information for shared library libbar (soname 1, path /usr/X11R6/lib/libbar.so.1.0, dependency field Depends) - shlibs:Depends=elf-x11r6lib, libc5 (>= 5.2.18) + shlibs:Depends=libc6 (>= 2.2.1), xlibs (>= 4.0.1-11) The foo binary depends on the libbar shared library, but no package seems to provide a *.shlibs file in - var/lib/dpkg/info/. Let's determine the package + /var/lib/dpkg/info/. Let's determine the package responsible:

@@ -3741,17 +3760,17 @@ - + The Operating System - - + + File system hierarchy - - + + Linux File system Structure - +

The location of all installed files and directories must comply with the Linux File system Hierarchy Standard @@ -3762,33 +3781,33 @@ asked on debian-devel, or referred to Daniel Quinlan, the FHS coordinator, at quinlan@pathname.com.

 - - + + Site-specific programs - +

As mandated by the FHS, packages must not place any files in /usr/local, either by putting them in the file system archive to be unpacked by dpkg or by manipulating them in their maintainer scripts.

- +

However, the package may create empty directories below /usr/local so that the system administrator knows where to place site-specific files. These directories should be removed on package removal if they are empty.

- +

Note, that this applies only to directories below /usr/local, not in - /usr/local. Packages must not create sub-directories + /usr/local. Packages must not create sub-directories in the directory /usr/local itself, except those listed in FHS, section 4.5. However, you may create directories below them as you wish. You must not remove any of the directories listed in 4.5, even if you created them.

- +

Since /usr/local can be mounted read-only from a remote server, these directories must be created and @@ -3800,7 +3819,7 @@ included in the .deb packages and system administrators who do not wish these directories in /usr/local do not need to have them.)

- +

For example, the emacs package will contain @@ -3812,7 +3831,7 @@ rmdir /usr/local/lib/emacs || true in the prerm script.

- +

If you do create a directory in /usr/local for local additions to a package, you should ensure that @@ -3824,7 +3843,7 @@ exclusive use of the local administrator, a package must not rely on the presence or absence of files or directories in '/usr/local' for normal operation.

- +

The /usr/local directory itself and all the subdirectories created by the package should (by default) have @@ -3832,14 +3851,14 @@ owned by root.staff.

 - + Users and groups - +

The Debian system can be configured to use either plain or shadow passwords.

- +

Some user ids (UIDs) and group ids (GIDs) are reserved globally for use by certain packages. Because some packages @@ -3850,17 +3869,17 @@ we should avoid getting in the way of local administration policies. In particular, many sites allocate users and/or local system groups starting at 100.

- +

Apart from this we should have dynamically allocated ids, which should by default be arranged in some sensible order--but the behavior should be configurable.

- +

Packages other than base-passwd must not modify /etc/passwd, /etc/shadow, /etc/group or /etc/gshadow.

- +

The UID and GID ranges are as follows: @@ -3873,14 +3892,14 @@ Debian systems, new ids in this range being added automatically as the base-passwd package is updated.

- +

Packages which need a single statically allocated uid or gid should use one of these; their maintainers should ask the base-passwd maintainer for ids.

- + 100-999:

@@ -3892,8 +3911,8 @@ will check for the existence of the user or group, and if necessary choose an unused id based on the ranges specified in adduser.conf.

 - - + + 1000-29999:

@@ -3903,12 +3922,12 @@ adduser.conf may be used to modify this behavior.

 - + 30000-59999:

Reserved.

 - - + + 60000-64999:

@@ -3916,7 +3935,7 @@ created on demand. The ids are allocated centrally and statically, but the actual accounts are only created on users' systems on demand.

- +

These ids are for packages which are obscure or which require many statically-allocated ids. These packages @@ -3927,19 +3946,19 @@ further allocations should have a `hole' left after them in the allocation, to give them room to grow.

 - - + + 65000-65533:

Reserved.

 - - + + 65534:

User `nobody.' The corresponding gid refers to the group `nogroup.'

 - - + + 65535:

@@ -3951,11 +3970,11 @@ System run levels - - + + Introduction - +

The /etc/init.d directory contains the scripts executed by init at boot time and when init @@ -3983,7 +4002,7 @@ directory /etc/rcn.d for the scripts it should execute, where n is the runlevel that is being changed to, or `S' for the boot-up scripts.

- +

The names of the links all have the form Smmscript or @@ -3991,7 +4010,7 @@ mm is a two-digit number and script is the name of the script (this should be the same as the name of the actual script in /etc/init.d.

- +

When init changes runlevel first the targets of the links whose names starting with a K are @@ -4001,7 +4020,7 @@ links are responsible for killing services and the S link for starting services upon entering the runlevel.

- +

For example, if we are changing from runlevel 2 to runlevel 3, init will first execute all of the K @@ -4010,7 +4029,7 @@ starting with K will cause the referred-to file to be executed with an argument of stop, and the S links with an argument of start.

- +

The two-digit number mm is used to decide which order to start and stop things in--low-numbered links have @@ -4029,10 +4048,10 @@

- + Writing the scripts - +

Packages that include daemons for system services should place scripts in /etc/init.d to start or stop @@ -4040,32 +4059,32 @@ These scripts should be named /etc/init.d/package, and they should accept one argument, saying what to do: - + start

start the service,

- + stop

stop the service,

 - + restart

stop and restart the service,

 - + reload

cause the configuration of the service to be reloaded without actually stopping and restarting the service,

 - + force-reload

cause the configuration to be reloaded if the service supports this, otherwise restart the service.

 - + The start, stop, restart, and force-reload options should be supported by all scripts in /etc/init.d, the reload option is optional.

- +

The init.d scripts should ensure that they will behave sensibly if invoked with start when the @@ -4073,14 +4092,14 @@ isn't, and that they don't kill unfortunately-named user processes. The best way to achieve this is usually to use start-stop-daemon.

- +

If a service reloads its configuration automatically (as in the case of cron, for example), the reload option of the init.d script should behave as if the configuration has been reloaded successfully.

- +

These scripts should not fail obscurely when the configuration files remain but the package has been @@ -4124,10 +4143,10 @@

- + Managing the links - +

The program update-rc.d is provided to make it easier for package maintainers to arrange for the @@ -4136,7 +4155,7 @@ functional equivalent if another method is being used. This may be used by maintainers in their packages' postinst and postrm scripts.

- +

You must use this script to make changes to /etc/rcn.d and never either @@ -4145,7 +4164,7 @@ symbolic links in maintainer scripts. (The latter will fail if an alternative method of maintaining runlevel information is being used.)

- +

By default update-rc.d will start services in each of the multi-user state runlevels (2, 3, 4, and 5) @@ -4157,7 +4176,7 @@ /etc/rcn.d if symbolic links are being used, or by modifying /etc/runlevel.conf if the file-rc method is being used.

- +

To get the default behavior for your package, put in your postinst script @@ -4170,7 +4189,7 @@ update-rc.d package remove >/dev/null fi

- +

This will use a default sequence number of 20. If it does not matter when or in which order the script is run, use @@ -4178,16 +4197,16 @@ maintainer of the sysvinit package or post to debian-devel, and they will help you choose a number.

- +

For more information about using update-rc.d, please consult its manpage .

 - - + + Boot-time initialization - +

There used to be another directory, /etc/rc.boot, which contained scripts which were run once per machine @@ -4198,14 +4217,14 @@ Notes - +

Do not include the /etc/rcn.d/* symbolic links in the .deb file system archive! This will cause problems! You must create them with update-rc.d, as above.

- +

Do not include the /etc/rcn.d/* symbolic links in @@ -4222,10 +4241,10 @@ service--while making sure her changes aren't lost during the next package upgrade.)

 - + Example - +

The bind DNS (nameserver) package wants to make sure that the nameserver is running in multiuser @@ -4240,14 +4259,14 @@ be used to pass parameters to the named program at startup.

- +

#!/bin/sh # # Original version by Robert Leslie # <rob@mars.org>, edited by iwj and cs - + test -x /usr/sbin/named || exit 0 # Source defaults file. @@ -4255,8 +4274,8 @@ if [ -f /etc/default/bind ]; then . /etc/default/bind fi - - + + case "$1" in start) echo -n "Starting domain name service: named" @@ -4289,7 +4308,7 @@ exit 1 ;; esac - + exit 0

@@ -4310,7 +4329,7 @@

Another example on which to base your /etc/init.d scripts is in /etc/init.d/skeleton.

- +

If this package is happy with the default setup from update-rc.d, namely an ordering number of 20 @@ -4320,25 +4339,25 @@ update-rc.d bind defaults >/dev/null And in its postrm, to remove the links when the - package is purged: + package is purged: if [ purge = "$1" ]; then update-rc.d bind remove >/dev/null fi

- + Cron jobs - +

Packages must not modify the configuration file /etc/crontab, and they must not modify the files in /var/spool/cron/crontabs.

- +

If a package wants to install a job that has to be executed - via cron, it should place a file with the name if the + via cron, it should place a file with the name of the package in one of the following directories: /etc/cron.daily @@ -4378,33 +4397,33 @@ Console messages - +

This section describes different formats for messages written to standard output by the /etc/init.d scripts. The intent is to improve the consistency of Debian's startup and shutdown look and feel.

- +

Please look very careful at the details. We want to get the messages to look exactly the same way concerning spaces, punctuation, and case of letters.

- +

Here is a list of overall rules that you should use when you create output messages. They can be useful if you have a non-standard message that isn't covered in the sections below.

- +

Every message should cover one line, start with a capital letter and end with a period `.'.

- - - + + +

If you want to express that the computer is working on something (performing a specific task, not starting or @@ -4412,8 +4431,8 @@ three dots `...'. Note that we don't insert spaces in front of or behind the dots. If the task has been completed we write `done.' and a line feed.

 - - + +

Design your messages as if the computer is telling you @@ -4428,15 +4447,15 @@ Starting network daemons: nfsd mountd.

- +

The following formats should be used

- +

when daemons get started.

- +

Use this format if your script starts one or more daemons. The output should look like this (a single @@ -4449,13 +4468,13 @@ <daemon-1> up to <daemon-n> denote each daemon's name (typically the file name of the program).

- +

For example, the output of /etc/init.d/lpd would look like: Starting printer spooler: lpd.

- +

This can be achieved by saying @@ -4479,45 +4498,45 @@ comment out a line if he don't wants to start a specific daemon, while the displayed message still looks good.

 - - + +

when something needs to be configured.

- +

If you have to set up different parameters of the system upon boot up, you should use this format: Setting <parameter> to `<value>'.

- +

You can use the following echo statement to get the quotes right: echo "Setting DNS domainname to \`"value"'."

- +

Note that the left quotation mark (`) is different - from the right (').

 - + from the right (').

+

when a daemon is stopped.

- +

When you stop a daemon you should issue a message similar to the startup message, except that `Starting' is replaced with `Stopping'.

- +

So stopping the printer daemon will like like this: Stopping printer spooler: lpd.

- +

when something is executed.

- +

There are several examples where you have to run a program at system startup or shutdown to perform a @@ -4536,28 +4555,28 @@ echo "done." in your script.

 - +

when the configuration is reloaded.

- +

When a daemon is forced to reload its configuration files you should use the following format: Reloading <daemon's-name> configuration...done.

- +

when none of the above rules apply.

- +

If you have to print a message that doesn't fit into the styles described above, you can use something appropriate, but please have a look at the overall rules listed above.

- - + + Menus @@ -4575,7 +4594,7 @@ documents, and menu programs (either X window managers or text-based menu programs as pdmenu).

- +

All packages that provide applications that need not be passed any special command line arguments for normal @@ -4583,18 +4602,18 @@ applications, so that users of the menu package will automatically get menu entries in their window managers, as well in shells like pdmenu.

- +

Please refer to the Debian Menu System document that comes with the menu package for information about how to register your applications and web documents.

 - - + + Multimedia handlers - +

Packages which provide the ability to view/show/play, compose, edit or print MIME types should register themselves @@ -4602,7 +4621,7 @@ in the file found on ftp.debian.org in /debian/doc/package-developer/mime-policy.text.gz or your local mirror. In addition, it is included in the - debian-policy package. + debian-policy package.

@@ -4611,7 +4630,7 @@ meta-information about them, in particular their type (e.g. audio or video) and format (e.g. PNG, HTML, MP3).

- +

Registration of MIME type handlers allows programs like mail user agents and web browsers to to invoke these handlers to @@ -4622,42 +4641,42 @@ Keyboard configuration - +

To achieve a consistent keyboard configuration (i.e., all applications interpret a keyboard event the same way) all programs in the Debian distribution must be configured to comply with the following guidelines.

- +

Here is a list that contains certain keys and their interpretation: - + <--

delete the character to the left of the cursor

- + Delete

delete the character to the right of the cursor

 - + Control+H

emacs: the help prefix

 - + The interpretation of any keyboard events should be independent of the terminal that's used, be it a virtual console, an X terminal emulator, an rlogin/telnet session, etc.

- +

The following list explains how the different programs should be set up to achieve this:

- +

`<--' generates KB_Backspace in - X.

- + X.

+

`Delete' generates KB_Delete in X.

 - +

X translations are set up to make KB_Backspace @@ -4668,42 +4687,42 @@ displays, not using the application defaults, so that the translation resources used correspond to the xmodmap settings.

 - +

The Linux console is configured to make `<--' generate DEL, and `Delete' generate ESC [ 3 ~ (this is the case at the moment).

 - +

X applications are configured so that Backspace deletes left, and Delete deletes right. Motif applications already work like this.

 - +

stty erase ^? .

 - +

The `xterm' terminfo entry should have ESC [ 3 ~ for kdch1, just like TERM=linux and TERM=vt220.

 - +

Emacs is programmed to map KB_Backspace or the `stty erase' character to delete-backward-char, and KB_Delete or kdch1 to delete-forward-char, and ^H to help as always.

 - +

Other applications use the `stty erase' character and kdch1 for the two delete keys, with ASCII DEL being `delete previous character' and kdch1 being `delete character under cursor'.

- +

This will solve the problem except for:

- +

@@ -4714,7 +4733,7 @@ takes precedence in Emacs, and has been set correctly). M-x help or F1 (if available) can be used instead.

- +

Some operating systems use ^H for stty erase. However, modern telnet versions and all rlogin @@ -4722,7 +4741,7 @@ versions honour stty erase. Where the stty settings are not propagated correctly things can be made to work by using stty manually.

 - +

Some systems (including previous Debian versions) use xmodmap to arrange for both <-- and Delete @@ -4733,7 +4752,7 @@ other way around. On displays configured like this Delete will not work, but <-- will.

 - +

Some operating systems have different kdch1 settings in their terminfo for xterm and others. On these @@ -4743,18 +4762,18 @@

- - + + Environment variables - +

A program must not depend on environment variables to get reasonable defaults. (That's because these environment variables would have to be set in a system-wide configuration file like /etc/profile, which is not supported by all shells.)

- +

If a program usually depends on environment variables for its configuration, the program should be changed to fall back to @@ -4764,17 +4783,17 @@ available), the program must be replaced by a small `wrapper' shell script which sets the environment variables if they are not already defined, and calls the original program.

- +

Here is an example of a wrapper script for this purpose: - + #!/bin/sh BAR=${BAR:-/var/lib/fubar} export BAR exec /usr/lib/foo/foo "$@"

- +

Furthermore, as /etc/profile is a configuration file of the base-files package, other packages must not @@ -4784,11 +4803,11 @@ Files - - + + Binaries - +

Two different packages must not install programs with different functionality but with the same filenames. (The @@ -4800,16 +4819,16 @@ which package will have to be renamed. If a consensus can not be reached, both programs must be renamed.

- +

Generally the following compilation parameters should be used: - CC = gcc - CFLAGS = -O2 -Wall # sane warning options vary between programs - LDFLAGS = # none + CC = gcc + CFLAGS = -O2 -Wall # sane warning options vary between programs + LDFLAGS = # none install -s # (or use strip on the files in debian/tmp)

- +

Note that by default all installed binaries should be stripped, either by using the -s flag to @@ -4817,12 +4836,12 @@ the binaries after they have been copied into debian/tmp but before the tree is made into a package.

- +

The -N flag should not be used. On a.out systems it may have been useful for some very small binaries, but for ELF it has no good effect.

- +

Debugging symbols are useful for error diagnosis, investigation of core dumps (which may be submitted by users @@ -4866,7 +4885,7 @@ autobuilders since not having debugging information (and hence also not having to strip it) will increase the speed of compiles. This - skips an entire pass of the compiler. + skips an entire pass of the compiler.

@@ -4907,41 +4926,41 @@ the upstream author's ideas about which compilation options are best--they are often inappropriate for our environment.

 - - + + Libraries - +

All libraries must have a shared version in the lib package and a static version in the lib-dev package. The shared version must be compiled with -fPIC, and the static version must not be. In other words, each *.c file will need to be compiled twice.

- +

You must specify the gcc option -D_REENTRANT when building a library (either static or shared) to make the library compatible with LinuxThreads.

- +

Note that all installed shared libraries should be stripped with strip --strip-unneeded <your-lib> - + (The option `--strip-unneeded' makes strip remove only the symbols which aren't needed for relocation processing.) Shared libraries can function perfectly well when stripped, since the symbols for dynamic linking are in a separate part of the ELF object file.

- +

Note that under some circumstances it may be useful to install a shared library unstripped, for example when building a separate package to support debugging.

- +

An ever increasing number of packages are using libtool to do their linking. The latest GNU libtools (>= 1.3a) can take @@ -4976,7 +4995,7 @@ good idea in general, and especially for static linking issues.

- +

You must make sure that you use only released versions of shared libraries to build your packages; otherwise other @@ -4986,15 +5005,15 @@ idea.

- - + + Shared libraries - +

Packages involving shared libraries should be split up into several binary packages.

- +

For a straightforward library which has a development environment and a runtime kit including just shared @@ -5006,7 +5025,7 @@ linker to be able run the program; usually the soname is the major number of the library) and librarynamesoname-dev.

- +

If you prefer only to support one development version at a time you may name the development package @@ -5019,7 +5038,7 @@ development version should also have an exact version dependency on the runtime library, to make sure that compilation and linking happens correctly.

- +

Packages which use the shared library should have a dependency on the name of the shared library package, @@ -5027,7 +5046,7 @@ the soname changes you can have both versions of the library installed while moving from the old library to the new.

- +

If your package has some run-time support programs which use the shared library you must not put them in @@ -5039,7 +5058,7 @@ libraryname-runtime--note the absence of the soname in the package name) or if the development package is small include them in there.

- +

If you have several shared libraries built from the same source tree you may lump them all together into a single @@ -5047,45 +5066,45 @@ sonames at once (so that you don't get filename clashes if you try to install different versions of the combined shared libraries package).

- +

You should follow the directions in the Debian Packaging Manual for putting the shared library in its package, and you must include a shlibs control area file with details of the dependencies for packages which use the library.

- +

Shared libraries should not be installed executable, since ld.so does not require this and trying to execute a shared library results in a core dump.

 - - + + Scripts - +

All command scripts, including the package maintainer scripts inside the package and used by dpkg, 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.

- +

Shell scripts (sh and bash) should almost certainly start with set -e so that errors are detected. Every script should use set -e or check the exit status of every command.

- +

The standard shell interpreter `/bin/sh' can be a symbolic link to any POSIX compatible shell, if echo - -n does not generate a newline. + -n does not generate a newline.

Debian policy specifies POSIX behavior for /bin/sh, but @@ -5107,60 +5126,60 @@ marked `Essential', e.g., in the case of bash).

- +

You may wish to restrict your script to POSIX features when possible so that it may use /bin/sh as its interpreter. If your script works with ash, it's probably POSIX compliant, but if you are in doubt, use /bin/bash.

- +

Perl scripts should check for errors when making any system calls, including open, print, close, rename and system.

- +

csh and tcsh should be avoided as scripting languages. See Csh Programming Considered Harmful, one of the comp.unix.* - FAQs. It can be found on + FAQs. It can be found on , or - or even on ftp.cpan.org + or even on ftp.cpan.org /pub/perl/CPAN/doc/FMTEYEWTK/versus/csh.whynot. If an upstream package comes with csh scripts then you must make sure that they start with #!/bin/csh and make your package depend on the c-shell virtual package.

- +

Any scripts which create files in world-writeable directories (e.g., in /tmp) must use a mechanism which will fail if a file with the same name already exists.

- +

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

- - + + Symbolic links - +

In general, symbolic links within a top-level directory should be relative, and symbolic links pointing from one top-level directory into another should be absolute. (A top-level directory is a sub-directory of the root directory `/'.)

- +

In addition, symbolic links should be specified as short as possible, i.e., link targets like `foo/../bar' are deprecated.

- +

Note that when creating a relative link using ln it is not necessary for the target of the @@ -5171,17 +5190,17 @@ target of the link (this will be a pathname relative to the directory in which the link resides) as the first argument to ln.

- +

For example, in your Makefile or debian/rules, do things like: - ln -fs gcc $(prefix)/bin/cc - ln -fs gcc debian/tmp/usr/bin/cc - ln -fs ../sbin/sendmail $(prefix)/bin/runq + ln -fs gcc $(prefix)/bin/cc + ln -fs gcc debian/tmp/usr/bin/cc + ln -fs ../sbin/sendmail $(prefix)/bin/runq ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

- +

A symbolic link pointing to a compressed file should always have the same file extension as the referenced @@ -5189,33 +5208,33 @@ referenced by a symbolic link, the filename of the link has to end with `.gz' too, as in `bar.gz.')

 - - + + Device files - +

Packages must not include device files in the package file tree.

- +

If a package needs any special device files that are not included in the base system, it must call MAKEDEV in the postinst script, after asking the user for permission to do so.

- +

Packages must not remove any device files in the postrm or any other script. This is left to the system administrator.

- +

Debian uses the serial devices /dev/ttyS*. Programs using the old /dev/cu* devices should be changed to use /dev/ttyS*.

 - + Configuration files @@ -5462,7 +5481,7 @@ is installed.

 - + Log files

@@ -5472,7 +5491,7 @@ requires quite a lot of sysadmin work. Even though the original Debian system helped a little by automatically installing a system which can be used as a template, this - was deemed not enough. + was deemed not enough.

@@ -5480,7 +5499,7 @@ developed by Red Hat, which centralizes log management. It has both a configuration file (/etc/logrotate.conf) and a directory where packages can drop logrotation info - (/etc/logrotate.d). + (/etc/logrotate.d).

@@ -5490,7 +5509,7 @@ reasons (/var/log is writable only by root), you should usually create a directory named /var/log/package.

- +

Log files must be rotated occasionally so that they don't grow indefinitely; the best way to do this @@ -5508,24 +5527,24 @@ /etc/init.d/foo force-reload endscript } - + Which rotates all files under `/var/log/foo', saves 12 compressed generations, and sends a HUP signal at the end of rotation.

- +

Log files should be removed when the package is purged (but not when it is only removed), by checking the argument to the postrm script (see the Debian Packaging Manual for details).

 - - + + Permissions and owners - +

The rules in this section are guidelines for general use. If necessary you may deviate from the details below. @@ -5533,19 +5552,19 @@ is secure and you should try to be as consistent as possible with the rest of the system. You should probably also discuss it on debian-devel first.

- +

Files should be owned by root.root, and made writable only by the owner and universally readable (and executable, if appropriate).

- +

Directories should be mode 755 or (for group-writability) mode 2775. The ownership of the directory should be consistent with its mode--if a directory is mode 2775, it should be owned by the group that needs write access to it.

- +

Setuid and setgid executables should be mode 4755 or 2755 respectively, and owned by the appropriate user or group. @@ -5555,7 +5574,7 @@ Debian package--it is merely inconvenient. For the same reason you should not restrict read or execute permissions on non-set-id executables.

- +

Some setuid programs need to be restricted to particular sets of users, using file permissions. In this case they @@ -5564,7 +5583,7 @@ They should have mode 4754; there is no point in making them unreadable to those users who must not be allowed to execute them.

- +

You must not arrange that the system administrator can only reconfigure the package to correspond to their local @@ -5576,7 +5595,7 @@ example) creating a group for people allowed to use the program(s) and making any setuid executables executable only by that group.

- +

If you need to create a new user or group for your package there are two possibilities. Firstly, you may need to @@ -5585,7 +5604,7 @@ group id (rather than just the name) into the binary (though this latter should be avoided if possible, as in this case you need a statically allocated id).

- +

If you need a statically allocated id, you must ask for a user or group id from the base system @@ -5598,7 +5617,7 @@ correct id (using adduser) in its pre- or post-installation script (the latter is to be preferred if it is possible).

- +

On the other hand, the program might be able to determine the uid or gid from the group name at runtime, so that a @@ -5612,7 +5631,7 @@ adduser in the pre- or post-installation script (again, the latter is to be preferred if it is possible).

- +

Note that changing the numeric value of an id associated with a name is very difficult, and involves searching the file system for all @@ -5624,10 +5643,10 @@ Customized programs - + Architecture specification strings - +

If a program needs to specify an architecture specification string in some place, the following format should be used: @@ -5637,7 +5656,7 @@ where `<arch>' is one of the following: i386, alpha, arm, m68k, powerpc, sparc and `<os>' is one of: linux, gnu. Use of gnu in this string is reserved for the GNU/Hurd - operating system.

+ operating system.

Note, that we don't want to use `<arch>-debian-linux' to apply to the rule `architecture-vendor-os' since this @@ -5645,30 +5664,30 @@ distributions. Also note, that we don't use `<arch>-unknown-linux', since the `unknown' does not look very good.

 - - + + Daemons - +

The configuration files /etc/services, /etc/protocols, and /etc/rpc are managed by the netbase package and may not be modified by other packages.

- +

If a package requires a new entry in one of these files, the maintainer should get in contact with the netbase maintainer, who will add the entries and release a new version of the netbase package.

- +

The configuration file /etc/inetd.conf must not be modified by the package's scripts except via the update-inetd script or the DebianNet.pm Perl module.

- +

If a package wants to install an example entry into /etc/inetd.conf, the entry must be preceded with @@ -5676,18 +5695,18 @@ treated as `commented out by user' by the update-inetd script and are not changed or activated during a package updates.

 - - + + Using pseudo-ttys and modifying wtmp, utmp and lastlog - +

Some programs need to create pseudo-ttys. This should be done using Unix98 ptys if the C library supports it. The resulting program must not be installed setuid root, unless that is required for other functionality.

- +

The files /var/run/utmp, /var/log/wtmp and /var/log/lastlog must be installed writeable by @@ -5698,7 +5717,7 @@ Editors and pagers - +

Some programs have the ability to launch an editor or pager program to edit or display a text document. Since there are @@ -5706,25 +5725,25 @@ distribution, the system administrator and each user should have the possibility to choose his/her preferred editor and pager.

- +

In addition, every program should choose a good default editor/pager if none is selected by the user or system administrator.

- +

Thus, every program that launches an editor or pager must use the EDITOR or PAGER environment variables to determine the editor/pager the user wants to get started. If these variables are not set, the programs /usr/bin/editor and /usr/bin/pager should be used, respectively.

- +

These two files are managed through `alternatives.' That is, every package providing an editor or pager must call the update-alternatives script to register these programs.

- +

If it is very hard to adapt a program to make us of the EDITOR and PAGER variables, that program may be configured @@ -5735,7 +5754,7 @@ launch the appropriate program or fall back to /usr/bin/editor and /usr/bin/pager, automatically.

- +

A program may also use the VISUAL environment variable to determine the user's choice of editor. If it exists, it @@ -5749,22 +5768,22 @@

The Debian base system already provides an editor and - a pager program, + a pager program,

- - + + Web servers and applications - +

This section describes the locations and URLs that should be used by all web servers and web application in the Debian system.

- +

@@ -5777,10 +5796,10 @@ http://localhost/cgi-bin/<cgi-bin-name>

- - + +

Access to html documents

- +

Html documents for a package are stored in /usr/share/doc/package but should @@ -5791,10 +5810,10 @@ http://localhost/doc/<package>/<filename>

- - + +

Web Document Root

- +

Web Applications should try to avoid storing files in the Web Document Root. Instead they should use the @@ -5803,18 +5822,18 @@ access to the web-root is unavoidable then use /var/www - + as the Document Root. This might be just a symbolic link to the location where the sysadmin has put the real document root.

 - +

- - + + Mail transport, delivery and user agents - +

Debian packages which process electronic mail, whether mail-user-agents (MUAs) or mail-transport-agents (MTAs), @@ -5822,13 +5841,13 @@ configuration decisions below. Failure to do this may result in lost mail, broken From: lines, and other serious brain damage!

- +

The mail spool is /var/spool/mail and the interface to send a mail message is /usr/sbin/sendmail (as per the FHS). The mail spool is part of the base system and not part of the MTA package.

- +

All Debian MUAs, MTAs, MDAs and other mailbox accessing programs (like IMAP daemons) must lock the mailbox in an @@ -5849,20 +5868,20 @@ liblockfile version >>1.01

packages is the recommended way to realize this.

- +

Mailboxes are generally 660 user.mail unless the user has chosen otherwise. A MUA may remove a mailbox (unless it has nonstandard permissions) in which case the MTA or another MUA must recreate it if needed. Mailboxes must be writable by group mail.

- +

The mail spool is 2775 root.mail, and MUAs should be setgid mail to do the locking mentioned above (and must obviously avoid accessing other users' mailboxes using this privilege).

- +

/etc/aliases is the source file for the system mail aliases (e.g., postmaster, usenet, etc.)--it is the one @@ -5873,19 +5892,19 @@ even if it does nothing, but older MTA packages do not do this so programs should not fail if newaliases cannot be found.

- +

The convention of writing forward to address in the mailbox itself is not supported. Use a .forward file instead.

- +

The rmail program used by UUCP for incoming mail should be /usr/sbin/rmail. - Likewise, rsmtp, for receiving + Likewise, rsmtp, for receiving batch-SMTP-over-UUCP, should be /usr/sbin/rsmtp if it is supported.

- +

If you need to know what name to use (for example) on outgoing news and mail messages which are generated locally, @@ -5893,7 +5912,7 @@ contain the portion after the username and @ (at) sign for email addresses of users on the machine (followed by a newline).

- +

A package should check for the existence of this file. If it exists it should use it without comment. (An MTA's @@ -5912,41 +5931,41 @@ name [`syshostname']: where syshostname is the output of hostname - --fqdn.

 - - + --fqdn.

+ + News system configuration - +

All the configuration files related to the NNTP (news) servers and clients should be located under /etc/news.

- +

There are some configuration issues that apply to a number of news clients and server packages on the machine. These are: - + /etc/news/organization

A string which should appear as the organization header for all messages posted by NNTP clients on the machine

- + /etc/news/server

Contains the FQDN of the upstream NNTP server, or localhost if the local machine is an NNTP server.

 - - Other global files may be added as required for cross-package news + + Other global files may be added as required for cross-package news configuration.

 - - + + Programs for the X Window System - +

Programs that may be configured with support for the X Window System must be configured to do so and must declare any @@ -5957,8 +5976,8 @@ alternative versions of the package with X support may be provided.

- - + +

Packages which provide an X server that, directly or indirectly, communicates with real input and display hardware @@ -6150,7 +6169,7 @@

- +

Application defaults files must be installed in the directory /usr/X11R6/lib/X11/app-defaults/. @@ -6178,7 +6197,7 @@

- +

Packages using the X Window System should abide by the FHS standard whenever possible; they should install binaries, @@ -6235,28 +6254,28 @@ his or her possession.

- - + + Emacs lisp programs - +

Please refer to the `Debian Emacs Policy' (documented in debian-emacs-policy.gz of the emacsen-common package) for details of how to package emacs lisp programs.

 - - + + Games - +

The permissions on /var/games are 755 root.root.

- +

Each game decides on its own security policy.

- +

Games which require protected, privileged access to high-score files, savegames, etc., may be made @@ -6272,7 +6291,7 @@ important game data, and if they can get at the other players' accounts at all it will take considerably more effort.)

- +

Some packages, for example some fortune cookie programs, are configured by the upstream authors to install with their @@ -6284,7 +6303,7 @@ making the files unreadable also means that you don't have to make so many programs set-id, which reduces the risk of a security hole.

- +

As described in the FHS, binaries of games should be installed in the directory /usr/games. This also @@ -6293,27 +6312,27 @@ /usr/share/man/man6.

 - + Documentation - - + + Manual pages - +

You should install manual pages in nroff source form, in appropriate places under /usr/share/man. You should only use sections 1 to 9 (see the FHS for more details). You must not install a preformatted `cat page'.

- +

Each program, utility, and function should have an associated manpage included in the same package. It is suggested that all configuration files also have a manual page included as well.

- +

If no manual page is available for a particular program, utility, function or configuration file and this is reported as a bug on @@ -6324,12 +6343,12 @@ ln -s ../man7/undocumented.7.gz \ debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz - + This manpage claims that the lack of a manpage has been reported as a bug, so you may only do this if it really has (you can report it yourself, if you like). Do not close the bug report until a proper manpage is available.

- +

You may forward a complaint about a missing manpage to the upstream authors, and mark the bug as forwarded in the @@ -6338,11 +6357,11 @@ we do--if they tell you that they don't consider it a bug you should leave the bug in our bug tracking system open anyway.

- +

Manual pages should be installed compressed using gzip -9.

- +

If one manpage needs to be accessible via several names it is better to use a symbolic link than the .so @@ -6354,15 +6373,15 @@ in a .so in a manpage should be relative to the base of the manpage tree (usually /usr/share/man).

 - - + + Info documents - +

Info documents should be installed in /usr/share/info. They should be compressed with gzip -9.

- +

Your package should call install-info to update the Info dir @@ -6371,7 +6390,7 @@ install-info --quiet --section Development Development \ /usr/share/info/foobar.info

- +

It is a good idea to specify a section for the location of your program; this is done with the --section @@ -6382,22 +6401,22 @@ flag takes two arguments; the first is a regular expression to match (case-insensitively) against an existing section, the second is used when creating a new one.

- +

You should remove the entries in the pre-removal script: install-info --quiet --remove /usr/share/info/foobar.info

- +

If install-info cannot find a description entry in the Info file you must supply one. See for details.

 - + Additional documentation - +

Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. @@ -6405,14 +6424,14 @@ /usr/share/doc/package, where package is the name of the package, and compressed with gzip -9 unless it is small.

- +

If a package comes with large amounts of documentation which many users of the package will not require you should create a separate binary package to contain it, so that it does not take up disk space on the machines of users who do not need or want it installed.

- +

It is often a good idea to put text information files (READMEs, changelogs, and so forth) that come with @@ -6427,12 +6446,12 @@ delete them without causing any programs to break. Any files that are referenced by programs but are also useful as standalone documentation should be installed under - /usr/share/<package$gt;/ and symlinked in - /usr/share/doc/<package$gt;/. + /usr/share/<package>/ and symlinked in + /usr/share/doc/<package>/.

- + Accessing the documentation @@ -6469,14 +6488,14 @@

- + Preferred documentation formats - +

The unification of Debian documentation is being carried out via HTML.

- +

If your package comes with extensive documentation in a mark up format that can be converted to various other formats @@ -6490,21 +6509,21 @@ necessarily in the main binary package, though.

- +

Other formats such as PostScript may be provided at your option.

 - + Copyright information - +

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/<package-name>/copyright. This file must neither be compressed nor be a symbolic link.

- +

In addition, the copyright file must say where the upstream sources (if any) were obtained, and should explain briefly what @@ -6517,8 +6536,8 @@ A copy of the file which will be installed in /usr/share/doc/package/copyright should be in debian/copyright.

- - + +

/usr/share/doc/<package-name> may be a symbolic link to a directory in /usr/share/doc only if two packages both come from @@ -6543,7 +6562,7 @@ for packages are no longer in a common directory. Once /usr/doc/copyright is almost empty it makes sense to rename "copyright" to "licenses" -

+

Why "common-licenses" and not "licenses"? Because if I put just "licenses" I'm sure I will receive a bug report @@ -6555,17 +6574,17 @@

- +

You should not use the copyright file as a general README file. If your package has such a file it should be installed in /usr/share/doc/package/README or README.Debian or some other appropriate place.

 - + Examples - +

Any examples (configurations, source files, whatever), should be installed in a directory @@ -6579,10 +6598,10 @@ to files in it. Or the latter directory may be a symlink to the former.

 - + Changelog files - +

Packages that are not Debian-native must contain a copy of debian/changelog file from the Debian source tree @@ -6606,14 +6625,14 @@

- - + +

All these files should be installed compressed using gzip -9, as they will become large with time even if they start out small.

- +

If the package has only one changelog which is used both as the Debian changelog and the upstream one because there is @@ -6624,12 +6643,6 @@ changelog, then the Debian changelog should still be called changelog.Debian.gz.

 - + - - - - - - diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 16baa1c..93073ed 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -1,9 +1,9 @@ - @@ -44,14 +44,19 @@ Manual.

The checklist

-3.5.0.0                    Jan 28
+3.5.1.0                    Feb 01
+  Policy Manual:
+     - dpkg-shlibdeps now uses objdump, so shared libraries have to be
+       run through dpkg-shlibdeps as well as executables
+
+3.5.0.0                    Jan 01
 
   Policy Manual:
      - If your package had fonts for the X Window System, and you
        converted BDF to PCF formats, the bdftopcf utility has
-       moved to the xutils package. 
+       moved to the xutils package.
      - Font packages for the X Window System must now declare a
-       dependency on xutils >= 4.0.2 
+       dependency on xutils >= 4.0.2
 
 3.2.1.1                    Jan 01
 
@@ -66,6 +71,8 @@ Manual.
        program. If such files are needed, they must be placed in
        /usr/share/package-name/, and symbolic links created as required
        in /usr/share/doc/package-name/
+     - Much of the packaging manual has now been imported into the
+       policy document
 
 3.2.1.0                    Aug 00
 
@@ -73,14 +80,13 @@ Manual.
      - A package of priority standard or higher may provide two
        binaries, one compiled with support for the X Window System,
        and the other without.
-     -
 
 3.2.0.0                    Aug 00
 
   Policy Manual:
      - By default executables should not be built with the debugging
        option -g. Instead, it is recommended to support building the
-       package with debugging information optionally. Please look at the 
+       package with debugging information optionally. Please look at the
        examples using  DEB_BUILD_OPTIONS in the policy manual.
      - Policy for packages where the upstream uses html changelog
        files has been expanded. In short, a plain text changelog file
@@ -101,13 +107,13 @@ Manual.
      - Policy for packages using the X Window System and FHS issues
        has been clarified. Please read the manual for details.
      - Policy for packages providing an X application default has been
-       clarified. 
+       clarified.
      - No package may contain or make hard links to conffiles.
 
   Packaging Manual:
      - Noted that newer dpkg versions do not require extreme care in
        always creating the shared lib before the symlink, so the unpack
-       order be correct. 
+       order be correct.
 
 3.1.1.0                    Nov 99
 
@@ -169,7 +175,7 @@ Manual.
       major change, and the implications of this move are probably
       not all known.
     - Only 3 digits of the Standards version need be included in
-      control files, though all four digits are still permitted. 
+      control files, though all four digits are still permitted.
     - The location of the GPL has changed to
       /usr/share/common-licenses. This may require changing the
       copyright files to point to the correct location of the GPL and
@@ -178,9 +184,9 @@ Manual.
       include the .la files in the -dev packages.
     - Use logrotate to rotate log files
     - section 5.8 has been rewritten (Programs for the X Window
-      System) 
+      System)
     - There is now anassociated menu policy, in a separate document,
-      that carries the full weight of Debian policy. 
+      that carries the full weight of Debian policy.
     - The files `/var/run/utmp', `/var/log/wtmp' and
       `/var/log/lastlog' must be installed writeable by group
       utmp. Programs who need to modify those files must be installed
@@ -199,11 +205,11 @@ Manual.
         "Configuration files", moving the Section 4.8 ("Permissions
         and owners") to Section 4.9.  All subsections of the old
         Section 5 after 5.5  were moved down to fill in the number
-        gap. 
+        gap.
     - Modified the section about changelog files to accommodate
       upstream changelogs which were formatted as HTML/ These
       upstream changelog files should now be accessible as
-      /usr/doc/package/changelog.html.gz 
+      /usr/doc/package/changelog.html.gz
       + Symlinks are permissible to link the real, or upstream,
         changelog name to the Debian mandated name.
     - Clarified that HTML documentation should be present in some
@@ -211,7 +217,7 @@ Manual.
     - Corrected all references to the location of the copyright
       files. The correct location is /usr/doc/package/copyright
     - Ratified the architecture specification strings to cater to the
-      HURD. 
+      HURD.
 
 2.4.1.0                         Apr 98
 
@@ -230,7 +236,7 @@ Manual.
       ldconfig must be called in the postinst script if the package
       installs shared libraries
       (cf., Policy Weekly Issue #6, fixes:bug#20515)
-  
+
 2.4.0.0                         Jan 98
 
     - Updated section 3.3.4 Scripts:
@@ -292,7 +298,7 @@ Manual.
 	  /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
 
 	* updated section about `Configuration files':
-	  packages may not touch other packages' configuration files  
+	  packages may not touch other packages' configuration files
 
 	* MUAs and MTAs have to use liblockfile
 
@@ -300,7 +306,7 @@ Manual.
 
 	* added section 4.1 `Architecture specification strings':
           use
-	       <arch>-linux 
+	       <arch>-linux
           where <arch> is one of the following:
                i386, alpha, arm, m68k, powerpc, sparc.
 
@@ -338,7 +344,7 @@ Manual.
 2.1.1.0				Sep 96
 
 	* No hard links in source packages
-	
+
 	* Do not use dpkg-divert or update-alternatives without consultation
 
 	* Shared libraries must be installed stripped
@@ -353,15 +359,6 @@ Manual.
   
 
 
-
-
-
-
-
-
-
-
-