X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=61167254fe98d535833b107fd4e3ef2b409ad5bf;hb=ca749fffb7f63d2a9ff72778104a5c60510da72c;hp=0c2470c36c16fb2c932e0efe2f90bd888bfc378d;hpb=9cb86abc7b37aab05866755f2e193a378dc13e25;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 0c2470c..6116725 100644 --- a/policy.sgml +++ b/policy.sgml @@ -4,41 +4,11 @@ %versiondata; ]> - Debian Policy Manual - - Ian Jackson - ijackson@gnu.ai.mit.edu - - - Christian Schwarz - schwarz@debian.org - - - revised: David A. Morris - bweaver@debian.org - - - The Debian Policy mailing List - debian-policy@lists.debian.org - + The Debian Policy Mailing List version &version;, &date; @@ -47,23 +17,11 @@ contents of the Debian archive and several design issues of the operating system, as well as technical requirements that each package must satisfy to be included in the distribution. - The policy package itself is maintained by a group of - maintainers that have no editorial powers. The current list - of maintainers is: - - -

Julian Gilbey jdg@debian.org

- - -

Manoj Srivastava srivasta@debian.org

- - - - Copyright ©1996,1997,1998 Ian Jackson + Copyright © 1996,1997,1998 Ian Jackson and Christian Schwarz.

@@ -83,17 +41,17 @@

A copy of the GNU General Public License is available as - /usr/share/common-licenses/GPL in the Debian GNU/Linux + /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the World Wide Web at . You can also + name="the GNU General Public Licence">. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

- + About this manual @@ -108,7 +66,6 @@ distribution.

-

This manual also describes Debian policy as it relates to creating Debian packages. It is not a tutorial on how to build @@ -157,9 +114,14 @@ merely informative, and are not part of Debian policy itself.

+

+ The appendices to this manual are not necessarily normative, + either. Please see for more information. +

- In this manual, the words must, should and + In the normative part of this manual, + the words must, should and may, and the adjectives required, recommended and optional, are used to distinguish the significance of the various guidelines in @@ -192,37 +154,66 @@ only.

+ New versions of this document +

- The current version of this document is always accessible - from the Debian FTP server ftp.debian.org - as - /debian/doc/package-developer/policy.txt.gz - (also available from the same directory are several other - formats: policy.html.tar.gz, policy.pdf.gz - and policy.ps.gz) or from the webpage.

+ This manual is distributed via the Debian package + debian-policy. +

- In addition, this manual is distributed via the Debian package - debian-policy. + The current version of this document is also available from + the Debian web mirrors at + + and from the Debian archive mirrors at + . + Also available from the same directory are several other + formats: policy.html.tar.gz, policy.pdf.gz + and policy.ps.gz.

- The debian-policy package also includes the file - upgrading-checklist.txt which indicates policy + The debian-policy package also includes the file + upgrading-checklist.txt which indicates policy changes between versions of this document.

- - Feedback + + + Authors and Maintainers

- As the Debian GNU/Linux system is continuously evolving this - manual does so too. -

+ Originally called "Debian GNU/Linux Policy Manual", this + manual was initially written in 1996 by Ian Jackson. + It was revised on November 27th, 1996 by David A. Morris. + Christian Schwarz added new sections on March 15th, 1997, + and reworked/restructured it in April-July 1997. + Christoph Lameter contributed the "Web Standard". + Julian Gilbey largely restructured it in 2001. +

+ +

+ Since September 1998, the responsibility for the contents of + this document lies on the . Proposals + are discussed there and inserted into policy after a certain + consensus is established. + + The actual editing is done by a group of maintainers that have + no editorial powers. These are the current maintainers: + + + Julian Gilbey + Branden Robinson + Josip Rodin + Manoj Srivastava + +

+

While the authors of this document have tried hard to avoid typos and other errors, these do still occur. If you discover @@ -232,6 +223,11 @@ debian-policy@lists.debian.org, or submit a bug report against the debian-policy package.

+ +

+ Please do not try to reach the individual authors or maintainers + of the Policy Manual regarding changes to the Policy. +

@@ -293,7 +289,7 @@ The Debian Free Software Guidelines

The Debian Free Software Guidelines (DFSG) form our - definition of `free software'. These are: + definition of "free software". These are: Free Redistribution @@ -330,7 +326,7 @@

The license may restrict source-code from being distributed in modified form only if the - license allows the distribution of ``patch files'' + license allows the distribution of "patch files" with the source code for the purpose of modifying the program at build time. The license must explicitly permit distribution of software built from modified @@ -399,8 +395,8 @@

- The ``GPL,'' ``BSD,'' and ``Artistic'' licenses are - examples of licenses that we consider free. + The "GPL," "BSD," and "Artistic" licenses are examples of + licenses that we consider free.

@@ -555,21 +551,20 @@ The non-US sections

- Some programs with cryptographic program code need to be - stored on the non-US server because of United - States export restrictions. Such programs must be - distributed in the appropriate non-US section, - either non-US/main, non-US/contrib or - non-US/non-free. + Non-free programs with cryptographic program code need to + be stored on the non-us server because of export + restrictions of the U.S. +

+

+ Programs which use patented algorithms that have a + restrictied license also need to be stored on "non-us", + since that is located in a country where it is not allowed + to patent algorithms.

- This applies only to packages which contain cryptographic - code. A package containing a program with an interface to - a cryptographic program or a program that's dynamically - linked against a cryptographic library should not be - distributed via the non-US server if it is - capable of running without the cryptographic library or - program. + A package depends on another package which is distributed + via the non-us server has to be stored on the non-us + server as well.

@@ -577,7 +572,7 @@

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

@@ -649,8 +644,8 @@ debian-legal@lists.debian.org. Be prepared to provide us with the copyright statement. Software covered by the GPL, public domain software and BSD-like - copyrights are safe; be wary of the phrases `commercial - use prohibited' and `distribution restricted'. + copyrights are safe; be wary of the phrases "commercial + use prohibited" and "distribution restricted".

@@ -741,8 +736,8 @@ Important programs, including those which one would expect to find on any Unix-like system. If the expectation is that an experienced Unix person who - found it missing would say `What on earth is going on, - where is foo?', it must be an + found it missing would say "What on earth is going on, + where is foo?", it must be an important package.

This is an important criterion because we are @@ -764,8 +759,7 @@ These packages provide a reasonably small but not too limited character-mode system. This is what will be installed by default if the user doesn't select anything - else. It doesn't include many large applications. - .

+ else. It doesn't include many large applications.

optional @@ -818,11 +812,11 @@ archive.

- Package names must consist of lower case letters + Package names must consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). - They must be at least two characters long and must contain - at least one letter. + They must be at least two characters long and must start + with an alphanumeric character.

@@ -892,6 +886,11 @@ statements and other administrivia should not be included either (that is what the copyright file is for).

+ +

+ Please refer to for more information. +

+ @@ -927,7 +926,7 @@ doing that has been reached.

- + Virtual packages

@@ -948,24 +947,31 @@ They should not use virtual package names (except privately, amongst a cooperating group of packages) unless they have been agreed upon and appear in the list of virtual package - names.

+ names. (See also )

The latest version of the authoritative list of virtual - package names can be found on - ftp.debian.org in - /debian/doc/package-developer/virtual-package-names-list.txt - 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.

 + package names can be found in the debian-policy package. + It's also available from the Debian web mirrors at + + and from the Debian archive mirrors at + . +

+

+ The procedure for updating the list is described in the preface + to the list. +

+ + - Base packages + Base system

- The packages included in the base section have a - special function. They form a minimum subset of the Debian + The base system is a minimum subset of the Debian GNU/Linux system that is installed before everything else on a new system. Thus, only very few packages are allowed to go into the base section to keep the required @@ -976,11 +982,8 @@ 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.

 + + @@ -1020,9 +1023,42 @@ reached.

+ + Tasks + +

+ The Debian install process allows the user to choose from + a number of common tasks which a Debian system can be used to + perform. Selecting a task with tasksel causes + a set of packages that are useful in performing that task to be + installed. +

+ +

+ This set of packages is all available packages which have the + name of the selected task in the Task field of their + control file. The format of this field is a list of tasks, + separated by commas. +

+ +

+ You should not tag any packages as belonging to a task + before this has been discussed on the + debian-devel mailing list and a consensus about + doing that has been reached. +

+ +

+ For third parties (and historical reasons), tasksel also + supports constructing tasks based on task + packages. These are packages whose names begin with + task-. Task packages should not be included in the + Debian archive. +

+ - Maintainer scripts + Maintainer Scripts

The package installation scripts should avoid producing @@ -1044,7 +1080,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.

@@ -1069,20 +1105,27 @@ Prompting in maintainer scripts

Package maintainer scripts may prompt the user if - necessary. Prompting may be accomplished by hand, or by - communicating with a program, such as - debconf, which conforms to the Debian - Configuration management specification, version 2 or - higher. These are included in the - debconf_specification files in the - debian-policy package. - You may also find this file on the FTP site + necessary. Prompting may be accomplished by + hand +

From the Jasrgon file: by hand 2. By extension, + writing code which does something in an explicit or + low-level way for which a presupplied library + (debconf, in this instance) routine ought + to have been available.

+ (but this is deprecated), or by + communicating though a program, which conforms to the + Debian Configuration management specification, version 2 + or higher (such as debconf). Thiss + specification is included in the + debconf_specification files in the + debian-policy package. You may also + find this file on the FTP site ftp.debian.org in /debian/doc/package-developer/debconf_specification.txt.gz or on your local mirror.

- 4% of Debian packages [see ] currently use debconf to prompt the user at install time, and this number is growing daily. The @@ -1099,7 +1142,7 @@ debconf, plus the existance of a nascent second implementation of the Debian configuration management system - (cdebconf), and the stabalization + (cdebconf), and the stabilization of the protocol these things use, the time has finally come to reflect the use of these things in policy. @@ -1114,7 +1157,7 @@ file in their control archive. The config script might be run before the preinst script, and before the package is unpacked or any of its - dependancies or pre-dependancies are satisfied. + dependencies or pre-dependancies are satisfied. Therefore it must work using only the tools present in essential packages.

@@ -1132,8 +1175,8 @@ they need to do, and they should ensure that the user will only ever be asked each question once. This means that packages should try to use appropriate shared - configuration files (such as /etc/papersize and - /etc/news/server), and shared + configuration files (such as /etc/papersize and + /etc/news/server), and shared debconf variables rather than each prompting for their own list of required pieces of information. @@ -1144,7 +1187,7 @@ questions again, unless the user has used dpkg --purge to remove the package's configuration. The answers to configuration questions should be stored in an - appropriate place in /etc so that the user can + appropriate place in /etc so that the user can modify them, and how this has been done should be documented.

@@ -1158,7 +1201,7 @@ prompt the user to hit return to acknowledge the message. Copyright messages do not count as vitally important (they belong in - /usr/share/doc/package/copyright); + /usr/share/doc/package/copyright); neither do instructions on how to use a program (these should be in on-line documentation, where all the users can see them).

@@ -1215,11 +1258,11 @@ four components may be specified.

In the past, people specified the full version number - in the Standards-Version field, for example `2.3.0.0'. + in the Standards-Version field, for example "2.3.0.0". Since minor patch-level changes don't introduce new policy, it was thought it would be better to relax policy and only require the first 3 components to be - specified, in this example `2.3.0'. All four + specified, in this example "2.3.0". All four components may still be used if someone wishes to do so.

@@ -1234,7 +1277,7 @@ Standards-Version source package field and release it.

- See the file upgrading-checklist for + See the file upgrading-checklist for information about policy which has changed between different versions of this document.

@@ -1243,7 +1286,7 @@ - + Package relationships

@@ -1261,7 +1304,7 @@ standard "Hello World!" program written in C or C++. The required packages are called build-essential, and an informational list can be found in - /usr/share/doc/build-essential/list (which is + /usr/share/doc/build-essential/list (which is contained in the build-essential package).

Rationale: @@ -1277,10 +1320,9 @@

Having a separate package allows one to install the build-essential packages on a machine, as - well as allowing other packages such as task - packages to require installation of the - build-essential packages using the depends - relation. + well as allowing other packages such as tasks to + require installation of the build-essential + packages using the depends relation.

@@ -1307,7 +1349,7 @@ you should list all those packages, and only those packages that you need directly. What others need is their business. For example, if you - only link against libimlib, you will need to + only link against libimlib, you will need to build-depend on libimlib2-dev but not against any libjpeg* packages, even though libimlib2-dev currently depends on @@ -1331,6 +1373,10 @@ are properly satisfied.

+

+ explains the technical details. +

+ Changes to the upstream sources @@ -1349,7 +1395,7 @@ or #define) and send the patch to the upstream authors, with the default set to the way they originally had it. You can then easily override the default in your - debian/rules or wherever is appropriate.

+ debian/rules or wherever is appropriate.

You should make sure that the configure utility @@ -1359,43 +1405,17 @@

If you need to edit a Makefile where GNU-style configure scripts are used, you - should edit the .in files rather than editing the + should edit the .in files rather than editing the Makefile directly. This allows the user to reconfigure the package if necessary. You should not configure the package and edit the generated Makefile! This makes it impossible for - someone else to later reconfigure the package.

 - - - - Documenting your changes + someone else to later reconfigure the package.

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 use a format for - debian/changelog which is supported by the most - recent released version of dpkg. -

- If you wish to use an alternative format, you may do - so as long as you include a parser for it in your - source package. The parser must have an API - compatible with that expected by - dpkg-genchanges and - dpkg-gencontrol. If there is general - interest in the new format, you should contact the - dpkg maintainer to have the parser - script for it included in the dpkg - package. (You will need to agree that the parser and - its manpage may be distributed under the GNU GPL, just - as the rest of `dpkg' is.) -

- + package properly in the debian/changelog file. + For more information, please see .

@@ -1406,8 +1426,8 @@

When make invokes a command in a makefile (including your package's upstream makefiles and - debian/rules), it does so using sh. This - means that sh's usual bad error handling + debian/rules), it does so using sh. This + means that sh's usual bad error handling properties apply: if you include a miniature script as one of the commands in your makefile you'll find that if you don't do anything about it then errors are not detected @@ -1454,9 +1474,9 @@ data represented in a common format, known as control data. The data is often stored in control files. Binary and source packages have control files, - and the .changes files which control the installation + and the .changes files which control the installation of uploaded files are also in control file format. - Dpkg's internal databases are in a similar + dpkg's internal databases are in a similar format.

@@ -1526,16 +1546,17 @@ Package: libc6

The name of the binary package. Package names consist of - the alphanumerics and + - . - (plus, minus and full stop). + lower case letters (a-z), digits (0-9), + plus (+) and minus (-) signs, and + periods (.).

They must be at least two characters long and must start - with an alphanumeric character and not be all digits. 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.

+ with an alphanumeric character. The use of lowercase + package names is required unless the package you're + building (or referring to, in other fields) is already + using uppercase characters.

 Version @@ -1568,7 +1589,7 @@ Package: libc6

- In a .changes file or parsed changelog output + In a .changes file or parsed changelog output this contains the (space-separated) name(s) of the distribution(s) where this version of the package should be installed. Valid distributions are determined by the @@ -1578,7 +1599,7 @@ Package: libc6 stable

- This is the current `released' version of Debian + This is the current "released" version of Debian GNU/Linux. Once the distribution is stable only security fixes and other major bug fixes are allowed. When changes are @@ -1619,7 +1640,7 @@ Package: libc6

From time to time, the testing - distribution enters a state of `code-freeze' in + distribution enters a state of "code-freeze" in anticipation of release as a stable version. During this period of testing only fixes for existing or newly-discovered bugs will @@ -1672,7 +1693,7 @@ Package: libc6

The version number format is: - [epoch:]upstream_version[-debian_revision] + [epoch:]upstream_version[-debian_revision]

@@ -1698,8 +1719,8 @@ Package: libc6

This is the main part of the version number. It is - usually the version number of the original (`upstream') - package from which the .deb file has been made, + usually the version number of the original ("upstream") + package from which the .deb file has been made, if this is applicable. Usually this will be in the same format as that specified by the upstream author(s); however, it may need to be reformatted to fit into the @@ -1743,7 +1764,7 @@ Package: libc6 upstream_version may not contain a hyphen. This format represents the case where a piece of software was written specifically to be turned into a - Debian package, and so there is only one `debianization' + Debian package, and so there is only one "debianization" of it and therefore no revision indication is required.

@@ -1829,15 +1850,15 @@ Package: libc6

However, in some cases where the upstream version number is - based on a date (e.g., a development `snapshot' release) the + based on a date (e.g., a development "snapshot" release) the package management system cannot handle these version numbers without epochs. For example, dpkg will consider - `96May01' to be greater than `96Dec24'.

+ "96May01" to be greater than "96Dec24".

To prevent having to use epochs for every new upstream version, the version number should be changed to the - following format in such cases: `19960501', `19961224'. It + following format in such cases: "19960501", "19961224". It is up to the maintainer whether he/she wants to bother the upstream maintainer to change the version numbers upstream, too.

@@ -1850,7 +1871,7 @@ Package: libc6

Native Debian packages (i.e., packages which have been written especially for Debian) whose version numbers include - dates should always use the `YYYYMMDD' format.

+ dates should always use the "YYYYMMDD" format.

@@ -1873,7 +1894,7 @@ Package: libc6

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

@@ -1889,7 +1910,7 @@ Package: libc6

- Since an interactive debian/rules script makes it + Since an interactive debian/rules script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary package, all required targets MUST be @@ -1996,8 +2017,8 @@ Package: libc6 build-arch or build-indep target, if provided, so that the package is built if it has not been already. It should then create the relevant - binary package(s), using dpkg-gencontrol to - make their control files and dpkg-deb to + binary package(s), using dpkg-gencontrol to + make their control files and dpkg-deb to build them and place them in the parent of the top level directory.

@@ -2085,7 +2106,7 @@ Package: libc6

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

@@ -2136,7 +2157,7 @@ Package: libc6

- debian/changelog + debian/changelog

@@ -2189,12 +2210,12 @@ Package: libc6 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 . + .changes file. See .

urgency is the value for the Urgency - field in the .changes file for the upload. It is + field in the .changes file for the upload. It is not possible to specify an urgency containing commas; commas are used to separate keyword=value settings in the @@ -2262,8 +2283,8 @@ Package: libc6

- The first `title' line with the package name should start - at the left hand margin; the `trailer' line with the + 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. @@ -2283,7 +2304,9 @@ Package: libc6 - debian/substvars + + + debian/substvars and variable substitutions

@@ -2292,42 +2315,41 @@ Package: libc6 generate control files they perform variable substitutions on their output just before writing it. Variable substitutions have the form ${variable}. - The optional file debian/substvars contains + The optional file debian/substvars contains variable substitutions to be used; variables can also be set - directly from debian/rules using the -V + directly from debian/rules using the -V option to the source packaging commands, and certain predefined variables are also available.

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

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

+ format of debian/substvars.

 - debian/files + 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. + when it generates a .changes file.

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

- files.new is used as a temporary file by + files.new is used as a temporary file by dpkg-gencontrol and dpkg-distaddfile - they write a new version of files here before renaming it, @@ -2342,8 +2364,8 @@ Package: libc6

When dpkg-gencontrol is run for a binary - package, it adds an entry to debian/files for the - .deb file that will be created when dpkg-deb + package, it adds an entry to debian/files for the + .deb file that will be created when dpkg-deb --build is run for that binary package. So for most packages all that needs to be done with this file is to delete it in the clean target. @@ -2355,7 +2377,7 @@ Package: libc6 made with dpkg-gencontrol then they should be placed in the parent of the package's top-level directory and dpkg-distaddfile should be called to add - the file to the list in debian/files.

+ the file to the list in debian/files.

 Restrictions on objects in source packages @@ -2381,8 +2403,20 @@ Package: libc6

+ Descriptions of packages - the - Description field + Description field + +

+ The "Description" control file field consists of two parts, + the synopsis or the short description, and the long description. + The field's format is as follows: +

+ +

+ Description: <single line synopsis> + <extended description over several lines> +

The description is intended to describe the program to a user @@ -2393,8 +2427,15 @@ Package: libc6 conflicts have been declared.

- Notes about writing descriptions - +

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

+ + The single line synopsis

The single line synopsis should be kept brief - certainly @@ -2409,6 +2450,10 @@ Package: libc6 informative as you can.

+ + + The extended description +

Do not try to continue the single line synopsis into the extended description. This will not work correctly when @@ -2427,35 +2472,63 @@ Package: libc6 The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. -

The blurb that comes with a program in its announcements and/or README files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used. -

- 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. + The lines in the extended description can have these formats:

-

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

+

+ + + Those starting with a single space are part of a paragraph. + Successive lines of this form will be word-wrapped when + displayed. The leading space will usually be stripped off. + + + + Those starting with two or more spaces. These will be + displayed verbatim. If the display cannot be panned + horizontally, the displaying program will linewrap them "hard" + (i.e., without taking account of word breaks). If it can they + will be allowed to trail off to the right. None, one or two + initial spaces may be deleted, but the number of spaces + deleted from each line will be the same (so that you can have + indenting work correctly, for example). + + + + Those containing a single space followed by a single full stop + character. These are rendered as blank lines. This is the + only way to get a blank line + Completely empty lines will not be rendered as blank lines. + Instead, they will cause the parser to think you're starting + a whole new record in the control file, and will therefore + likely abort with an error. + . + + + + Those containing a space, a full stop and some more characters. + These are for future expansion. Do not use them. + + +

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

+ + @@ -2537,7 +2610,7 @@ Package: libc6 aborted half way through for some reason, the second call should merely do the things that were left undone the first time, if any, and exit with a success status if everything - is OK. + is OK.

This is so that if an error occurs, the user interrupts dpkg or some other unforeseen circumstance @@ -2557,7 +2630,7 @@ Package: libc6 controlling terminal and can interact with the user. If they need to prompt for passwords, do full-screen interaction or something similar you should do these - things to and from /dev/tty, since + things to and from /dev/tty, since dpkg will at some point redirect scripts' standard input and output so that it can log the installation process. Likewise, because these scripts @@ -2701,7 +2774,7 @@ Package: libc6 case, if a major error occurs (unless listed below) the actions are, in general, run backwards - this means that the maintainer scripts are run with different arguments in - reverse order. These are the `error unwind' calls listed + reverse order. These are the "error unwind" calls listed below. @@ -2732,7 +2805,7 @@ Package: libc6

-

If a `conflicting' package is being removed at the same time: +

If a "conflicting" package is being removed at the same time:

@@ -2784,7 +2857,7 @@ Package: libc6

Otherwise, if the package had some configuration files from a previous version installed (i.e., it - is in the `configuration files only' state): + is in the "configuration files only" state): new-preinst install old-version

@@ -2842,7 +2915,7 @@ Package: libc6 Packages which overwrite each other's files produce behavior which, though deterministic, is hard for the system administrator to understand. It can easily - lead to `missing' programs if, for example, a package + lead to "missing" programs if, for example, a package is installed which overwrites a file from another package, and is then removed again.

@@ -2943,7 +3016,7 @@ Package: libc6 Any files in the package we're unpacking that are also listed in the file lists of other packages are removed from those lists. (This will lobotomize the file list - of the `conflicting' package if there is one.) + of the "conflicting" package if there is one.)

@@ -2956,7 +3029,7 @@ Package: libc6

The new package's status is now sane, and recorded as - `unpacked'. + "unpacked".

@@ -3071,34 +3144,6 @@ Package: libc6 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 - packages, and/or that they depend on the presence of others, - or that they should overwrite files in certain other packages - if present. -

- -

- This is done using the Depends, Pre-Depends, - Recommends, Suggests, Enhances, - Conflicts, Provides and Replaces - control file fields. -

- -

- Source packages may declare relationships to binary packages, - 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 - Build-Conflicts-Indep control file fields. -

- Syntax of relationship fields @@ -3205,8 +3250,21 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], Pre-Depends +

+ Packages can declare in their control file that they have + certain relationships to other packages - for example, that + they may not be installed at the same time as certain other + packages, and/or that they depend on the presence of others. +

+ +

+ This is done using the Depends, Pre-Depends, + Recommends, Suggests, Enhances and + Conflicts control file fields. +

+

- These five fields are used to declare a dependency + These six fields are used to declare a dependency relationship by one package on another. Except for Enhances, they appear in the depending (binary) package's control file. (Enhances appears in the @@ -3409,7 +3467,7 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],

A Conflicts entry should almost never have an - `earlier than' version clause. This would prevent + "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. @@ -3420,13 +3478,13 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],

- As well as the names of actual (`concrete') packages, the + As well as the names of actual ("concrete") packages, the package relationship fields Depends, Recommends, Suggests, Enhances, Pre-Depends, Conflicts, Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep - may mention `virtual packages'. + may mention "virtual packages".

@@ -3434,15 +3492,17 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], Provides control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name - everywhere the virtual package name appears. + everywhere the virtual package name appears. (See also )

- If there are both a real and a virtual package of the same - name then the dependency may be satisfied (or the conflict - caused) by either the real package or any of the virtual - packages which provide it. This is so that, for example, - supposing we have + If there are both concrete and virtual packages of the same + name, then the dependency may be satisfied (or the conflict + caused) by either the concrete package with the name in + question or any other concrete package which provides the + virtual package with the name in question. This is so that, + for example, supposing we have Package: foo Depends: bar @@ -3463,7 +3523,7 @@ Provides: bar 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 the virtual package is not of the `right' version. + 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 @@ -3492,8 +3552,10 @@ Provides: bar packages - Replaces

- The Replaces control file field has two distinct - purposes, which come into play in different situations. + Packages can declare in their control file that they should + overwrite files in certain other packages, or completely + replace other packages. The Replaces control file + field has these two distinct purposes.

Overwriting files in other packages @@ -3509,13 +3571,13 @@ Provides: bar Replaces the one containing the file being overwritten, then dpkg will replace the file from the old package with that from the new. The file - will no longer be listed as `owned' by the old package. + will no 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 + contains, it is considered to have "disappeared". It will be marked as not wanted on the system (selected for removal) and not installed. Any conffiles details noted for the package will be ignored, as they @@ -3583,16 +3645,51 @@ Replaces: mail-transport-agent Build-Conflicts, Build-Conflicts-Indep +

+ Source packages that require certain binary packages to be + installed or absent at the time of building the package + can declare relationships to those binary packages. +

+ +

+ This is done using the Build-Depends, + Build-Depends-Indep, Build-Conflicts and + Build-Conflicts-Indep control file fields. +

+

- A source package may declare a dependency or a conflict on a - binary package, indicating which packages are required to be - present on the system in order to build the binary packages - from the source package. This is done with the control file - fields Build-Depends, Build-Depends-Indep, - Build-Conflicts and Build-Conflicts-Indep. + Build-dependencies on "build-essential" binary packages can be + omitted. Please see for more information. +

+ +

The dependencies and conflicts they define must be satisfied (as defined earlier for binary packages) in order to invoke - the targets in debian/rules, as follows: + the targets in debian/rules, as follows: +

+ If you make "build-arch" or "binary-arch", you need + Build-Depends. If you make "build-indep" or + "binary-indep", you need Build-Depends and + Build-Depends-Indep. If you make "build" or "binary", + you need both. +

+

+ There is no Build-Depends-Arch; the autobuilders will + only need the Build-Depends if they know how to build + only build-arch and binary-arch. Anyone building the + build-indep/binary-indep targets is basically assumed to + be building the whole package and so installs all build + dependencies. +

+

+ The purpose of the original split, I recall, was so that + the autobuilders wouldn't need to install extra packages + needed only for the binary-indep targets. But without a + build-arch/build-indep split, this didn't work, since + most of the work is done in the build target, not in the + binary target. +

+ Build-Depends, Build-Conflicts @@ -3601,17 +3698,21 @@ Replaces: mail-transport-agent The Build-Depends and Build-Conflicts fields must be satisfied when any of the following targets is invoked: - build, binary, binary-arch - and binary-indep. + build, clean, binary, + binary-arch, build-arch, + build-indep and binary-indep.

- Build-Depends-Indep, Build-Conflicts-Indep + Build-Depends-Indep, + Build-Conflicts-Indep

The Build-Depends-Indep and Build-Conflicts-Indep fields must be satisfied when any of the following targets is - invoked: binary and binary-indep. + invoked: build, clean, + build-indep, binary and + binary-indep.

@@ -3626,7 +3727,7 @@ Replaces: mail-transport-agent

- This chapter has been superseded by . + This chapter has been superseded by .

@@ -3641,10 +3742,51 @@ Replaces: mail-transport-agent

- Firstly, the package should install the shared libraries under - their normal names. For example, the libgdbmg1 - package should install libgdbm.so.1.7.3 as - /usr/lib/libgdbm.so.1.7.3. The files should not be + Packages involving shared libraries should be split up into + several binary packages. This section mostly deals with how + this separation is to be accomplished; rules for files within + the shared library packages are in instead. +

+ + + Run-time shared libraries + +

+ The run-time shared library needs to be placed in a package called + librarynamesoversion, where + soversion is the version number in the + soname of the shared library +

+ The soname is the shared object name: it's the thing + that has to match exactly between building an executable + and running it for the dynamic linker to be able run the + program. For example, if the soname of the library is + libfoo.so.6, the library package would be + called libfoo6. +

+ . + Alternatively, if it would be confusing to directly append + soversion to libraryname (e.g. because + libraryname itself ends in a number), you may use + libraryname-soversion and + libraryname-soversion-dev + instead. +

+ +

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

+ +

+ The package should install the shared libraries under + their normal names. For example, the libgdbmg1 + package should install libgdbm.so.1.7.3 as + /usr/lib/libgdbm.so.1.7.3. The files should not be renamed or re-linked by any prerm or postrm scripts; dpkg will take care of renaming things safely without affecting running programs, @@ -3653,11 +3795,17 @@ Replaces: mail-transport-agent

- Secondly, the package should include the symbolic link that + Shared libraries should not be installed executable, since + the dynamic linker does not require this and trying to + execute a shared library usually results in a core dump. +

+ +

+ The run-time library package should include the symbolic link that ldconfig would create for the shared libraries. - For example, the libgdbmg1 package should include - a symbolic link from /usr/lib/libgdbm.so.1 to - libgdbm.so.1.7.3. This is needed so that the dynamic + For example, the libgdbmg1 package should include + a symbolic link from /usr/lib/libgdbm.so.1 to + libgdbm.so.1.7.3. This is needed so that the dynamic linker (for example ld.so or ld-linux.so.*) can find the library between the time that dpkg installs it and the time that @@ -3666,7 +3814,7 @@ Replaces: mail-transport-agent

The package management system requires the library to be placed before the symbolic link pointing to it in the - .deb file. This is so that when + .deb file. This is so that when dpkg comes to install the symlink (overwriting the previous symlink pointing at an older version of the library), the new shared library is already @@ -3674,32 +3822,25 @@ Replaces: mail-transport-agent library in the temporary packaging directory before creating the symlink. Unfortunately, this was not always effective, since the building of the tar file in the - .deb depended on the behavior of the underlying + .deb depended on the behavior of the underlying file system. Some file systems (such as reiserfs) reorder the files so that the order of creation is forgotten. - Starting with release 1.7.0, dpkg - will reorder the files itself as necessary when building a + Since version 1.7.0, dpkg + reorders the files itself as necessary when building a package. Thus it is no longer important to concern oneself with the order of file creation.

-

- Thirdly, the associated development package should contain a - symlink for the shared library without a version number. For - example, the libgdbmg1-dev package should include a - symlink from /usr/lib/libgdbm.so to - libgdbm.so.1.7.3. This symlink is needed by the - linker (ld) when compiling packages, as it will - only look for libgdbm.so when compiling dynamically. -

+ + ldconfig

Any package installing shared libraries in one of the default library directories of the dynamic linker (which are currently - /usr/lib and /lib) or a directory that is - listed in /etc/ld.so.conf + /usr/lib and /lib) or a directory that is + listed in /etc/ld.so.conf

These are currently @@ -3711,26 +3852,154 @@ Replaces: mail-transport-agent

- must call ldconfig in its postinst - script if the first argument is configure and should - call it in the postrm script if the first - argument is remove. + must use ldconfig to update the shared library + system.

- However, postrm and preinst scripts - must not call ldconfig in the case where - the package is being upgraded (see for - details), as ldconfig will see the temporary - names that dpkg uses for the files while it is - installing them and will make the shared library links point - to them, just before dpkg continues the - installation and renames the temporary files! + The package must call ldconfig in the + postinst script if the first argument is + configure; the postinst script may + optionally invoke ldconfig at other times. The + package should call ldconfig in the + postrm script if the first argument is + remove. The maintainer scripts must not invoke + ldconfig under any circumstances other than those + described in this paragraph. +

During install or upgrade, the preinst is called before + the new files are installed, so calling "ldconfig" is + pointless. The preinst of an existing package can also be + called if an upgrade fails. However, this happens during + the critical time when a shared libs may exist on-disk + under a temporary name. Thus, it is dangerous and + forbidden by current policy to call "ldconfig" at this + time. +

+

When a package is installed or upgraded, "postinst + configure" runs after the new files are safely on-disk. + Since it is perfectly safe to invoke ldconfig + unconditionally in a postinst, it is OK for a package to + simply put ldconfig in its postinst without checking the + argument. The postinst can also be called to recover from + a failed upgrade. This happens before any new files are + unpacked, so there is no reason to call "ldconfig" at this + point. +

+

For a package that is being removed, prerm is + called with all the files intact, so calling ldconfig is + useless. The other calls to "prerm" happen in the case of + upgrade at a time when all the files of the old package + are on-disk, so again calling "ldconfig" is pointless. +

+

postrm, on the other hand, is called with the "remove" + argument just after the files are removed, so this is the + proper time to call "ldconfig" to notify the system of the + fact shared libraries from the package are removed. + The postrm can be called at several other times. At the + time of "postrm purge", "postrm abort-install", or "postrm + abort-upgrade", calling "ldconfig" is useless because the + shared lib files are not on-disk. However, when "postrm" + is invoked with arguments "upgrade", "failed-upgrade", or + "disappear", a shared lib may exist on-disk under a + temporary filename. +

+

+ - - Handling shared library dependencies - the - shlibs system + + + + Run-time support programs + +

+ If your package has some run-time support programs which use + the shared library you must not put them in the shared + library package. If you do that then you won't be able to + install several versions of the shared library without + getting filename clashes. +

+ +

+ Instead, either create another package for the runtime binaries + (this package might typically be named + libraryname-runtime; note the absence + of the soversion in the package name), or if the + development package is small, include them in there. +

+ + + + Static libraries + +

+ The static library (libraryname.a) + is usually provided in addition to the shared version. + It is placed into the development package (see below). +

+ +

+ In some cases, it is acceptable for a library to be + available in static form only; these cases include: + + libraries for languages whose shared library support + is immature or unstable + libraries whose interfaces are in flux or under + development (commonly the case when the library's + major version number is zero, or where the ABI breaks + across patchlevels) + libraries which are explicitly intended to be + available only in static form by their upstream + author(s) + +

+ + + Development files + +

+ The development files associated to a shared library need to be + placed in a package called + librarynamesoversion-dev, + or if you prefer only to support one development version at a + time, libraryname-dev. +

+ +

+ In case several development versions of a library exist, you may + need to use dpkg's Conflicts mechanism (see + ) to ensure that the user only installs one + development version at a time (as different development versions are + likely to have the same header files in them, which would cause a + filename clash if both were installed). +

+ +

+ The development package should contain a symlink for the associated + shared library without a version number. For example, the + libgdbmg1-dev package should include a symlink + from /usr/lib/libgdbm.so to + libgdbm.so.1.7.3. This symlink is needed by the linker + (ld) when compiling packages, as it will only look for + libgdbm.so when compiling dynamically. +

+ + + + Dependencies between the packages of the same library + +

+ Typically the development version should have an exact + version dependency on the runtime library, to make sure that + compilation and linking happens correctly. The + ${Source-Version} substitution variable can be + useful for this purpose. +

+ + + + Dependencies between the library and other packages - + the shlibs system

If a package contains a binary or library which links to a @@ -3744,12 +4013,12 @@ Replaces: mail-transport-agent uses a shared library uses this information to determine the dependencies it requires. The files which contain the mapping from shared libraries to the necessary - dependency information are called shlibs files. + dependency information are called shlibs files.

Thus, when a package is built which contains any shared - libraries, it must provide a shlibs file for other + libraries, it must provide a shlibs file for other packages to use, and when a package is built which contains any shared libraries or compiled binaries, it must run dpkg-shlibdeps on these to determine the @@ -3758,8 +4027,8 @@ Replaces: mail-transport-agent

In the past, the shared libraries linked to were determined by calling ldd, but now - objdump to do this. The only change this - makes to package building is that + objdump is used to do this. The only + change this makes to package building is that dpkg-shlibdeps must also be run on shared libraries, whereas in the past this was unnecessary. The rest of this footnote explains the advantage that @@ -3774,7 +4043,7 @@ Replaces: mail-transport-agent libraries that are needed by libbar are linked indirectly to foo, and the dynamic linker will load them automatically when it loads - libbar. A package should needs to depend on + libbar. A package should depend on the libraries it directly uses, and the dependencies for those libraries should automatically pull in the other libraries. @@ -3812,10 +4081,9 @@ Replaces: mail-transport-agent shlibs file format and how to create them if your package contains a shared library.

- - The shlibs files present on the system - + + The shlibs files present on the system

There are several places where shlibs files are @@ -3827,7 +4095,7 @@ Replaces: mail-transport-agent

-

debian/shlibs.local

+

debian/shlibs.local

This lists overrides for this package. Its use is described below (see ). @@ -3835,7 +4103,7 @@ Replaces: mail-transport-agent -

/etc/dpkg/shlibs.override

+

/etc/dpkg/shlibs.override

This lists global overrides. This list is normally empty. It is maintained by the local system @@ -3844,12 +4112,12 @@ Replaces: mail-transport-agent -

DEBIAN/shlibs files in the `build directory'

+

DEBIAN/shlibs files in the "build directory"

When packages are being built, any - debian/shlibs files are copied into the + debian/shlibs files are copied into the control file area of the temporary build directory and - given the name shlibs. These files give + given the name shlibs. These files give details of any shared libraries included in the package.

@@ -3858,20 +4126,20 @@ Replaces: mail-transport-agent packages, libfoo2 and foo-runtime. When building the binary packages, the two packages are created in the - directories debian/libfoo2 and - debian/foo-runtime respectively. - (debian/tmp could be used instead of one + directories debian/libfoo2 and + debian/foo-runtime respectively. + (debian/tmp could be used instead of one of these.) Since libfoo2 provides the libfoo shared library, it will require a shlibs file, which will be installed in - debian/libfoo2/DEBIAN/shlibs, eventually + debian/libfoo2/DEBIAN/shlibs, eventually to become - /var/lib/dpkg/info/libfoo2.shlibs. Then + /var/lib/dpkg/info/libfoo2.shlibs. Then when dpkg-shlibdeps is run on the executable - debian/foo-runtime/usr/bin/foo-prog, it + debian/foo-runtime/usr/bin/foo-prog, it will examine the - debian/libfoo2/DEBIAN/shlibs file to + debian/libfoo2/DEBIAN/shlibs file to determine whether foo-prog's library dependencies are satisfied by any of the libraries provided by libfoo2. For this reason, @@ -3885,35 +4153,35 @@ Replaces: mail-transport-agent -

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

+

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

- These are the shlibs files corresponding to + These are the shlibs files corresponding to all of the packages installed on the system, and are maintained by the relevant package maintainers.

-

/etc/dpkg/shlibs.default

+

/etc/dpkg/shlibs.default

This file lists any shared libraries whose packages - have failed to provide correct shlibs files. - It was used when the shlibs setup was first + have failed to provide correct shlibs files. + It was used when the shlibs setup was first introduced, but it is now normally empty. It is maintained by the dpkg maintainer.

- + - + How to use dpkg-shlibdeps and the - shlibs files + shlibs files

Put a call to dpkg-shlibdeps into your - debian/rules file. If your package contains only + debian/rules file. If your package contains only compiled binaries and libraries (but no scripts), you can use a command such as: @@ -3933,7 +4201,7 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

This command puts the dependency information into the - debian/substvars file, which is then used by + debian/substvars file, which is then used by dpkg-gencontrol. You will need to place a ${shlib:Depends} variable in the Depends field in the control file for this to work. @@ -3942,7 +4210,7 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

If dpkg-shlibdeps doesn't complain, you're done. If it does complain you might need to create your own - debian/shlibs.local file, as explained below (see + debian/shlibs.local file, as explained below (see ).

@@ -3951,18 +4219,18 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ dpkg-shlibdeps on each one which contains compiled libraries or binaries. In such a case, you will need to use the -T option to the dpkg - utilities to specify a different substvars file. + utilities to specify a different substvars file. For more details on this and other options, see .

- + - The shlibs File Format - + + The shlibs File Format

- Each shlibs file has the same format. Lines - beginning with # are considered to be commments and + Each shlibs file has the same format. Lines + beginning with # are considered to be comments and are ignored. Each line is of the form: library-name soname-version-number dependencies ... @@ -3972,7 +4240,7 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

We will explain this by reference to the example of the zlib1g package, which (at the time of writing) - installs the shared library /usr/lib/libz.so.1.1.3. + installs the shared library /usr/lib/libz.so.1.1.3.

@@ -4019,18 +4287,18 @@ libz 1 zlib1g (>= 1:1.1.3) the dynamic linker about using older shared libraries with newer binaries.

- + - - Providing a shlibs file + + Providing a shlibs file

If your package provides a shared library, you should create - a shlibs file following the format described above. - It is usual to call this file debian/shlibs (but if + a shlibs file following the format described above. + It is usual to call this file debian/shlibs (but if you have multiple binary packages, you might want to call it - debian/shlibs.package instead). Then - let debian/rules install it in the control area: + debian/shlibs.package instead). Then + let debian/rules install it in the control area: install -m644 debian/shlibs debian/tmp/DEBIAN @@ -4039,35 +4307,35 @@ install -m644 debian/shlibs debian/tmp/DEBIAN install -m644 debian/shlibs.package debian/package/DEBIAN/shlibs An alternative way of doing this is to create the - shlibs file in the control area directly from - debian/rules without using a debian/shlibs + shlibs file in the control area directly from + debian/rules without using a debian/shlibs file at all,

This is what dh_makeshlibs in the debhelper suite does.

- since the debian/shlibs file itself is ignored by + since the debian/shlibs file itself is ignored by dpkg-shlibdeps.

As dpkg-shlibdeps reads the - DEBIAN/shlibs files in all of the binary packages + DEBIAN/shlibs files in all of the binary packages being built from this source package, all of the - DEBIAN/shlibs files should be installed before + DEBIAN/shlibs files should be installed before dpkg-shlibdeps is called on any of the binary packages.

- + - - Writing the debian/shlibs.local file + + Writing the debian/shlibs.local file

This file is intended only as a temporary fix if your binaries or libraries depend on a library whose package - does not yet provide a correct shlibs file. + does not yet provide a correct shlibs file.

@@ -4095,8 +4363,8 @@ libc.so.6 => /lib/libc.so.6 (0x40032000) So the foo binary depends on the libbar shared library, but no package seems to - provide a *.shlibs file handling - libbar.so.1 in /var/lib/dpkg/info/. Let's + provide a *.shlibs file handling + libbar.so.1 in /var/lib/dpkg/info/. Let's determine the package responsible: $ dpkg -S /usr/lib/libbar.so.1 @@ -4107,9 +4375,9 @@ Version: 1.0-1 This tells us that the bar1 package, version 1.0-1, is the one we are using. Now we can file a bug against the bar1 package and create our own - debian/shlibs.local to locally fix the problem. + debian/shlibs.local to locally fix the problem. Including the following line into your - debian/shlibs.local file: + debian/shlibs.local file: libbar 1 bar1 (>= 1.0-1) @@ -4118,13 +4386,16 @@ libbar 1 bar1 (>= 1.0-1)

As soon as the maintainer of bar1 provides a - correct shlibs file, you should remove this line - from your debian/shlibs.local file. (You should + correct shlibs file, you should remove this line + from your debian/shlibs.local file. (You should probably also then have a versioned Build-Depends on bar1 to help ensure that others do not have the same problem building your package.)

+ + + The Operating System @@ -4139,16 +4410,24 @@ libbar 1 bar1 (>= 1.0-1)

The location of all installed files and directories must comply with the Filesystem Hierarchy Standard (FHS), - except where doing so would violate other terms of Debian - Policy. The latest version of this document can be found - in the debian-policy package or on - alongside this manual or on + version 2.1, except where doing so would violate other + terms of Debian Policy. The version of this document + referred here can be found in the debian-policy + package or on + alongside this manual (or, if + you have the debian-policy installed, + you can try ). The + latest version, which may be a more recent version, may + be found on . Specific questions about following the standard may be asked on the debian-devel mailing list, or - referred to Daniel Quinlan, the FHS coordinator, at - quinlan@pathname.com. + referred to the FHS mailing list (see the + for + more information).

@@ -4157,14 +4436,14 @@ libbar 1 bar1 (>= 1.0-1)

As mandated by the FHS, packages must not place any - files in /usr/local, either by putting them in + 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 + /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. @@ -4172,20 +4451,20 @@ libbar 1 bar1 (>= 1.0-1)

Note, that this applies only to directories below - /usr/local, not in /usr/local. + /usr/local, not in /usr/local. Packages must not create sub-directories in the directory - /usr/local itself, except those listed in FHS, + /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 + Since /usr/local can be mounted read-only from a remote server, these directories must be created and removed by the postinst and prerm maintainer scripts and not be included in the - .deb archive. These scripts must not fail if + .deb archive. These scripts must not fail if either of these operations fail.

@@ -4209,26 +4488,26 @@ rmdir /usr/local/share/emacs 2>/dev/null || true in the prerm script. (Note that this form is used to ensure that if the script is interrupted, the - directory /usr/local/share/emacs will still be + directory /usr/local/share/emacs will still be removed.)

- If you do create a directory in /usr/local for + If you do create a directory in /usr/local for local additions to a package, you should ensure that - settings in /usr/local take precedence over the - equivalents in /usr. + settings in /usr/local take precedence over the + equivalents in /usr.

- However, because /usr/local and its contents are + However, because /usr/local and its contents are for 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. + directories in /usr/local for normal operation.

- The /usr/local directory itself and all the + The /usr/local directory itself and all the subdirectories created by the package should (by default) have permissions 2775 (group-writable and set-group-id) and be owned by root.staff. @@ -4238,14 +4517,14 @@ rmdir /usr/local/share/emacs 2>/dev/null || true The system-wide mail directory

- The system-wide mail directory is /var/mail. This + The system-wide mail directory is /var/mail. This directory is part of the base system and should not owned by any particular mail agents. The use of the old - location /var/spool/mail is deprecated, even + location /var/spool/mail is deprecated, even though the spool may still be physically located there. To maintain partial upgrade compatibility for systems - which have /var/spool/mail as their physical mail - spool, packages using /var/mail must depend on + which have /var/spool/mail as their physical mail + spool, packages using /var/mail must depend on either libc6 (>= 2.1.3-13), or on base-files (>= 2.2.0), or on later versions of either one of these packages. @@ -4283,8 +4562,8 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

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

@@ -4299,7 +4578,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

Globally allocated by the Debian project, the same on every Debian system. These ids will appear in - the passwd and group files of all + the passwd and group files of all Debian systems, new ids in this range being added automatically as the base-passwd package is updated. @@ -4324,7 +4603,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true adduser 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. + adduser.conf.

@@ -4334,7 +4613,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true Dynamically allocated user accounts. By default adduser will choose UIDs and GIDs for user accounts in this range, though - adduser.conf may be used to modify this + adduser.conf may be used to modify this behavior.

@@ -4357,10 +4636,10 @@ rmdir /usr/local/share/emacs 2>/dev/null || true These ids are for packages which are obscure or which require many statically-allocated ids. These packages should check for and create the accounts in - /etc/passwd or /etc/group (using + /etc/passwd or /etc/group (using adduser if it has this facility) if necessary. Packages which are likely to require - further allocations should have a `hole' left after + further allocations should have a "hole" left after them in the allocation, to give them room to grow.

@@ -4393,15 +4672,15 @@ rmdir /usr/local/share/emacs 2>/dev/null || true - System run levels and init.d scripts + System run levels and init.d scripts Introduction

- The /etc/init.d directory contains the scripts + The /etc/init.d directory contains the scripts executed by init at boot time and when the - init state (or `runlevel') is changed (see ).

@@ -4422,9 +4701,9 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

These scripts are referenced by symbolic links in the - /etc/rcn.d directories. When changing + /etc/rcn.d directories. When changing runlevels, init looks in the directory - /etc/rcn.d for the scripts it should + /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. @@ -4432,11 +4711,11 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

The names of the links all have the form - Smmscript or - Kmmscript where + Smmscript or + Kmmscript where 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). + name of the actual script in /etc/init.d).

@@ -4445,7 +4724,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true executed, each with the single argument stop, followed by the scripts prefixed with an S, each with the single argument start. (The links are - those in the /etc/rcn.d directory + those in the /etc/rcn.d directory corresponding to the new runlevel.) The K links are responsible for killing services and the S link for starting services upon entering the runlevel. @@ -4454,7 +4733,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

For example, if we are changing from runlevel 2 to runlevel 3, init will first execute all of the K - prefixed scripts it finds in /etc/rc3.d, and then + prefixed scripts it finds in /etc/rc3.d, and then all of the S prefixed scripts in that directory. The links starting with K will cause the referred-to file to be executed with an argument of @@ -4502,10 +4781,10 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

Packages that include daemons for system services should - place scripts in /etc/init.d to start or stop + place scripts in /etc/init.d to start or stop services at boot time or during a change of runlevel. These scripts should be named - /etc/init.d/package, and they should + /etc/init.d/package, and they should accept one argument, saying what to do: @@ -4516,7 +4795,8 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

stop the service,

restart -

stop and restart the service,

 +

stop and restart the service if it's already + running, otherwise start the service

 reload

cause the configuration of the service to be @@ -4531,11 +4811,11 @@ rmdir /usr/local/share/emacs 2>/dev/null || true The start, stop, restart, and force-reload options should be supported by all - scripts in /etc/init.d, the reload + scripts in /etc/init.d, the reload option is optional.

- The init.d scripts should ensure that they will + The init.d scripts should ensure that they will behave sensibly if invoked with start when the service is already running, or with stop when it isn't, and that they don't kill unfortunately-named user @@ -4545,21 +4825,23 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

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

- The /etc/init.d scripts should be treated as - configuration files, either by marking them as - conffiles or managing them correctly in the - maintainer scripts (see ). This is - important since we want to give the local system - administrator the chance to adapt the scripts to the local - system, e.g., to disable a service without de-installing - the package, or to specify some special command line - options when starting a service, while making sure her - changes aren't lost during the next package upgrade. + The /etc/init.d scripts must be treated as + configuration files, either (if they are present in the + package, that is, in the .deb file) by marking them as + conffiles, or, (if they do not exist in the .deb) + by managing them correctly in the maintainer scripts (see + ). This is important since we want + to give the local system administrator the chance to adapt + the scripts to the local system, e.g., to disable a + service without de-installing the package, or to specify + some special command line options when starting a service, + while making sure her changes aren't lost during the next + package upgrade.

@@ -4569,7 +4851,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true the package has been removed. Only when dpkg is executed with the --purge option will configuration files be removed. In particular, as the - /etc/init.d/package script itself is + /etc/init.d/package script itself is usually a conffile, it will remain on the system if the package is removed but not purged. Therefore, you should include a test statement at the top of the @@ -4580,8 +4862,8 @@ test -f program-executed-later-in-script || exit 0

- Often there are some variables in the init.d - scripts whose values control the bahaviour of the scripts, + Often there are some variables in the init.d + scripts whose values control the behaviour of the scripts, and which a system administrator is likely to want to change. As the scripts themselves are frequently conffiles, modifying them requires that the @@ -4590,125 +4872,202 @@ test -f program-executed-later-in-script || exit 0 the burden on the system administrator, such configurable values should not be placed directly in the script. Instead, they should be placed in a file in - /etc/default, which typically will have the same - base name as the init.d script. This extra file + /etc/default, which typically will have the same + base name as the init.d script. This extra file should be sourced by the script when the script runs. It must contain only variable settings and comments in POSIX sh format. It may either be a conffile or a configuration file maintained by - the package maintainer scripts. See for more details. + the package maintainer scripts. See + for more details.

To ensure that vital configurable values are always - available, the init.d script should set default + available, the init.d script should set default values for each of the shell variables it uses, either - before sourcing the /etc/default/ file or + before sourcing the /etc/default/ file or afterwards using something like the : - ${VAR:=default} syntax. Also, the init.d + ${VAR:=default} syntax. Also, the init.d script must behave sensibly and not fail if the - /etc/default file is deleted. + /etc/default file is deleted.

- Managing the links - -

- The program update-rc.d is provided for - package maintainers to arrange for the proper creation and - removal of /etc/rcn.d symbolic links, - or their functional equivalent if another method is being - used. This may be used by maintainers in their packages' - postinst and postrm scripts.

- -

- You must not include any /etc/rcn.d - symbolic links in the actual archive or manually create or - remove the symbolic links in maintainer scripts; you must - use the update-rc.d program instead. (The - former will fail if an alternative method of maintaining - runlevel information is being used.) You must not include - the /etc/rcn.d directories themselves - in the archive either. (Only the sysvinit - package may do so.) -

+ Interfacing with the initscript system

- By default update-rc.d will start services in - each of the multi-user state runlevels (2, 3, 4, and 5) - and stop them in the halt runlevel (0), the single-user - runlevel (1) and the reboot runlevel (6). The system - administrator will have the opportunity to customize - runlevels by simply adding, moving, or removing the - symbolic links in /etc/rcn.d if - symbolic links are being used, or by modifying - /etc/runlevel.conf if the file-rc method - is being used. + Maintainers should use the abstraction layer provided by + the update-rc.d and invoke-rc.d + programs to deal with initscripts in their packages' + scripts such as postinst, prerm + and postrm.

-

- To get the default behavior for your package, put in your - postinst script - -update-rc.d package defaults >/dev/null - - and in your postrm - -if [ "$1" = purge ]; then - update-rc.d package remove >/dev/null -fi -

+ Directly managing the /etc/rc?.d links and directly + invoking the /etc/init.d/ initscripts should + be done only by packages providing the initscript + subsystem (such as sysvinit and + file-rc). -

- This will use a default sequence number of 20. If it does - not matter when or in which order the init.d - script is run, use this default. If it does, then you - should talk to the 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 . -

- + + Managing the links +

+ The program update-rc.d is provided for + package maintainers to arrange for the proper creation and + removal of /etc/rcn.d symbolic links, + or their functional equivalent if another method is being + used. This may be used by maintainers in their packages' + postinst and postrm scripts.

- - Boot-time initialization +

+ You must not include any /etc/rcn.d + symbolic links in the actual archive or manually create or + remove the symbolic links in maintainer scripts; you must + use the update-rc.d program instead. (The + former will fail if an alternative method of maintaining + runlevel information is being used.) You must not include + the /etc/rcn.d directories themselves + in the archive either. (Only the sysvinit + package may do so.) +

-

- There used to be another directory, /etc/rc.boot, - which contained scripts which were run once per machine - boot. This has been deprecated in favour of links from - /etc/rcS.d to files in /etc/init.d as - described in . Packages must not - place files in /etc/rc.boot.

+

+ By default update-rc.d will start services in + each of the multi-user state runlevels (2, 3, 4, and 5) + and stop them in the halt runlevel (0), the single-user + runlevel (1) and the reboot runlevel (6). The system + administrator will have the opportunity to customize + runlevels by simply adding, moving, or removing the + symbolic links in /etc/rcn.d if + symbolic links are being used, or by modifying + /etc/runlevel.conf if the file-rc method + is being used. +

- - Example +

+ To get the default behavior for your package, put in your + postinst script + + update-rc.d package defaults + + and in your postrm + + if [ "$1" = purge ]; then + update-rc.d package remove + fi + . Note that if your package changes runlevels + or priority, you may have to remove and recreate the links, + since otherwise the old links may persist. Refer to the + documentation of update-rc.d

-

- The bind DNS (nameserver) package wants to - make sure that the nameserver is running in multiuser - runlevels, and is properly shut down with the system. It - puts a script in /etc/init.d, naming the script - appropriately bind. As you can see, the script - interprets the argument reload to send the - nameserver a HUP signal (causing it to reload its - configuration); this way the system administrator can say - /etc/init.d/bind reload to reload the name - server. The script has one configurable value, which can - be used to pass parameters to the named program at - startup; this value is read from - /etc/default/bind (see below). -

+

+ This will use a default sequence number of 20. If it does + not matter when or in which order the init.d + script is run, use this default. If it does, then you + should talk to the 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 . +

+ + + + Running initscripts +

+ The program invoke-rc.d is provided to make + it easier for package maintainers to properly invoke an + initscript, obeying runlevel and other locally-defined + constraints that might limit a package's right to start, + stop and otherwise manage services. This program may be + used by maintainers in their packages' scripts. +

+

+ The use of invoke-rc.d to invoke the + /etc/init.d/* initscripts is strongly + recommended +

+ In the future, the use of invoke-rc.d to invoke + initscripts shall be made mandatory. Maintainers are + advised to switch to invoke-rc.d as soon as + possible.

+ , instead of calling them directly. +

+ +

+ By default, invoke-rc.d will pass any + action requests (start, stop, reload, restart...) to the + /etc/init.d script, filtering out requests + to start or restart a service out of its intended + runlevels. +

+

+ Most packages will simply need to change: + /etc/init.d/<package> + <action> in their postinst + and prerm scripts to: + + if [ -x /usr/sbin/invoke-rc.d ] ; then + invoke-rc.d package <action> + else + /etc/init.d/package <action> + fi +

+

+ A package should register its initscript services using + update-rc.d before it tries to invoke them + using invoke-rc.d. Invocation of + unregistered services may fail. +

+

+ For more information about using + invoke-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 + boot. This has been deprecated in favour of links from + /etc/rcS.d to files in /etc/init.d as + described in . Packages must not + place files in /etc/rc.boot.

+ + + Example + +

+ The bind DNS (nameserver) package wants to + make sure that the nameserver is running in multiuser + runlevels, and is properly shut down with the system. It + puts a script in /etc/init.d, naming the script + appropriately bind. As you can see, the script + interprets the argument reload to send the + nameserver a HUP signal (causing it to reload its + configuration); this way the system administrator can say + /etc/init.d/bind reload to reload the name + server. The script has one configurable value, which can + be used to pass parameters to the named program at + startup; this value is read from + /etc/default/bind (see below). +

+ +

#!/bin/sh # @@ -4752,7 +5111,8 @@ force-reload|reload) echo "." ;; *) - echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2 + echo "Usage: /etc/init.d/bind " \ + " {start|stop|restart|reload|force-reload}" >&2 exit 1 ;; esac @@ -4763,7 +5123,7 @@ exit 0

Complementing the above init script is a configuration - file /etc/default/bind, which contains + file /etc/default/bind, which contains configurable parameters used by the script. This would be created by the postinst script if it was not already present, and removed on purge by the @@ -4777,8 +5137,8 @@ exit 0

Another example on which you can base your - /etc/init.d scripts is found in - /etc/init.d/skeleton. + /etc/init.d scripts is found in + /etc/init.d/skeleton.

@@ -4801,11 +5161,11 @@ fi - Console messages from init.d scripts + Console messages from init.d scripts

This section describes the formats to be used for messages - written to standard output by the /etc/init.d + 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. For this reason, please look very carefully at the details. We want @@ -4885,7 +5245,7 @@ Starting description: daemon-1 ... daemon-n.

- For example, the output of /etc/init.d/lpd + For example, the output of /etc/init.d/lpd would look like: Starting printer spooler: lpd. @@ -4925,7 +5285,7 @@ echo "." If you have to set up different system parameters during the system boot, you should use this format: -Setting parameter to `value'. +Setting parameter to "value".

@@ -4933,13 +5293,15 @@ Setting parameter to `value'. You can use a statement such as the following to get the quotes right: -echo "Setting DNS domainname to \`$domainname'." +echo "Setting DNS domainname to \"$domainname\"."

- Note that the left quotation mark (`) is - different from the right one ('). + Note that the same symbol (") is used for the left + and right quotation marks. A grave accent (`) is + not a quote character; neither is an apostrophe + (').

@@ -5010,8 +5372,8 @@ Reloading description configuration...done.

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

+ /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 @@ -5025,7 +5387,7 @@ Reloading description configuration...done. As these directory names imply, the files within them are executed on a daily, weekly, or monthly basis, respectively. The exact times are listed in - /etc/crontab.

+ /etc/crontab.

All files installed in any of these directories must be @@ -5038,11 +5400,11 @@ Reloading description configuration...done.

If a certain job has to be executed more frequently than daily, the package should install a file - /etc/cron.d/package. This file uses the - same syntax as /etc/crontab and is processed by + /etc/cron.d/package. This file uses the + same syntax as /etc/crontab and is processed by cron automatically. The file must also be treated as a configuration file. (Note that entries in the - /etc/cron.d directory are not handled by + /etc/cron.d directory are not handled by anacron. Thus, you should only use this directory for jobs which may be skipped if the system is not running.)

@@ -5058,15 +5420,6 @@ Reloading description configuration...done. Menus -

- Menu entries should follow the current menu policy found in - the menu-policy files in the debian-policy - package. It may also be found on the Debian FTP site - ftp.debian.org as the file - /debian/doc/package-developer/menu-policy.txt.gz, - or in the equivalent location on your local mirror. -

-

The Debian menu package provides a standard interface between packages providing applications and @@ -5081,7 +5434,23 @@ Reloading description configuration...done. operation should register a menu entry for those applications, so that users of the menu package will automatically get menu entries in their window - managers, as well in shells like pdmenu.

+ managers, as well in shells like pdmenu. +

+ +

+ Menu entries should follow the current menu policy. +

+ +

+ The menu policy can be found in the menu-policy + files in the debian-policy package. + They are also available from the Debian web mirrors at + + and from the Debian archive mirrors at + . +

Please also refer to the Debian Menu System @@ -5094,17 +5463,6 @@ Reloading description configuration...done. Multimedia handlers -

- Packages which provide the ability to view/show/play, - compose, edit or print MIME types should register themselves - as such following the current MIME support policy found in - the mime-policy files in the debian-policy - package. It may also be found on the Debian FTP site - ftp.debian.org as the file - /debian/doc/package-developer/mime-policy.txt.gz, - or in the equivalent location on your local mirror. -

-

MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) is a mechanism for encoding files and data streams and @@ -5119,6 +5477,24 @@ Reloading description configuration...done. view, edit or display MIME types they don't support directly.

+ +

+ Packages which provide the ability to view/show/play, + compose, edit or print MIME types should register themselves + as such following the current MIME support policy. +

+ +

+ The MIME support policy can be found in the mime-policy + files in the debian-policy package. + They are also available from the Debian web mirrors at + + and from the Debian archive mirrors at + . +

+ @@ -5158,7 +5534,7 @@ Reloading description configuration...done.

-

<-- generates KB_Backspace +

<-- generates KB_BackSpace in X.

Delete generates KB_Delete in @@ -5169,7 +5545,7 @@ Reloading description configuration...done. X translations are set up to make KB_Backspace generate ASCII DEL, and to make KB_Delete generate ESC [ 3 ~ (this - is the vt220 escape code for the `delete character' + is the vt220 escape code for the "delete character" key). This must be done by loading the X resources using xrdb on all local X displays, not using the application defaults, so that the @@ -5208,9 +5584,9 @@ Reloading description configuration...done.

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

 + with ASCII DEL being "delete previous character" and + kdch1 being "delete character under + cursor".

@@ -5274,7 +5650,7 @@ Reloading description configuration...done. 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 + configuration file like /etc/profile, which is not supported by all shells.)

@@ -5284,7 +5660,7 @@ Reloading description configuration...done. variables are not present. If this cannot be done easily (e.g., if the source code of a non-free program is not available), the program must be replaced by a small - `wrapper' shell script which sets the environment variables + "wrapper" shell script which sets the environment variables if they are not already defined, and calls the original program.

@@ -5299,7 +5675,7 @@ exec /usr/lib/foo/foo "$@"

- Furthermore, as /etc/profile is a configuration + Furthermore, as /etc/profile is a configuration file of the base-files package, other packages must not put any environment variables or other commands into that file.

@@ -5316,8 +5692,8 @@ exec /usr/lib/foo/foo "$@" Two different packages must not install programs with different functionality but with the same filenames. (The case of two programs having the same functionality but - different implementations is handled via `alternatives' or - the `Conflicts' mechanism. See and + different implementations is handled via "alternatives" or + the "Conflicts" mechanism. See and respectively.) If this case happens, one of the programs must be renamed. The maintainers should report this to the debian-devel mailing list and @@ -5327,67 +5703,81 @@ exec /usr/lib/foo/foo "$@"

- Generally the following compilation parameters should be used: + By default, when a package is being built, any binaries + created should include debugging information, as well as + being compiled with optimization. You should also turn on + as many reasonable compilation warnings as possible; this + makes life easier for porters, who can then look at build + logs for possible problems. For the C programming language, + this means the following compilation parameters should be + used: CC = gcc -CFLAGS = -O2 -Wall # sane warning options vary between programs +CFLAGS = -O2 -g -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 install, or by calling strip on the binaries after they have been copied into - debian/tmp but before the tree is made into a + 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 - in bug reports), or testing and developing the software. - Therefore it is recommended to support building the package - with debugging information through the following interface: - If the environment variable DEB_BUILD_OPTIONS - contains the string debug, compile the software - with debugging information (usually this involves adding the - -g flag to CFLAGS). This allows the - generation of a build tree with debugging information. If - the environment variable DEB_BUILD_OPTIONS contains - the string nostrip, do not strip the files at - installation time. This allows one to generate a package - with debugging information included. -

- Rationale: Using -g by default causes wasted - CPU cycles since the information is stripped away - anyway; this can have a significant impact on the - efficiency of the autobuilders. Having a standard way - to build a debugging variant also makes it easier to - build debugging bins and libraries since it provides a - documented way of getting this type of build; one does - not have to manually edit debian/rules or - Makefiles. -

- + Although binaries in the build tree should be compiled with + debugging information by default, it can often be difficult + to debug programs if they are also subjected to compiler + optimization. For this reason, it is recommended to support + the standardized environment + variable DEB_BUILD_OPTIONS. This variable can + contain several flags to change how a package is compiled + and built. +

+

+ + noopt + +

+ The presence of this string means that the package + should be complied with a minimum of optimization. + For C programs, it is best to add -O0 + to CFLAGS (although this is usually the + default). Some programs might fail to build or run at + this level of optimization; it may be necessary to + use -O1, for example. +

+ + nostrip + +

+ This string means that the debugging symbols should + not be stripped from the binary during installation, + so that debugging information may be included in the package. +

+ + +

+

The following makefile snippet is an example of how one may - test for either condition; you will probably have to massage - this example in order to make it work for your package. - -CFLAGS = -O2 -Wall + implement the build options; you will probably have to + massage this example in order to make it work for your + package. + +CFLAGS = -Wall -g INSTALL = install INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 -ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS))) -CFLAGS += -g +ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) +CFLAGS += -O0 +else +CFLAGS += -O2 endif ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) INSTALL_PROGRAM += -s @@ -5405,28 +5795,30 @@ endif if there is good reason to do so. Feel free to override the upstream author's ideas about which compilation options are best: they are often inappropriate for our - environment.

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

+ The shared version of a library must be compiled with + -fPIC, and the static version must not be. In other + words, each source unit (*.c, for example, for C files) + 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.

+ the library compatible with LinuxThreads. +

- Note that all installed shared libraries should be - stripped with + All installed shared libraries should be stripped with strip --strip-unneeded your-lib @@ -5453,30 +5845,30 @@ strip --strip-unneeded your-lib

- Shared object files (often .so files) that are not + Shared object files (often .so files) that are not public libraries, that is, they are not meant to be linked to by third party executables (binaries of other packages), should be installed in subdirectories of the - /usr/lib directory. Such files are exempt from the + /usr/lib directory. Such files are exempt from the rules that govern ordinary shared libraries, except that they must not be installed executable and should be stripped.

- A common example are the so-called ``plug-ins'', + A common example are the so-called "plug-ins", internal shared objects that are dynamically loaded by programs using .

- +

Packages containing shared libraries that may be linked to by other packages' binaries, but which for some compelling reason can not be installed in - /usr/lib directory, may install the shared library - files in subdirectories of the /usr/lib directory, + /usr/lib directory, may install the shared library + files in subdirectories of the /usr/lib directory, in which case they should arrange to add that directory in - /etc/ld.so.conf in the package's post-installation + /etc/ld.so.conf in the package's post-installation script, and remove it in the package's post-removal script.

@@ -5484,9 +5876,9 @@ strip --strip-unneeded your-lib An ever increasing number of packages are using libtool to do their linking. The latest GNU libtools (>= 1.3a) can take advantage of the metadata in the - installed libtool archive files (*.la + installed libtool archive files (*.la files). The main advantage of libtool's - .la files is that it allows libtool to + .la files is that it allows libtool to store and subsequently access metadata with respect to the libraries it builds. libtool will search for those files, which contain a lot of useful information about @@ -5503,16 +5895,16 @@ strip --strip-unneeded your-lib for each library every time it is linked. With the advent of libtool version 1.4 (and to a lesser extent libtool version 1.3), the - .la files also store information about + .la files also store information about inter-library dependencies which cannot necessarily be - derived after the .la file is deleted. + derived after the .la file is deleted.

Packages that use libtool to create shared - libraries should include the .la files in the + libraries should include the .la files in the -dev package, unless the package relies on libtool's libltdl library, in which case the .la files must go in the run-time library @@ -5529,85 +5921,15 @@ strip --strip-unneeded your-lib

+ 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 - libraries you need to create two packages: - librarynamesoversion, where - soversion is the version number in the - soname of the shared library -

- The soname is the shared object name: it's the thing - that has to match exactly between building an executable - and running it for the dynamic linker to be able run the - program. For example, if the soname of the library is - libfoo.so.6, the library package would be - called libfoo6. -

- - and librarynamesoversion-dev. -

- -

- If you prefer only to support one development version at a - time you may name the development package - libraryname-dev; otherwise you may need - to use dpkg's Conflicts mechanism (see ) to ensure that the user only installs one - development version at a time (as different development - versions are likely to have the same header files in them, - which would cause a filename clash if both were installed). - Typically the development version should also have an exact - version dependency on the runtime library, to make sure that - compilation and linking happens correctly. The - ${Source-Version} substitution variable can be - useful for this purpose. -

- -

- Packages which use the shared library should have a - dependency on the name of the shared library package, - librarynamesoversion. When - the soname changes you can have both versions of the library - installed while migrating 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 the shared - library package. If you do that then you won't be able to - install several versions of the shared library without - getting filename clashes. Instead, either create a third - package for the runtime binaries (this package might - typically be named libraryname-runtime; - note the absence of the soversion in the package - name), or if the development package is small you may - 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 - shared library package, provided that you change all of - their sonames at once (so that you don't get filename - clashes if you try to install different versions of the - combined shared libraries package). -

- -

- Shared libraries should not be installed executable, since - the dynamic linker does not require this and trying to - execute a shared library usually results in a core dump. + This section has moved to .

+ Scripts @@ -5629,12 +5951,12 @@ strip --strip-unneeded your-lib command.

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

Debian policy specifies POSIX behavior for - /bin/sh, but echo -n has widespread + /bin/sh, but echo -n has widespread use in the Linux community (in particular including this policy, the Linux kernel source, many Debian scripts, etc.). This echo -n mechanism is valid but not @@ -5643,22 +5965,23 @@ strip --strip-unneeded your-lib the LSB anyway.

- Thus, shell scripts specifying /bin/sh as + Thus, shell scripts specifying /bin/sh as interpreter should only use POSIX features. If a script requires non-POSIX features from the shell interpreter, the appropriate shell must be specified in the first line of the script (e.g., #!/bin/bash) and the package must depend on the package providing the shell (unless the shell - package is marked `Essential', as in the case of + package is marked "Essential", as 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. + possible so that it may use /bin/sh as its + interpreter. If your script works with dash + (originally called ash), it's probably POSIX + compliant, but if you are in doubt, use + /bin/bash.

@@ -5688,7 +6011,7 @@ strip --strip-unneeded your-lib

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

@@ -5706,11 +6029,11 @@ strip --strip-unneeded your-lib 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 /.)

+ directory /.)

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

@@ -5726,7 +6049,7 @@ strip --strip-unneeded your-lib

For example, in your Makefile or - debian/rules, you can do things like: + debian/rules, you can do things like: ln -fs gcc $(prefix)/bin/cc ln -fs gcc debian/tmp/usr/bin/cc @@ -5737,9 +6060,9 @@ 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 file. (For - example, if a file foo.gz is referenced by a + example, if a file foo.gz is referenced by a symbolic link, the filename of the link has to end with - `.gz' too, as in bar.gz.) + ".gz" too, as in bar.gz.)

@@ -5754,7 +6077,13 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq 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.

+ after notifying the user +

+ This notification could be done via a (low-priority) + debconf message, or an echo (printf) statement. +

+ + .

Packages must not remove any device files in the @@ -5763,12 +6092,12 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

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

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

 - + Configuration files Definitions @@ -5807,8 +6136,8 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

Note that a script that embeds configuration information - (such as most of the files in /etc/default and - /etc/cron.{daily,weekly,monthly}) is de-facto a + (such as most of the files in /etc/default and + /etc/cron.{daily,weekly,monthly}) is de-facto a configuration file and should be treated as such.

@@ -5817,17 +6146,16 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Location

Any configuration files created or used by your package - must reside in /etc. If there are several you - should consider creating a subdirectory of /etc + must reside in /etc. If there are several, + consider creating a subdirectory of /etc named after your package.

If your package creates or uses configuration files - outside of /etc, and it is not feasible to modify - the package to use the /etc, you should still put - the files in /etc and create symbolic links to - those files from the location that the package - requires.

+ outside of /etc, and it is not feasible to modify + the package to use /etc directly, put the files + in /etc and create symbolic links to those files + from the location that the package requires.

 @@ -5910,16 +6238,16 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

A common practice is to create a script called - package-configure and have the + package-configure and have the package's postinst call it if and only if the configuration file does not already exist. In certain cases it is useful for there to be an example or template file which the maintainer scripts use. Such files should - be in /usr/share/package or - /usr/lib/package (depending on whether + be in /usr/share/package or + /usr/lib/package (depending on whether they are architecture-independent or not). There should be symbolic links to them from - /usr/share/doc/package/examples if + /usr/share/doc/package/examples if they are examples, and should be perfectly ordinary dpkg-handled files (not configuration files). @@ -6011,23 +6339,26 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq User configuration files ("dotfiles")

- The files in /etc/skel will automatically be + The files in /etc/skel will automatically be copied into new user accounts by adduser. No other program should reference the files in - /etc/skel. + /etc/skel.

Therefore, if a program needs a dotfile to exist in - advance in $HOME to work sensibly, that dotfile - should be installed in /etc/skel and treated as a + advance in $HOME to work sensibly, that dotfile + should be installed in /etc/skel and treated as a configuration file.

However, programs that require dotfiles in order to - operate sensibly (dotfiles that they do not create - themselves automatically, that is) are a bad thing. + operate sensibly are a bad thing, unless they do create + the dotfiles themselves automatically. +

+ +

Furthermore, programs should be configured by the Debian default installation to behave as closely to the upstream default behaviour as possible. @@ -6037,14 +6368,14 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Therefore, if a program in a Debian package needs to be configured in some way in order to operate sensibly, that should be done using a site-wide configuration file placed - in /etc. Only if the program doesn't support a + in /etc. Only if the program doesn't support a site-wide default configuration and the package maintainer doesn't have time to add it may a default per-user file be - placed in /etc/skel. + placed in /etc/skel.

- /etc/skel should be as empty as we can make it. + /etc/skel should be as empty as we can make it. This is particularly true because there is no easy (or necessarily desirable) mechanism for ensuring that the appropriate dotfiles are copied into the accounts of @@ -6057,11 +6388,11 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Log files

Log files should usually be named - /var/log/package.log. If you have many + /var/log/package.log. If you have many log files, or need a separate directory for permission - reasons (/var/log is writable only by - root), you should usually create a directory named - /var/log/package and place your log + reasons (/var/log is writable only by + root), you should usually create a directory named + /var/log/package and place your log files there.

@@ -6069,7 +6400,7 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Log files must be rotated occasionally so that they don't grow indefinitely; the best way to do this is to drop a log rotation configuration file into the directory - /etc/logrotate.d and use the facilities provided by + /etc/logrotate.d and use the facilities provided by logrotate.

The traditional approach to log files has been to set up @@ -6085,16 +6416,16 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq The use of logrotate, a program developed by Red Hat, is better, as it centralizes log management. It has both a configuration file - (/etc/logrotate.conf) and a directory where + (/etc/logrotate.conf) and a directory where packages can drop their individual log rotation - configurations (/etc/logrotate.d). + configurations (/etc/logrotate.d).

Here is a good example for a logrotate config file (for more information see ): -/var/log/foo/* { +/var/log/foo/*.log { rotate 12 weekly compress @@ -6103,7 +6434,7 @@ postrotate endscript } - This rotates all files under /var/log/foo, saves 12 + This rotates all files under /var/log/foo, saves 12 compressed generations, and forces the daemon to reload its configuration information after the log rotation.

@@ -6203,7 +6534,7 @@ endscript allocated one. Once you have been allocated one you must either make the package depend on a version of the base-passwd package with the id present in - /etc/passwd or /etc/group, or arrange for + /etc/passwd or /etc/group, or arrange for your package to create the user or group itself with the correct id (using adduser) in its preinst or postinst. (Doing it in @@ -6218,7 +6549,7 @@ endscript that a dynamically allocated id can be used. In this case you should choose an appropriate user or group name, discussing this on debian-devel and checking - with the base system maintainer that it is unique and that + with the Daemons

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

@@ -6357,18 +6688,18 @@ done

- The configuration file /etc/inetd.conf must not be + 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. See their documentation + DebianNet.pm Perl module. See their documentation for details on how to add entries.

If a package wants to install an example entry into - /etc/inetd.conf, the entry must be preceded with + /etc/inetd.conf, the entry must be preceded with exactly one hash character (#). Such lines are - treated as `commented out by user' by the + treated as "commented out by user" by the update-inetd script and are not changed or activated during package updates.

@@ -6386,8 +6717,8 @@ done

- The files /var/run/utmp, /var/log/wtmp and - /var/log/lastlog must be installed writeable by + The files /var/run/utmp, /var/log/wtmp and + /var/log/lastlog must be installed writeable by group utmp. Programs which need to modify those files must be installed setgid utmp.

@@ -6415,13 +6746,13 @@ done Thus, every program that launches an editor or pager must use the EDITOR or PAGER environment variable to determine the editor or pager the user wishes to use. If these - variables are not set, the programs /usr/bin/editor - and /usr/bin/pager should be used, respectively. + variables are not set, the programs /usr/bin/editor + and /usr/bin/pager should be used, respectively.

These two files are managed through the dpkg - `alternatives' mechanism. Thus every package providing an + "alternatives" mechanism. Thus every package providing an editor or pager must call the update-alternatives script to register these programs. @@ -6430,12 +6761,12 @@ done

If it is very hard to adapt a program to make use of the EDITOR or PAGER variables, that program may be configured to - use /usr/bin/sensible-editor and - /usr/bin/sensible-pager as the editor or pager + use /usr/bin/sensible-editor and + /usr/bin/sensible-pager as the editor or pager program respectively. These are two scripts provided in the Debian base system that check the EDITOR and PAGER variables and launch the appropriate program, and fall back to - /usr/bin/editor and /usr/bin/pager if the + /usr/bin/editor and /usr/bin/pager if the variable is not set.

@@ -6443,7 +6774,7 @@ done A program may also use the VISUAL environment variable to determine the user's choice of editor. If it exists, it should take precedence over EDITOR. This is in fact what - /usr/bin/sensible-editor does. + /usr/bin/sensible-editor does.

@@ -6487,7 +6818,7 @@ http://localhost/cgi-bin/cgi-bin-name

HTML documents for a package are stored in - /usr/share/doc/package + /usr/share/doc/package and can be referred to as http://localhost/doc/package/filename @@ -6536,12 +6867,12 @@ http://localhost/doc/package/filename

- The mail spool is /var/mail and the interface to - send a mail message is /usr/sbin/sendmail (as per + The mail spool is /var/mail and the interface to + send a mail message is /usr/sbin/sendmail (as per the FHS). On older systems, the mail spool may be - physically located in /var/spool/mail, but all + physically located in /var/spool/mail, but all access to the mail spool should be via the - /var/mail symlink. The mail spool is part of the + /var/mail symlink. The mail spool is part of the base system and not part of the MTA package.

@@ -6585,10 +6916,10 @@ http://localhost/doc/package/filename using this privilege).

- /etc/aliases is the source file for the system mail + /etc/aliases is the source file for the system mail aliases (e.g., postmaster, usenet, etc.), it is the one which the sysadmin and postinst scripts may - edit. After /etc/aliases is edited the program or + edit. After /etc/aliases is edited the program or human editing it must call newaliases. All MTA packages must come with a newaliases program, even if it does nothing, but older MTA packages did not do @@ -6606,15 +6937,15 @@ http://localhost/doc/package/filename

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

If your package needs to know what hostname to use on (for example) outgoing news and mail messages which are generated - locally, you should use the file /etc/mailname. It + locally, you should use the file /etc/mailname. It will contain the portion after the username and @ (at) sign for email addresses of users on the machine (followed by a newline). @@ -6627,17 +6958,17 @@ http://localhost/doc/package/filename may wish to prompt the user even if it finds that this file exists. If the file does not exist, the package should prompt the user for the value (preferably using - debconf) and store it in /etc/mailname + debconf) and store it in /etc/mailname as well as using it in the package's configuration. The prompt should make it clear that the name will not just be used by that package. For example, in this situation the inn package could say something like: -Please enter the `mail name' of your system. This is the +Please enter the "mail name" of your system. This is the hostname portion of the address to be shown on outgoing news and mail messages. The default is syshostname, your system's host name. Mail -name [`syshostname']: +name ["syshostname"]: where syshostname is the output of hostname --fqdn. @@ -6650,7 +6981,7 @@ name [`syshostname']:

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

+ /etc/news.

There are some configuration issues that apply to a number @@ -6658,12 +6989,12 @@ name [`syshostname']: are: - /etc/news/organization + /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 + /etc/news/server

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

 @@ -6724,7 +7055,7 @@ name [`syshostname']: in their control data that they provide the virtual package x-terminal-emulator. They should also register themselves as an alternative for - /usr/bin/x-terminal-emulator, with a priority of + /usr/bin/x-terminal-emulator, with a priority of 20.

@@ -6748,7 +7079,10 @@ name [`syshostname']: "view" in a multiple-document interface (MDI).

- and runs the specified command. + and runs the specified command, + interpreting the entirity of the rest of the command + line as a command to pass straight to exec, in the + manner that xterm does.

@@ -6768,7 +7102,7 @@ name [`syshostname']: their control data that they provide the virtual package x-window-manager. They should also register themselves as an alternative for - /usr/bin/x-window-manager, with a priority + /usr/bin/x-window-manager, with a priority calculated as follows:

Start with a priority of 20.

 @@ -6784,6 +7118,15 @@ name [`syshostname']: points.

+ +

+ If the window manager complies with , + written by the , add 40 points. +

+

@@ -6822,7 +7165,7 @@ name [`syshostname']:

Fonts of any type supported by the X Window System - must be be in a separate binary package from any + must be in a separate binary package from any executables, libraries, or documentation (except that specific to the fonts shipped, such as their license information). If one or more of the fonts @@ -6847,24 +7190,24 @@ name [`syshostname']:

BDF fonts must be converted to PCF fonts with the bdftopcf utility (available in the - xutils package, gzipped, and + xutils package, gzipped, and placed in a directory that corresponds to their resolution:

100 dpi fonts must be placed in - /usr/X11R6/lib/X11/fonts/100dpi/. + /usr/X11R6/lib/X11/fonts/100dpi/.

75 dpi fonts must be placed in - /usr/X11R6/lib/X11/fonts/75dpi/. + /usr/X11R6/lib/X11/fonts/75dpi/.

Character-cell fonts, cursor fonts, and other low-resolution fonts must be placed in - /usr/X11R6/lib/X11/fonts/misc/. + /usr/X11R6/lib/X11/fonts/misc/.

@@ -6872,22 +7215,22 @@ name [`syshostname']:

Speedo fonts must be placed in - /usr/X11R6/lib/X11/fonts/Speedo/. + /usr/X11R6/lib/X11/fonts/Speedo/.

Type 1 fonts must be placed in - /usr/X11R6/lib/X11/fonts/Type1/. If font + /usr/X11R6/lib/X11/fonts/Type1/. If font metric files are available, they must be placed here as well.

- Subdirectories of /usr/X11R6/lib/X11/fonts/ + Subdirectories of /usr/X11R6/lib/X11/fonts/ other than those listed above must be neither - created nor used. (The PEX, CID, - and cyrillic directories are excepted for + created nor used. (The PEX, CID, + and cyrillic directories are excepted for historical reasons, but installation of files into these directories remains discouraged.)

@@ -6897,7 +7240,7 @@ name [`syshostname']:

Font packages may, instead of placing files directly in the X font directories listed above, provide - symbolic links in the font directory which point to + symbolic links in that font directory pointing to the files' actual location in the filesystem. Such a location must comply with the FHS.

@@ -6916,7 +7259,7 @@ name [`syshostname']:

- Fonts destined for the misc subdirectory + Fonts destined for the misc subdirectory should not be included in the same package as 75dpi or 100dpi fonts; instead, they should be provided in a separate package with -misc appended to @@ -6927,22 +7270,22 @@ name [`syshostname']:

Font packages must not provide the files - fonts.dir, fonts.alias, or - fonts.scale in a font directory: + fonts.dir, fonts.alias, or + fonts.scale in a font directory:

- fonts.dir files must not be provided at all. + fonts.dir files must not be provided at all.

- fonts.alias and fonts.scale + fonts.alias and fonts.scale files, if needed, should be provided in the directory - /etc/X11/fonts/fontdir/package.extension, + /etc/X11/fonts/fontdir/package.extension, where fontdir is the name of the subdirectory of - /usr/X11R6/lib/X11/fonts/ where the + /usr/X11R6/lib/X11/fonts/ where the package's corresponding fonts are stored (e.g., 75dpi or misc), package is the name of the package @@ -6967,7 +7310,7 @@ name [`syshostname']:

Font packages that provide one or more - fonts.scale files as described above must + fonts.scale files as described above must invoke update-fonts-scale on each directory into which they installed fonts before invoking @@ -6982,7 +7325,7 @@ name [`syshostname']:

Font packages that provide one or more - fonts.alias files as described above must + fonts.alias files as described above must invoke update-fonts-alias on each directory into which they installed fonts. This invocation must occur in both the @@ -7026,20 +7369,20 @@ name [`syshostname']:

Application defaults files must be installed in the - directory /etc/X11/app-defaults/ (use of a - localized subdirectory of /etc/X11/ as described + directory /etc/X11/app-defaults/ (use of a + localized subdirectory of /etc/X11/ as described in the X Toolkit Intrinsics - C Language Interface manual is also permitted). They must be registered as conffiles or handled as configuration files. Packages must not provide the - directory /usr/X11R6/lib/X11/app-defaults/. + directory /usr/X11R6/lib/X11/app-defaults/.

Customization of programs' X resources may also be supported with the provision of a file with the same name as that of the package placed in the - /etc/X11/Xresources/ directory, which must + /etc/X11/Xresources/ directory, which must registered as a conffile or handled as a configuration file.

@@ -7051,10 +7394,10 @@ name [`syshostname']:

Important: packages that install files into the - /etc/X11/Xresources/ directory must conflict with + /etc/X11/Xresources/ directory must conflict with xbase (<< 3.3.2.3a-2); if this is not done it is possible for the installing package to destroy a - previously-existing /etc/X11/Xresources file + previously-existing /etc/X11/Xresources file which had been customized by the system administrator.

@@ -7064,13 +7407,13 @@ name [`syshostname']:

Packages using the X Window System should not be - configured to install files under the /usr/X11R6/ + configured to install files under the /usr/X11R6/ directory unless they use imake. The - /usr/X11R6/ directory hierarchy should be + /usr/X11R6/ directory hierarchy should be regarded as deprecated for all packages except the X Window System itself, and those which use the imake program it provides, in which case the - packages may transition out of the /usr/X11R6/ + packages may transition out of the /usr/X11R6/ directory at the maintainer's discretion.

Imake-using programs are exempt because, @@ -7078,8 +7421,8 @@ name [`syshostname']: they use to locate resources and install themselves are derived wholly from the X Window System configuration. Thus, in the event that the X Window - System moves to /usr/X11R7/, - /usr/X12/, or just plain /usr/, all + System moves to /usr/X11R7/, + /usr/X12/, or just plain /usr/, all that is required for these programs is a recompile against the corresponding X Window System library development packages. @@ -7087,30 +7430,30 @@ name [`syshostname']: Programs that use GNU autoconf and automake are usually easily configured at - compile time to use /usr/ instead of - /usr/X11R6/, and this should be done whenever + compile time to use /usr/ instead of + /usr/X11R6/, and this should be done whenever possible. Configuration files for window managers and display managers should be placed in a subdirectory of - /etc/X11/ corresponding to the package name due + /etc/X11/ corresponding to the package name due to these programs' tight integration with the mechanisms of the X Window System. Application-level programs should - use the /etc/ directory unless otherwise mandated + use the /etc/ directory unless otherwise mandated by policy. The installation of files into subdirectories - of /usr/X11R6/include/X11/ and - /usr/X11R6/lib/X11/ is permitted but discouraged; + of /usr/X11R6/include/X11/ and + /usr/X11R6/lib/X11/ is permitted but discouraged; package maintainers should determine if subdirectories of - /usr/lib/ and /usr/share/ can be used + /usr/lib/ and /usr/share/ can be used instead. (The use of symbolic links from the - X11R6 directories to other FHS-compliant + X11R6 directories to other FHS-compliant locations is encouraged if the program is not easily configured to look elsewhere for its files.) Packages must not provide or install files into the directories - /usr/bin/X11/, /usr/include/X11/ or - /usr/lib/X11/. Files within a package should, + /usr/bin/X11/, /usr/include/X11/ or + /usr/lib/X11/. Files within a package should, however, make reference to these directories, rather than their X11R6-named counterparts - /usr/X11R6/bin/, /usr/X11R6/include/X11/ - and /usr/X11R6/lib/X11/, if the resources being + /usr/X11R6/bin/, /usr/X11R6/include/X11/ + and /usr/X11R6/lib/X11/, if the resources being referred to have not been moved to other FHS-compliant locations.

@@ -7152,13 +7495,20 @@ name [`syshostname']: Perl programs and modules + +

+ Perl programs and modules should follow the current Perl policy. +

+

- Perl programs and modules should follow the current Perl - policy as defined in the file found on - ftp.debian.org in - /debian/doc/package-developer/perl-policy.txt.gz - or your local mirror. In addition, it is included in the - debian-policy package. + The Perl policy can be found in the perl-policy + files in the debian-policy package. + They are also available from the Debian web mirrors at + + and from the Debian archive mirrors at + .

@@ -7166,21 +7516,28 @@ name [`syshostname']: 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 + Please refer to the "Debian Emacs Policy" for details of how to package emacs lisp programs.

+ +

+ The Emacs policy is available in + debian-emacs-policy.gz of the + emacsen-common package. + It is also available from the Debian web mirrors at + . +

Games

- The permissions on /var/games are mode 755, owner + The permissions on /var/games are mode 755, owner root and group root.

- +

Each game decides on its own security policy.

@@ -7206,7 +7563,7 @@ name [`syshostname']: data files or other static information made unreadable so that they can only be accessed through set-id programs provided. You should not do this in a Debian package: anyone can - download the .deb file and read the data from it, + download the .deb file and read the data from it, so there is no point making the files unreadable. Not making the files unreadable also means that you don't have to make so many programs set-id, which reduces the risk of a @@ -7214,10 +7571,10 @@ name [`syshostname']:

As described in the FHS, binaries of games should be - installed in the directory /usr/games. This also + installed in the directory /usr/games. This also applies to games that use the X Window System. Manual pages for games (X and non-X games) should be installed in - /usr/share/man/man6.

+ /usr/share/man/man6.

 @@ -7229,34 +7586,36 @@ name [`syshostname']:

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

+ 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 + associated manual page included in the same package. It is suggested that all configuration files also have a manual - page included as well. + page included as well. Manual pages for protocols and other + auxiliary things are optional.

- If no manual page is available for a particular program, - utility, function or configuration file and this is reported - as a bug to the Debian Bug Tracking System, a symbolic link - from the requested manual page to the manual page may be - provided. This symbolic link can be created from - debian/rules like this: - -ln -s ../man7/undocumented.7.gz \ - debian/tmp/usr/share/man/man[1-9]/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.

+ If no manual page is available, this is considered as a bug + and should be reported to the Debian Bug Tracking System (the + maintainer of the package is allowed to write this bug report + themselves, if they so desire). Do not close the bug report + until a proper manpage is available. +

+ It is not very hard to write a man page. See the + , + , the examples + created by debmake or dh_make, + the helper programs help2man, or the + directory /usr/share/doc/man-db/examples. +

+ +

You may forward a complaint about a missing manpage to the @@ -7265,23 +7624,24 @@ ln -s ../man7/undocumented.7.gz \ not in general consider the lack of a manpage to be a bug, we do; if they tell you that they don't consider it a bug you should leave the bug in our bug tracking system open - anyway.

+ anyway. +

- Manual pages should be installed compressed using gzip - -9.

+ 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 + is better to use a symbolic link than the .so feature, but there is no need to fiddle with the relevant - parts of the upstream source to change from .so to + parts of the upstream source to change from .so to symlinks: don't do it unless it's easy. You should not create hard links in the manual page directories, nor put - absolute filenames in .so directives. The filename - in a .so in a manpage should be relative to the + absolute filenames in .so directives. The filename + in a .so in a manpage should be relative to the base of the manpage tree (usually - /usr/share/man). If you do not create any links + /usr/share/man). If you do not create any links (whether symlinks, hard links, or .so directives) in the filesystem to the alternate names of the manpage, then you should not rely on man finding your @@ -7303,12 +7663,13 @@ ln -s ../man7/undocumented.7.gz \ Info documents

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

+ 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 file in its postinst + the Info dir file in its postinst script when called with a configure argument, for example: @@ -7320,7 +7681,7 @@ install-info --quiet --section Development Development \ It is a good idea to specify a section for the location of your program; this is done with the --section switch. To determine which section to use, you should look - at /usr/share/info/dir on your system and choose the most + at /usr/share/info/dir on your system and choose the most relevant (or create a new section if none of the current sections are relevant). Note that the --section flag takes two arguments; the first is a regular expression @@ -7347,9 +7708,10 @@ install-info --quiet --remove /usr/share/info/foobar.info Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. Text documentation should be installed in the directory - /usr/share/doc/package, where + /usr/share/doc/package, where package is the name of the package, and - compressed with gzip -9 unless it is small.

+ compressed with gzip -9 unless it is small. +

If a package comes with large amounts of documentation which @@ -7360,63 +7722,45 @@ install-info --quiet --remove /usr/share/info/foobar.info

It is often a good idea to put text information files - (READMEs, changelogs, and so forth) that come with - the source package in /usr/share/doc/package + (READMEs, changelogs, and so forth) that come with + the source package in /usr/share/doc/package in the binary package. However, you don't need to install the instructions for building and installing the package, of course!

- Files in /usr/share/doc should not be referenced by - any program, and the system administrator should be able to - 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/ with symbolic links - from /usr/share/doc/package/. + Packages must not require the existance of any files in + /usr/share/doc/ in order to function + +

+ The system administrator should be able to + delete files in /usr/share/doc/ 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/ with symbolic links from + /usr/share/doc/package.

- - - - Accessing the documentation +

+ /usr/share/doc/package may be a symbolic + link to another directory in /usr/share/doc only if + the two packages both come from the same source and the + first package Depends on the second. +

Former Debian releases placed all additional documentation - in /usr/doc/package. To realize a - smooth migration to - /usr/share/doc/package, each package - must maintain a symlink /usr/doc/package - that points to the new location of its documentation in - /usr/share/doc/packageThese - symlinks will be removed in the future, but they have to be - there for compatibility reasons until all packages have - moved and the policy is changed accordingly.. - The symlink must be created when the package is installed; - it cannot be contained in the package itself due to problems - with dpkg. One reasonable way to accomplish - this is to put the following in the package's - postinst -

- The debhelper script - dh_installdocs does this automatically. -

- : - -if [ "$1" = "configure" ]; then - if [ -d /usr/doc -a ! -e /usr/doc/package \ - -a -d /usr/share/doc/package ]; then - ln -sf ../share/doc/package /usr/doc/package - fi -fi - - and the following in the package's prerm: - -if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ - -a -L /usr/doc/package ]; then - rm -f /usr/doc/package -fi - + in /usr/doc/package. This has been + changed to /usr/share/doc/package, + and packages must not put documentation in the directory + /usr/doc/package. +

At this phase of the transition, we no longer require a + symbolic link in /usr/doc/. At a later point, + policy shall change to make the symbolic links a bug.

+

@@ -7432,7 +7776,7 @@ fi markup format that can be converted to various other formats you should if possible ship HTML versions in a binary package, in the directory - /usr/share/doc/appropriate-package or + /usr/share/doc/appropriate-package or its subdirectories.

The rationale: The important thing here is that HTML @@ -7454,27 +7798,25 @@ fi

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file - /usr/share/doc/package/copyright. This + /usr/share/doc/package/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 - modifications were made in the Debian version of the package - compared to the upstream one. It should name the original + sources (if any) were obtained. It should name the original authors of the package and the Debian maintainer(s) who were involved with its creation.

A copy of the file which will be installed in - /usr/share/doc/package/copyright should - be in debian/copyright in the source package. + /usr/share/doc/package/copyright should + be in debian/copyright in the source package.

- /usr/share/doc/package may be a symbolic - link to another directory in /usr/share/doc only if + /usr/share/doc/package may be a symbolic + link to another directory in /usr/share/doc only if the two packages both come from the same source and the first package Depends on the second. These rules are important because copyrights must be extractable by @@ -7484,18 +7826,18 @@ fi

Packages distributed under the UCB BSD license, the Artistic license, the GNU GPL, and the GNU LGPL should refer to the - files /usr/share/common-licenses/BSD, - /usr/share/common-licenses/Artistic, - /usr/share/common-licenses/GPL, and - /usr/share/common-licenses/LGPL respectively, + files /usr/share/common-licenses/BSD, + /usr/share/common-licenses/Artistic, + /usr/share/common-licenses/GPL, and + /usr/share/common-licenses/LGPL respectively, rather than quoting them in the copyright file.

- You should not use the copyright file as a general README + 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.

+ installed in /usr/share/doc/package/README or + README.Debian or some other appropriate place.

@@ -7504,34 +7846,76 @@ fi

Any examples (configurations, source files, whatever), should be installed in a directory - /usr/share/doc/package/examples. These + /usr/share/doc/package/examples. These files should not be referenced by any program: they're there for the benefit of the system administrator and users as documentation only. Architecture-specific example files should be installed in a directory - /usr/lib/package/examples with symbolic + /usr/lib/package/examples with symbolic links to them from - /usr/share/doc/package/examples, or the + /usr/share/doc/package/examples, or the latter directory itself may be a symbolic link to the former.

+ +

+ If the purpose of a package is to provide examples, then the + example files may be installed into + /usr/share/doc/package. +

- + Changelog files +

+ The Debian changelog file (debian/changelog) should + explain briefly what modifications were made in the Debian version + of the package compared to the upstream one. Other changes and + updates to the package should also be documented in this file. +

+ +

+ Mistakes in changelogs are usually best rectified by + making a new changelog entry rather than "rewriting history" + by editing old changelog entries. +

+ +

+ The format of the debian/changelog file is described + in . In non-experimental packages you must + use a format for debian/changelog which is supported + by the most recent released version of dpkg. +

+ If you wish to use an alternative format, you may do so as + long as you include a parser for it in your source package. + The parser must have an API compatible with that expected by + dpkg-genchanges and dpkg-gencontrol. + If there is general interest in the new format, you should + contact the dpkg maintainer to have the + parser script for it included in the dpkg + package. (You will need to agree that the parser and its + manpage may be distributed under the GNU GPL, just as the rest + of dpkg is.) +

+ +

+

Packages that are not Debian-native must contain a - compressed copy of the debian/changelog file from + compressed copy of the debian/changelog file from the Debian source tree in - /usr/share/doc/package with the name - changelog.Debian.gz. If an upstream changelog is - available, it should be accessible as - /usr/share/doc/package/changelog.gz in + /usr/share/doc/package with the name + changelog.Debian.gz. +

+ +

+ If an upstream changelog is available, it should be accessible as + /usr/share/doc/package/changelog.gz in plain text. If the upstream changelog is distributed in HTML, it should be made available in that form as - /usr/share/doc/package/changelog.html.gz - and a plain text changelog.gz should be generated + /usr/share/doc/package/changelog.html.gz + and a plain text changelog.gz should be generated from it using, for example, lynx -dump -nolist. If the upstream changelog files do not already conform to this naming convention, then this may be achieved either by @@ -7556,10 +7940,11 @@ fi the Debian changelog and the upstream one because there is no separate upstream maintainer then that changelog should usually be installed as - /usr/share/doc/package/changelog.gz; if + /usr/share/doc/package/changelog.gz; if there is a separate upstream maintainer, but no upstream changelog, then the Debian changelog should still be called - changelog.Debian.gz.

+ changelog.Debian.gz.

+ @@ -7586,7 +7971,7 @@ fi precedence. The remaining chapters of the old Packaging Manual have also not been read in detail to ensure that there are not parts which have been left out. Both of these will be - done in due course. + done in due course.

@@ -7609,7 +7994,7 @@ fi

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

@@ -7619,13 +8004,13 @@ fi dselect's core and the access method scripts it uses to actually install the selected packages, and describes how to create a new access method.

- +

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

+

The utility programs which are provided with dpkg @@ -7634,23 +8019,13 @@ fi install-info, are not described in detail here - please see their manpages.

- -

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

- +

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

- +

The Debian version of the FSF's GNU hello program is provided as an example for people wishing to create Debian @@ -7664,31 +8039,31 @@ fi Binary packages (from old Packaging Manual) - +

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

- +

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

- +

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

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

All manipulation of binary package files is done by dpkg-deb; it's the only program that has @@ -7698,30 +8073,30 @@ fi dpkg-deb and invoke that instead with the same arguments.)

- +

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

- +

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

- +

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

- +

You need to add one special directory to the root of the miniature filesystem tree you're creating: @@ -7729,28 +8104,28 @@ fi information files, notably the binary package control file (see ).

- +

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

- +

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

- +

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

- +

See the manpage for details of how to examine the contents of this newly-created file. You may find the @@ -7771,7 +8146,7 @@ fi Package control information files - +

The control information portion of a binary package is a collection of files with names known to dpkg. @@ -7780,23 +8155,23 @@ fi installing or removing the package; others are scripts which the package maintainer wants dpkg to run.

- +

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

- +

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

- +

control - +

This is the key description file used by dpkg. It specifies the package's name @@ -7804,7 +8179,7 @@ fi states its relationships with other packages, and so forth. See .

- +

It is usually generated automatically from information in the source package by the @@ -7812,12 +8187,12 @@ fi assistance from dpkg-shlibdeps. See .

- + postinst, preinst, postrm, prerm - +

These are exectuable files (usually scripts) which dpkg runs during installation, upgrade @@ -7828,7 +8203,7 @@ fi how they are called are in .

- +

It is very important to make these scripts idempotent. @@ -7844,13 +8219,13 @@ fi unforeseen circumstance happens you don't leave the user with a badly-broken package.

- +

The maintainer scripts are guaranteed to run with a controlling terminal and can interact with the user. If they need to prompt for passwords, do full-screen interaction or something similar you should do these - things to and from /dev/tty, since + things to and from /dev/tty, since dpkg will at some point redirect scripts' standard input and output so that it can log the installation process. Likewise, because these scripts @@ -7860,27 +8235,27 @@ fi output is printed immediately rather than being buffered.

- +

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

 - + conffiles - +

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

 - + shlibs - +

This file contains a list of the shared libraries supplied by the package, with dependency details for @@ -7892,7 +8267,7 @@ fi

- + The main control information file: control @@ -7900,20 +8275,20 @@ fi

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

-

+

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

-

+

The fields in binary package control files are: @@ -7957,9 +8332,9 @@ fi

Installed-Size

- + - +

A description of the syntax of control files and the purpose of these fields is available in . @@ -7971,7 +8346,7 @@ fi

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

The rationale is that there is some information conveyed @@ -7989,70 +8364,64 @@ fi Source packages (from old Packaging Manual) -

+

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

-

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

- - Tools for processing source packages + Tools for processing source packages -

+

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

-

+

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

-

+

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

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

+

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

-

+

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

-

- with the filename.tar.gz and - filename.diff.gz (if applicable) in +

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

-

+

To create a packed source archive it is typically invoked: dpkg-source -b package-version @@ -8060,34 +8429,34 @@ fi

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

-

+

See also .

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

+

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

-

+

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

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

- This program is usually called from debian/rules +

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

-

+

This is usually done just before the files and directories in the temporary directory tree where the package is being built have their permissions and ownerships set and the package is constructed using @@ -8156,29 +8525,29 @@ fi .

-

+

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

-

+

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

-

+

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

-

+

Sources which build several binaries will typically need something like: @@ -8189,32 +8558,32 @@ fi tells it which package's control file should be generated.

-

+

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

 - + dpkg-shlibdeps - calculates shared library dependencies -

- This program is usually called from debian/rules +

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

-

+

Its arguments are executables.

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

They may be specified either in the locations in the @@ -8226,7 +8595,7 @@ fi be included in the binary package's control file.

-

+

If some of the found shared libraries should only warrant a Recommends or Suggests, or if some warrant a Pre-Depends, this can be achieved @@ -8235,26 +8604,26 @@ fi takes effect until the next -d.)

-

+

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

-

+

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

-

+

Sources which produce several binary packages with different shared library dependency requirements can use the -pvarnameprefix option to override - the default shlib: prefix (one invocation of + the default shlibs: prefix (one invocation of dpkg-shlibdeps per setting of this option). They can thus produce several sets of dependency variables, each of the form @@ -8277,101 +8646,101 @@ fi binary package control files.

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

+

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

-

+

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

-

+

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

-

+

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

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

+

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

-

+

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

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

+

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

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

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

- + The Debianised source tree -

+

The source archive scheme described later is intended to allow a Debianised source tree with some associated control information to be reproduced and transported easily. The @@ -8382,30 +8751,30 @@ fi scripts.

-

+

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

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

+

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

-

+

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

- Since an interactive debian/rules script makes it + Since an interactive debian/rules script makes it impossible to autocompile that package and also makes it hard for other people to reproduce the same binary package, all required targets have to be @@ -8416,8 +8785,8 @@ fi targets depend on must also be non-interactive.

-

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

+ The targets which are required to be present are: build @@ -8429,7 +8798,7 @@ fi built after this has taken place, so that it can be built without rerunning the configuration.

- +

A package may also provide both of the targets build-arch and build-indep. The @@ -8450,16 +8819,16 @@ fi build-indep that are provided in the rules file.

- -

+ +

If one or both of the targets build-arch and build-indep are not provided, then invoking - debian/rules with one of the not-provided + debian/rules with one of the not-provided targets as arguments should produce a exit status code of 2. Usually this is provided automatically by make if the target is missing.

- +

For some packages, notably ones where the same source tree is compiled in different ways to produce @@ -8474,18 +8843,18 @@ fi binary package out of each.

-

+

The targets build, build-arch and build-indep 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 @@ -8495,10 +8864,10 @@ fi again it will not rebuild the whole program.

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

The binary target should be all that is @@ -8511,14 +8880,14 @@ fi those which are not.

-

+

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

-

+

Both binary-* targets should depend on the build target, above, so that the package is built if it has not been already. It @@ -8529,7 +8898,7 @@ fi 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, @@ -8538,20 +8907,20 @@ fi succeed.

-

+

describes how to construct binary packages.

-

+

The binary targets must be invoked as root.

- + clean - +

This should undo any effects that the build and binary targets @@ -8561,7 +8930,7 @@ fi to be non-interactive.

-

+

If a build file is touched at the end of the build target, as suggested above, it must be removed as the first thing that @@ -8571,7 +8940,7 @@ fi already done.

-

+

The clean target must be invoked as root if binary has been invoked since the last clean, or if @@ -8580,10 +8949,10 @@ fi example).

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

This target fetches the most recent version of the original source package from a canonical archive @@ -8593,32 +8962,32 @@ fi in the current directory.

-

+

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

-

+

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

- +

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

- -

- Additional targets may exist in debian/rules, + +

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

- +

The architecture we build on and build for is determined by make variables via dpkg-architecture (see ). You can @@ -8631,7 +9000,7 @@ fi

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

+ specification string)

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

@@ -8641,20 +9010,20 @@ fi DEB_*_GNU_TYPE)

- +

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

- +

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

- +

It is important to understand that the DEB_*_ARCH string does only determine which Debian architecture we @@ -8663,17 +9032,17 @@ fi used for that.

- - - debian/control + + + debian/control -

+

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

-

+

It is a series of sets of control fields, each syntactically similar to a binary package control file. The sets are separated by one or more blank lines. The @@ -8682,12 +9051,12 @@ fi that the source tree builds.

-

+

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

-

+

The general (binary-package-independent) fields are: @@ -8699,7 +9068,7 @@ fi

Section and - Priority + Priority (classification, mandatory)

@@ -8713,10 +9082,10 @@ fi

Standards-Version

- + -

+

The per-binary-package fields are: @@ -8746,16 +9115,16 @@ fi -

+

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

-

+

The fields here may contain variable references - their values will be substituted by dpkg-gencontrol, dpkg-genchanges @@ -8766,20 +9135,20 @@ fi

User-defined fields -

+

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

-

+

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

-

+

Fields in the main source control information file with names starting X, followed by one or more of the letters BCS and a hyphen -, will @@ -8792,7 +9161,7 @@ fi (.changes) files.

-

+

For example, if the main source information control file contains the field @@ -8805,13 +9174,13 @@ fi

- + - debian/changelog + debian/changelog -

+

This file records the changes to the Debian-specific parts of the package @@ -8825,40 +9194,40 @@ fi .

-

+

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. See + field in the .changes file for the upload. See . It is not possible to specify an urgency containing commas; commas are used to separate keyword=value settings in @@ -8867,7 +9236,7 @@ fi 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 @@ -8876,17 +9245,17 @@ fi used here to separate groups of changes, if desired.

-

+

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

-

+

The date should be in RFC822 format

@@ -8898,32 +9267,32 @@ fi 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 +

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

-

+

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

- + Defining alternative changelog formats -

+

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

-

+

In order to have dpkg-parsechangelog run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: @@ -8936,19 +9305,19 @@ fi Changelog format names are non-empty strings of alphanumerics.

-

+

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

-

+

The parser will be invoked with the changelog open on standard input at the start of the file. It should read the file (it may seek if it wishes) to determine the @@ -8964,7 +9333,7 @@ fi changelog.

-

+

The fields are: @@ -8977,7 +9346,7 @@ fi

Distribution (mandatory) -

+

Urgency (mandatory)

@@ -8999,7 +9368,7 @@ fi -

+

If several versions are being returned (due to the use of -v), the urgency value should be of the highest urgency code listed at the start of any of the @@ -9009,87 +9378,89 @@ fi date should always be from the most recent version.

-

+

For the format of the Changes field see .

-

+

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

-

+

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

-

+

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

-

+

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

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

+

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

-

- The is usually generated and modified dynamically by - debian/rules targets; in this case it must be +

+ This file is usually generated and modified dynamically by + debian/rules targets, in which case it must be removed by the clean target.

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

+ format of debian/substvars.

 - - debian/files + + 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. + when it generates a .changes file.

-

+

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

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

@@ -9099,30 +9470,30 @@ fi start of the binary target.

-

+

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

-

+

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

+ the file to the list in debian/files.

 - - debian/tmp + + debian/tmp -

+

This is the canonical temporary location for the construction of binary packages by the binary - target. The directory tmp serves as the root of + target. The directory tmp serves as the root of the filesystem tree as it is being constructed (for example, by using the package's upstream makefiles install targets and redirecting the output there), and it also @@ -9130,34 +9501,34 @@ fi id="pkg-bincreating">.

-

+

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

-

- Whatever tmp directories are created and used by +

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

 - - + + Source packages as archives -

+

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

-

+

Debian source control file - .dsc - +

This file contains a series of fields, identified and separated just like the fields in the control file of @@ -9194,7 +9565,7 @@ fi -

+

The source package control file is generated by dpkg-source when it builds the source archive, from other files in the source package, @@ -9202,34 +9573,34 @@ fi the files and directories in the other parts of the source package, as described below.

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

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

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

This is a unified context diff (diff -u) giving the changes which are required to turn the @@ -9241,53 +9612,53 @@ fi or renamed.

-

+

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

-

+

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

 - -

+ +

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

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

+

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

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

-

Rename the .orig directory to - package-version.

+

Rename the .orig directory to + package-version.

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

Apply the diff using patch -p0.

@@ -9296,18 +9667,18 @@ fi source code alongside the Debianised version.

 - -

+ +

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

- + Restrictions on objects in source packages -

+

The source package may not contain any hard links

@@ -9331,11 +9702,11 @@ fi

-

+

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

Changing the targets of symbolic links.

-

Creating directories, other than debian.

+

Creating directories, other than debian.

Changes to the contents of binary files.

 Changes which cause dpkg-source to @@ -9376,16 +9747,16 @@ fi dpkg-source, are:

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

 + debian/rules) and directories.

-

- The debian directory and debian/rules +

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

@@ -9395,26 +9766,26 @@ fi fields (from old Packaging Manual) -

+

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

- + Syntax of control files -

+

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

-

+

Each paragraph is a series of fields and values; each field consists of a name, followed by a colon and the value. It ends at the end of the line. Horizontal whitespace (spaces @@ -9423,14 +9794,14 @@ fi 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, @@ -9439,34 +9810,32 @@ fi relationships.

-

+

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

-

+

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

-

+

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

+ package, or whose omission may cause problems. +

- + List of fields - + Package -

+

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

-

+

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

This is a @@ -9489,40 +9858,40 @@ fi the package you're building (or referring to, in other fields) is already using uppercase.

 - + Version -

+

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

- + Architecture -

+

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

-

+

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

-

+

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

-

- In the main debian/control file in the source +

+ In the main debian/control file in the source package, or in the source package control file - .dsc, a list of architectures (separated by + .dsc, a list of architectures (separated by spaces) is also allowed, as is the special value any. A list indicates that the source will build an architecture-dependent package, and will only work @@ -9534,30 +9903,30 @@ fi whatever the current build architecture is.

-

- In a .changes file the Architecture +

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

-

+

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

- + Maintainer -

+

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

-

+

If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a @@ -9567,36 +9936,36 @@ fi end, and bringing the email address forward).

-

- In a .changes file or parsed changelog data this +

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

-

+

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

 - + Source -

+

This field identifies the source package name.

-

+

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

-

+

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

@@ -9611,61 +9980,61 @@ fi name and version as the binary package.

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

+

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

 - + Description -

+

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

-

- In a .changes file it contains a summary of the +

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

 - + Essential -

+

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

-

+

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

 - + Section and Priority -

+

These two fields classify the package. The Priority represents how important that it is that the user have it installed; the Section @@ -9673,55 +10042,52 @@ fi been classified.

-

- When they appear in the debian/control file these +

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

-

+

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

-

+

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

-

- These fields may appear in binary package control files, +

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

 - + Binary -

+

This field is a list of binary packages.

-

- When it appears in the .dsc file it is the list +

+ When it appears in the .dsc file it is the list of binary packages which a source package can produce. It does not necessarily produce all of these binary packages for every architecture. The source control file doesn't @@ -9729,12 +10095,12 @@ fi which of the binary packages.

-

- When it appears in a .changes file it lists the +

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

-

+

The syntax is a list of binary packages separated by commas. @@ -9742,39 +10108,39 @@ fi A space after each comma is conventional.

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

+ only spaces in the .changes file.

 - + Installed-Size -

+

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

-

+

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

 - + Files -

+

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

-

- In the .dsc (Debian source control) file each +

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

-

- In the .changes file this contains one line per +

+ In the .changes file this contains one line per file being uploaded. Each line contains the MD5 checksum, size, section and priority and the filename. The section and priority are the values of the corresponding fields in @@ -9799,7 +10165,7 @@ fi be installed properly.

-

+

The special value byhand for the section in a .changes file indicates that the file in question is not an ordinary package file and must by installed by @@ -9807,58 +10173,57 @@ fi byhand the priority should be -.

-

+

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

+ .dsc file and diff which are being uploaded.

 - - + + Standards-Version -

- The most recent version of the standards (the - dpkg programmers' and policy manuals and - associated texts) with which the package complies. This +

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

-

+

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

 - - + + Distribution -

- In a .changes file or parsed changelog output +

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

-

+

Current distribution values are: stable -

- This is the current `released' version of Debian +

+ This is the current "released" version of Debian GNU/Linux. A new version is released approximately every 3 months after the development code has been frozen for a month of testing. Once the @@ -9868,7 +10233,7 @@ fi (for example: 1.2r1 becomes 1.2r2 then 1.2r3, etc).

- + unstable

@@ -9879,7 +10244,7 @@ fi tree. Download from this distribution at your own risk.

 - + contrib

@@ -9893,7 +10258,7 @@ fi distributions. Use your best judgement in downloading from this Distribution.

 - + non-free

@@ -9902,7 +10267,7 @@ fi criteria for inclusion in the main Debian distribution as defined by the Policy Manual. Again, use your best judgement in downloading from this Distribution.

- + experimental

@@ -9914,13 +10279,13 @@ fi of the Debian distribution tree. Download at your own risk.

 - + frozen

From time to time, (currently, every 3 months) the unstable distribution enters a state of - `code-freeze' in anticipation of release as a + "code-freeze" in anticipation of release as a stable version. During this period of testing (usually 4 weeks) only fixes for existing or newly-discovered bugs will be allowed. @@ -9933,11 +10298,11 @@ fi unstable. Likewise, installations into frozen should also go into unstable.

 - + Urgency -

+

This is a description of how important it is to upgrade to this version from previous ones. It consists of a single keyword usually taking one of the values LOW, @@ -9949,72 +10314,72 @@ fi

-

- This field appears in the .changes file and in +

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

-

+

Urgency keywords are not case-sensitive.

 - + Date -

+

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

 - + Format -

- This field occurs in .changes files, and +

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

 - + Changes -

- In a .changes file or parsed changelog this field +

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

-

+

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

-

+

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

-

+

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

 - + Filename and MSDOS-Filename -

+

These fields in Packages files give the filename(s) of (the parts of) a package in the distribution directories, relative to the root of the @@ -10022,23 +10387,23 @@ fi several parts the parts are all listed in order, separated by spaces.

 - + Size and MD5sum -

- These fields in Packages files give the size (in +

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

 - + Status -

+

This field in dpkg's status file records whether the user wants a package installed, removed or left alone, whether it is broken (requiring @@ -10046,35 +10411,35 @@ fi system is. Each of these pieces of information is a single word.

 - + Config-Version -

+

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

 - + Conffiles -

+

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

 - + Obsolete fields -

+

These are still recognised by dpkg but should not appear anywhere any more. - + Revision Package-Revision Package_Revision @@ -10084,11 +10449,11 @@ fi at one point in a separate control file field. This field went through several names.

- + Recommended

Old name for Recommends

 - + Optional

Old name for Suggests.

 @@ -10105,18 +10470,18 @@ fi (from old Packaging Manual) -

+

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

-

+

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

-

+

The easy method is to ship a best-effort configuration in the package, and use dpkg's conffile mechanism to handle updates. If the user is unlikely to want to edit the @@ -10125,7 +10490,7 @@ fi 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 @@ -10133,12 +10498,12 @@ fi appropriate if the file is likely to need to be different on each system.

- + Automatic handling of configuration files by dpkg -

+

A package may contain a control area file called conffiles. This file should be a list of filenames of configuration files needing automatic handling, separated @@ -10147,14 +10512,14 @@ fi package.

-

+

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

-

+

For each file it checks to see whether the version of the file included in the package is the same as the one that was included in the last version of the package (the one that is @@ -10163,7 +10528,7 @@ fi version.

-

+

If neither the user nor the package maintainer has changed the file, it is left alone. If one or the other has changed their version, then the changed version is preferred - i.e., @@ -10176,20 +10541,20 @@ fi and must resolve the differences themselves.

-

+

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

-

+

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

-

+

However, note that dpkg will not replace a conffile that was removed by the user (or by a script). This is necessary because with some programs a @@ -10198,38 +10563,38 @@ fi kept that way if the user did it.

-

+

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

 - + Fully-featured maintainer script configuration handling -

+

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

-

+

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

-

+

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

-

+

If you discover a bug in the program which generates the configuration file, or if the format of the file changes from one version to the next, you will have to arrange for @@ -10242,11 +10607,11 @@ fi deal with them correctly.

-

+

If you do go down this route it's probably a good idea to make the program that generates the configuration file(s) a - separate program in /usr/sbin, by convention called - packageconfig and then run that if + separate program in /usr/sbin, by convention called + packageconfig and then run that if appropriate from the post-installation script. The packageconfig program should not unquestioningly overwrite an existing configuration - if its @@ -10256,20 +10621,20 @@ fi already exists, and require a --force flag to overwrite it.

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

+

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

-

+

For example, there are several versions of the vi editor, and there is no reason to prevent all of them from being installed at once, each under their own name @@ -10278,65 +10643,65 @@ fi refer to something, at least by default.

-

+

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

-

+

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

-

+

See the manpage for details.

-

+

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

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

+

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

-

+

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

-

+

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

-

+

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

-

+

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

-

+

The postrm has to do the reverse: if [ remove = "$1" ]; then @@ -10358,7 +10723,7 @@ fi

-

+

Do not attempt to divert a file which is vitally important for the system's operation - when using dpkg-divert there is a time, after it has been diverted but before @@ -10368,3 +10733,4 @@ fi +