X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=ae7149ff130ac8c9b8bc39ccbe62db152ed9a82f;hb=6e1b2d9c86e05355da2081276decbf3ae3fce4c2;hp=e6f15f2af77792b4177189f8f09ffde9213663fd;hpb=465e7f040503196734b3c0d202f82b762a071aa1;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index e6f15f2..ae7149f 100644 --- a/policy.sgml +++ b/policy.sgml @@ -46,7 +46,7 @@ . You can also obtain it by writing to the Free Software Foundation, Inc., - 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

@@ -157,7 +157,10 @@

This manual is distributed via the Debian package - . + + (packages.debian.org + /debian-policy).

@@ -165,14 +168,21 @@ the Debian web mirrors at . + ( + www.debian.org + /doc/debian-policy/) Also available from the same directory are several other - formats: policy.html.tar.gz, policy.pdf.gz - and policy.ps.gz. + formats: policy.html.tar.gz + (/doc/debian-policy/policy.html.tar.gz), + policy.pdf.gz + (/doc/debian-policy/policy.pdf.gz) + and policy.ps.gz + (/doc/debian-policy/policy.ps.gz).

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

@@ -251,7 +261,7 @@ is the Debian Developer's Reference. This document describes procedures and resources for Debian developers, but it is not normative; rather, it includes things that don't - belong into the Policy, such as best practices for developers. + belong in the Policy, such as best practices for developers.

@@ -272,7 +282,7 @@

The Debian GNU/Linux system is maintained and distributed as a collection of packages. Since there are so many of - them (currently well over 6000), they are split into + them (currently well over 15000), they are split into sections and given priorities to simplify the handling of them.

@@ -282,8 +292,8 @@ system, but not every package we want to make accessible is free in our sense (see the Debian Free Software Guidelines, below), or may be imported/exported without - restrictions. Thus, the archive is split into the sections - based on their licenses and other restrictions. + restrictions. Thus, the archive is split into the distribution + areas or categories based on their licenses and other restrictions.

@@ -300,16 +310,17 @@

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

- Packages in the other sections are not considered to be part - of the Debian distribution, although we support their use and - provide infrastructure for them (such as our bug-tracking - system and mailing lists). This Debian Policy Manual applies - to these packages as well. + Packages in the other distribution areas (contrib, + non-free) are not considered to be part of the Debian + distribution, although we support their use and provide + infrastructure for them (such as our bug-tracking system and + mailing lists). This Debian Policy Manual applies to these + packages as well.

@@ -411,15 +422,14 @@ - Sections + Categories - The main section + The main category

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

@@ -443,37 +453,17 @@

-

- Similarly, the packages in non-US/main - - - must not require a package outside of main - or non-US/main for compilation or - execution, - - - must not be so buggy that we refuse to support them, - - - must meet all policy requirements presented in this - manual. - - -

- - The contrib section + The contrib category

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

- In addition, the packages in contrib and - non-US/contrib + In addition, the packages in contrib must not be so buggy that we refuse to support them, @@ -486,15 +476,10 @@

-

- Furthermore, packages in contrib must not require - a package in a non-US section for compilation or - execution. -

Examples of packages which would be included in - contrib or non-US/contrib are: + contrib are: free packages which require contrib, @@ -511,18 +496,17 @@ - The non-free section + The non-free category

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

- In addition, the packages in non-free and - non-US/non-free + In addition, the packages in non-free must not be so buggy that we refuse to support them, @@ -543,28 +527,6 @@

- - The non-US sections - -

- 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 - restricted license also need to be stored on "non-us", - since that is located in a country where it is not allowed - to patent algorithms. -

- -

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

- @@ -647,53 +609,46 @@ - Subsections + Sections

- The packages in the sections main, + The packages in the categories main, contrib and non-free are grouped further - into subsections to simplify handling. + into sections to simplify handling.

- The section and subsection for each package should be - specified in the package's Section control - record (see ). - However, the maintainer of the Debian archive - may override this selection to ensure the consistency of - the Debian distribution. The Section field - should be of the form: + The category and section for each package should be + specified in the package's Section control record + (see ). However, the maintainer of the + Debian archive may override this selection to ensure the + consistency of the Debian distribution. The + Section field should be of the form: - subsection if the package is in the - main section, + section if the package is in the + main category, - section/subsection if the package is in - the contrib or non-free section, - and - - - non-US, non-US/contrib or - non-US/non-free if the package is in - non-US/main, non-US/contrib or - non-US/non-free respectively. + segment/section if the package is in + the contrib or non-free + distribution areas.

The Debian archive maintainers provide the authoritative - list of subsections. At present, they are: - admin, base, comm, - contrib, devel, doc, + list of sections. At present, they are: + admin, comm, + devel, doc, editors, electronics, embedded, games, gnome, graphics, hamradio, interpreters, kde, libs, libdevel, mail, math, misc, net, news, - non-US, non-free, oldlibs, - otherosfs, perl, python + oldlibs, + otherosfs, perl, python, science, shells, sound, tex, text, utils, web, x11. @@ -712,19 +667,21 @@

- The following priority levels are recognised by the + The following priority levels are recognized by the Debian package management tools. required Packages which are necessary for the proper - functioning of the system. You must not remove these - packages or your system may become totally broken and - you may not even be able to use dpkg to - put things back. Systems with only the - required packages are probably unusable, but - they do have enough functionality to allow the - sysadmin to boot and install more software. + functioning of the system (usually, this means that + dpkg functionality depends on these packages). + Removing a required package may cause your + system to become totally broken and you may not even + be able to use dpkg to put things back, + so only do so if you know what you are doing. Systems + with only the required packages are probably + unusable, but they do have enough functionality to + allow the sysadmin to boot and install more software. important @@ -769,7 +726,7 @@ This contains all packages that conflict with others with required, important, standard or optional priorities, or are only likely to be useful if you - already know what they are or have specialised + already know what they are or have specialized requirements. @@ -856,11 +813,11 @@

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 - is up to the maintainer whether he/she wants to bother the - upstream maintainer to change the version numbers upstream, - too. + version, the date based portion of the version number + should be changed to the following format in such cases: + "19960501", "19961224". It is up to the maintainer whether + they want to bother the upstream maintainer to change + the version numbers upstream, too.

@@ -893,7 +850,7 @@ The maintainer must be specified in the Maintainer control field with their correct name and a working email address. If one person maintains - several packages, he/she should try to avoid having + several packages, they should try to avoid having different forms of their name and email address in the Maintainer fields of those packages.

@@ -907,7 +864,7 @@ If the maintainer of a package quits from the Debian project, "Debian QA Group" packages@qa.debian.org takes over the - maintainership of the package until someone else + maintainer-ship of the package until someone else volunteers for that task. These packages are called orphaned packages. The detailed procedure for doing this gracefully can @@ -1026,7 +983,33 @@ Packages are not required to declare any dependencies they have on other packages which are marked Essential (see below), and should not do so unless they depend on a - particular version of that package. + particular version of that package. +

+ Essential is defined as the minimal set of functionality + that must be available and usable on the system even + when packages are in an unconfigured (but unpacked) + state. This is needed to avoid unresolvable dependency + loops on upgrade. If packages add unnecessary + dependencies on packages in this set, the chances that + there will be an unresolvable + dependency loop caused by forcing these Essential + packages to be configured first before they need to be + is greatly increased. It also increases the chances + that frontends will be unable to + calculate an upgrade path, even if one + exists. +

+

+ Also, it's pretty unlikely that functionality from + Essential shall ever be removed (which is one reason why + care must be taken before adding to the Essential + packages set), but packages have been removed + from the Essential set when the functionality moved to a + different package. So depending on these packages + just in case they stop being essential does way + more harm than good. +

+

@@ -1079,10 +1062,7 @@ package names can be found in the debian-policy package. It is also available from the Debian web mirrors at - and from the Debian archive mirrors at - . + id="http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt">.

@@ -1098,15 +1078,15 @@

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 - disk usage very small. + on a new system. Only very few packages are allowed to form + part of the base system, in order to keep the required disk + usage very small.

- Most of these packages will have the priority value - required or at least important, and many - of them will be tagged essential (see below). + The base system consists of all those packages with priority + required or important. Many of them will + be tagged essential (see below).

@@ -1149,46 +1129,12 @@

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

The package installation scripts should avoid producing - output which it is unnecessary for the user to see and + output which is unnecessary for the user to see and should rely on dpkg to stave off boredom on the part of a user installing many packages. This means, amongst other things, using the --quiet option on @@ -1250,10 +1196,7 @@ debian-policy package. It is also available from the Debian web mirrors at - and from the Debian archive mirrors at - . + id="http://www.debian.org/doc/packaging-manuals/debconf_specification.html">.

@@ -1266,7 +1209,7 @@ . The config script might be run before the preinst script, and before the package is unpacked - or any of its dependencies or pre-dependancies are satisfied. + or any of its dependencies or pre-dependencies are satisfied. Therefore it must work using only the tools present in essential packages. Debconf or another tool that @@ -1277,6 +1220,13 @@

+

+ Packages which use the Debian Configuration management + specification must allow for translation of their messages + by using a gettext-based system such as the one provided by + the po-debconf package. +

+

Packages should try to minimize the amount of prompting they need to do, and they should ensure that the user @@ -1483,14 +1433,15 @@

- If you need to edit a Makefile where - GNU-style configure scripts are used, you - should edit the .in files rather than editing the + If you need to edit a Makefile where GNU-style + configure scripts are used, you 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. + Makefile! This makes it impossible for someone + else to later reconfigure the package without losing the + changes you made.

@@ -1501,7 +1452,14 @@

Changes in the Debian version of the package should be briefly explained in the Debian changelog file - debian/changelog. This includes modifications + debian/changelog. +

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

+ + This includes modifications made in the Debian package compared to the upstream one as well as other changes and updates to the package. @@ -1515,9 +1473,7 @@

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

@@ -1567,14 +1523,7 @@ keyword=value settings in the dpkg changelog format (though there is currently only one useful keyword, - urgency). - Recognised urgency values are low, - medium, high and emergency. - They have an effect on how quickly a package will be - considered for inclusion into the testing - distribution, and give an indication of the importance - of any fixes included in this upload. - + urgency).

@@ -1618,8 +1567,7 @@

The date should be in RFC822 format - This is generated by the 822-date - program. + This is generated by date -R. ; it should include the time zone specified numerically, with the time zone name or abbreviation optionally present as a comment in parentheses. @@ -1658,13 +1606,23 @@ 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 + man page may be distributed under the GNU GPL, just as the rest of dpkg is.)

- + + Copyright: debian/copyright +

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

+ Error trapping in makefiles @@ -1968,6 +1926,19 @@ possible is a good idea.

+ + patch (optional) + +

+ This target performs whatever additional actions are + required to make the source ready for editing (unpacking + additional upstream archives, applying patches, etc.). + It is recommended to be implemented for any package where + dpkg-source -x does not result in source ready + for additional modification. See + . +

+

@@ -2028,6 +1999,105 @@ or system information; the GNU style variables should be used for that.

+ + + debian/rules and + DEB_BUILD_OPTIONS + +

+ Supporting the standardized environment variable + DEB_BUILD_OPTIONS is recommended. This variable can + contain several flags to change how a package is compiled and + built. Each flag must be in the form flag or + flag=options. If multiple flags are + given, they must be separated by whitespace. + Some packages support any delimiter, but whitespace is the + easiest to parse inside a makefile and avoids ambiguity with + flag values that contain commas. + + flag must start with a lowercase letter + (a-z) and consist only of lowercase letters, + numbers (0-9), and the characters + - and _ (hyphen and underscore). + options must not contain whitespace. The same + tag should not be given multiple times with conflicting + values. Package maintainers may assume that + DEB_BUILD_OPTIONS will not contain conflicting tags. +

+ +

+ The meaning of the following tags has been standardized: + + noopt + + The presence of this tag means that the package should + be compiled 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 tag means that the debugging symbols should not be + stripped from the binary during installation, so that + debugging information may be included in the package. + + parallel=n + + This tag means that the package should be built using up + to n parallel processes if the package build + system supports this. + Packages built with make can often implement + this by passing the -jn option to + make. + + If the package build system does not support parallel + builds, this string must be ignored. If the package + build system only supports a lower level of concurrency + than n, the package should be built using as + many parallel processes as the package build system + supports. It is up to the package maintainer to decide + whether the package build times are long enough and the + package build system is robust enough to make supporting + parallel builds worthwhile. + + +

+ +

+ Unknown flags must be ignored by debian/rules. +

+ +

+ The following makefile snippet is an example of how one may + 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 (,$(filter noopt,$(DEB_BUILD_OPTIONS))) + CFLAGS += -O0 +else + CFLAGS += -O2 +endif +ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS))) + INSTALL_PROGRAM += -s +endif +ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) + NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) + MAKEFLAGS += -j$(NUMJOBS) +endif + +

+ @@ -2059,6 +2129,21 @@ format of debian/substvars.

+ + Optional upstream source location: debian/watch + +

+ This is an optional, recommended control file for the + uscan utility which defines how to automatically + scan ftp or http sites for newly available updates of the + package. This is used by and other Debian QA tools + to help with quality control and maintenance of the + distribution as a whole. +

+ + + Generated files list: debian/files @@ -2103,6 +2188,85 @@ the file to the list in debian/files.

 + + Convenience copies of code + +

+ Some software packages include in their distribution convenience + copies of code from other software packages, generally so that + users compiling from source don't have to download multiple + packages. Debian packages should not make use of these + convenience copies unless the included package is explicitly + intended to be used in this way. + For example, parts of the GNU build system work like this. + + If the included code is already in the Debian archive in the + form of a library, the Debian packaging should ensure that + binary packages reference the libraries already in Debian and + the convenience copy is not used. If the included code is not + already in Debian, it should be packaged separately as a + prerequisite if possible. + + Having multiple copies of the same code in Debian is + inefficient, often creates either static linking or shared + library conflicts, and, most importantly, increases the + difficulty of handling security vulnerabilities in the + duplicated code. + +

+ + + + Source package handling: + debian/README.source + +

+ If running dpkg-source -x on a source package + doesn't produce the source of the package, ready for editing, + and allow one to make changes and run + dpkg-buildpackage to produce a modified package + without taking any additional steps, creating a + debian/README.source documentation file is + recommended. This file should explain how to do all of the + following: + + Generate the fully patched source, in a form ready for + editing, that would be built to create Debian + packages. Doing this with a patch target in + debian/rules is recommended; see + . + Modify the source and save those modifications so that + they will be applied when building the package. + Remove source modifications that are currently being + applied when building the package. + Optionally, document what steps are necessary to + upgrade the Debian source package to a new upstream version, + if applicable. + + This explanation should include specific commands and mention + any additional required Debian packages. It should not assume + familiarity with any specific Debian packaging system or patch + management tools. +

+ +

+ This explanation may refer to a documentation file installed by + one of the package's build dependencies provided that the + referenced documentation clearly explains these tasks and is not + a general reference manual. +

+ +

+ debian/README.source may also include any other + information that would be helpful to someone modifying the + source package. Even if the package doesn't fit the above + description, maintainers are encouraged to document in a + debian/README.source file any source package with a + particularly complex or unintuitive source layout or build + system (for example, a package that builds the same source + multiple times to generate different binary packages). +

+ @@ -2141,10 +2305,11 @@ Each paragraph consists of a series of data fields; each field consists of the field name, followed by a colon and then the data/value associated with that field. It ends at - the end of the line. Horizontal whitespace (spaces and - tabs) may occur immediately before or after the value and is - ignored there; it is conventional to put a single space - after the colon. For example, a field might be: + the end of the (logical) line. Horizontal whitespace + (spaces and tabs) may occur immediately before or after the + value and is ignored there; it is conventional to put a + single space after the colon. For example, a field might + be: Package: libc6 @@ -2153,19 +2318,19 @@ Package: libc6

- Some fields' values may span several lines; in this case + Many fields' values may span several lines; in this case each continuation line must start with a space or a tab. Any trailing spaces or tabs at the end of individual - lines of a field value are ignored. + 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 must not appear inside names (of packages, - architectures, files or anything else) or version numbers, - or between the characters of multi-character version - relationships. + In fields where it is specified that lines may not wrap, + only a single line of data is allowed and whitespace is not + significant in a field body. Whitespace must not appear + inside names (of packages, architectures, files or anything + else) or version numbers, or between the characters of + multi-character version relationships.

@@ -2203,10 +2368,12 @@ Package: libc6 Source (mandatory) Maintainer (mandatory) + Uploaders Section (recommended) Priority (recommended) Build-Depends et al Standards-Version (recommended) + Homepage

@@ -2221,6 +2388,7 @@ Package: libc6 Essential Depends et al Description (mandatory) + Homepage

@@ -2235,8 +2403,13 @@ Package: libc6 generate control files for binary packages (see below), by dpkg-genchanges to generate the .changes file to accompany the upload, and by - dpkg-source when it creates the .dsc - source control file as part of a source archive. + dpkg-source when it creates the + .dsc source control file as part of a source + archive. Many fields are permitted to span multiple lines in + debian/control but not in any other control + file. These tools are responsible for removing the line + breaks from such fields when using fields from + debian/control to generate other control files.

@@ -2272,6 +2445,7 @@ Package: libc6 Installed-Size Maintainer (mandatory) Description (mandatory) + Homepage

@@ -2286,14 +2460,17 @@ Package: libc6 syntax is described above, in . + Format (mandatory) Source (mandatory) Version (mandatory) Maintainer (mandatory) + Uploaders Binary Architecture Build-Depends et al Standards-Version (recommended) Files (mandatory) + Homepage

@@ -2353,14 +2530,14 @@ Package: libc6

- In a main source control information, a .changes - or a .dsc file this may contain only the name - of the source package. + In debian/control or a .dsc file, + this field must contain only the name of the source package.

- In the control file of a binary package it may be followed - by a version number in parentheses + In a binary package control file or a .changes + file, the source package name may be followed by a version + number in parentheses It is customary to leave a space after the package name if a version number is specified. . @@ -2393,6 +2570,29 @@ Package: libc6

+ + Uploaders + +

+ List of the names and email addresses of co-maintainers of + the package, if any. If the package has other maintainers + beside the one named in the + Maintainer field, their + names and email addresses should be listed here. The + format is the same as that of the Maintainer tag, and + multiple entries should be comma separated. Currently, + this field is restricted to a single line of data. This + is an optional field. +

+

+ Any parser that interprets the Uploaders field in + debian/control must permit it to span multiple + lines. Line breaks in an Uploaders field that spans multiple + lines are not significant and the semantics of the field are + the same as if the line breaks had not been present. +

+ + Changed-By @@ -2418,12 +2618,6 @@ Package: libc6 It also gives the default for the same field in the binary packages.

- -

- By default, dpkg-gencontrol does not include this - field in the control file of a binary package - use the - -is (or -isp) options to achieve this effect. -

@@ -2441,12 +2635,6 @@ Package: libc6 It also gives the default for the same field in the binary packages.

- -

- By default, dpkg-gencontrol does not include this - field in the control file of a binary package - use the - -ip (or -isp) options to achieve this effect. -

@@ -2546,8 +2734,9 @@ Package: libc6 Package interrelationship fields: Depends, Pre-Depends, - Recommends, Suggests, Conflicts, - Provides, Replaces + Recommends, Suggests, + Breaks, Conflicts, + Provides, Replaces, Enhances

@@ -2649,8 +2838,8 @@ Package: libc6 Alphanumerics are A-Za-z0-9 only. and the characters . + - - : (full stop, plus, hyphen, colon) and should - start with a digit. If there is no + : ~ (full stop, plus, hyphen, colon, + tilde) and should start with a digit. If there is no debian_revision then hyphens are not allowed; if there is no epoch then colons are not allowed. @@ -2663,8 +2852,8 @@ Package: libc6 This part of the version number specifies the version of the Debian package based on the upstream version. It may contain only alphanumerics and the characters - + and . (plus and full stop) and is - compared in the same way as the + + . ~ (plus, full stop, + tilde) and is compared in the same way as the upstream_version is.

@@ -2673,7 +2862,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 "debianisation" of it and therefore no revision indication is required.

@@ -2713,7 +2902,15 @@ Package: libc6 which may be empty) are compared lexically. If a difference is found it is returned. The lexical comparison is a comparison of ASCII values modified so that all the letters - sort earlier than all the non-letters. + sort earlier than all the non-letters and so that a tilde + sorts before anything, even the end of a part. For example, + the following parts are in sorted order from earliest to + latest: ~~, ~~a, ~, the empty part, + a. + One common use of ~ is for upstream pre-releases. + For example, 1.0~beta1~svn1245 sorts earlier than + 1.0~beta1, which sorts earlier than 1.0. +

@@ -2778,7 +2975,7 @@ Package: libc6 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" + horizontally, the displaying program will line wrap 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 @@ -2942,10 +3139,19 @@ Package: libc6

This is a description of how important it is to upgrade to this version from previous ones. It consists of a single - keyword usually taking one of the values low, - medium or high (not case-sensitive) - followed by an optional commentary (separated by a space) - which is usually in parentheses. For example: + keyword taking one of the values low, + medium, high, emergency, or + critical + Other urgency values are supported with configuration + changes in the archive software but are not used in Debian. + The urgency affects how quickly a package will be considered + for inclusion into the testing distribution and + gives an indication of the importance of any fixes included + in the upload. Emergency and critical are + treated as synonymous. + (not case-sensitive) followed by an optional + commentary (separated by a space) which is usually in + parentheses. For example: Urgency: low (HIGH for users of diversions) @@ -2972,7 +3178,7 @@ Package: libc6 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. + consisting only of a space and a full stop.

@@ -3109,6 +3315,19 @@ Package: libc6

+ + Homepage + +

+ The URL of the web site for this package, preferably (when + applicable) the site from which the original source can be + obtained and any additional upstream documentation or + information may be found. The content of this field is a + simple URL without any surrounding characters such as + <>. +

+ + @@ -3172,11 +3391,12 @@ Package: libc6

These scripts are the files preinst, - postinst, prerm and postrm in the - control area of the package. They must be proper executable - files; if they are scripts (which is recommended), they must - start with the usual #! convention. They should be - readable and executable by anyone, and not world-writable. + postinst, prerm and + postrm in the control area of the package. + They must be proper executable files; if they are scripts + (which is recommended), they must start with the usual + #! convention. They should be readable and + executable by anyone, and must not be world-writable.

@@ -3191,6 +3411,13 @@ Package: libc6 well.

+

+ Additionally, packages interacting with users using + debconf in the postinst script should + install a config script in the control area, + see for details. +

+

When a package is upgraded a combination of the scripts from the old and new packages is called during the upgrade @@ -3215,7 +3442,7 @@ Package: libc6 start-stop-daemon, install-info, and update-rc.d can be found via the PATH environment variable. Those programs, and any - other program that one would expect to be on the + other program that one would expect to be in the PATH, should thus be invoked without an absolute pathname. Maintainer scripts should also not reset the PATH, though they might choose to modify it by @@ -3224,7 +3451,7 @@ Package: libc6 - Maintainer scripts Idempotency + Maintainer scripts idempotency

It is necessary for the error recovery procedures that the @@ -3251,22 +3478,21 @@ Package: libc6

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

+ + + Exit status

- Each script should return a zero exit status for - success, or a nonzero one for failure. + Each script must return a zero exit status for + success, or a nonzero one for failure, since the package + management system looks for the exit status of these scripts + and determines what action to take next based on that datum.

@@ -3306,12 +3532,15 @@ Package: libc6 in-favour package new-version + + postinst abort-remove + deconfigured's-postinst abort-deconfigure in-favour failed-install-package version - removing conflicting-package - version + [removing conflicting-package + version] @@ -3336,9 +3565,9 @@ Package: libc6 deconfigured's-prerm deconfigure in-favour package-being-installed - version removing + version [removing conflicting-package - version + version] @@ -3406,20 +3635,43 @@ Package: libc6 new-prerm failed-upgrade old-version - Error unwind, for both the above cases: + If this works, the upgrade continues. If this + does not work, the error unwind: old-postinst abort-upgrade new-version + If this works, then the old-version is + "Installed", if not, the old version is in a + "Failed-Config" state. - If a "conflicting" package is being removed at the same time: + If a "conflicting" package is being removed at the same time, + or if any package will be broken (due to Breaks): - If any packages depended on that conflicting - package and --auto-deconfigure is + If --auto-deconfigure is + specified, call, for each package to be deconfigured + due to Breaks: + +deconfigured's-prerm deconfigure \ + in-favour package-being-installed version + + Error unwind: + +deconfigured's-postinst abort-deconfigure \ + in-favour package-being-installed-but-failed version + + The deconfigured packages are marked as + requiring configuration, so that if + --install is used they will be + configured again if possible. + + + If any packages depended on a conflicting + package being removed and --auto-deconfigure is specified, call, for each such package: deconfigured's-prerm deconfigure \ @@ -3438,7 +3690,7 @@ Package: libc6 configured again if possible. - To prepare for removal of the conflicting package, call: + To prepare for removal of each conflicting package, call: conflictor's-prerm remove \ in-favour package new-version @@ -3459,6 +3711,30 @@ Package: libc6 new-preinst upgrade old-version + If this fails, we call: + +new-postrm abort-upgrade old-version + + + +

+ If that works, then + +old-postinst abort-upgrade new-version + + is called. If this works, then the old version + is in an "Installed" state, or else it is left + in an "Unpacked" state. +

+ + +

+ If it fails, then the old version is left + in an "Half-Installed" state. +

+ + + Otherwise, if the package had some configuration @@ -3467,20 +3743,30 @@ Package: libc6 new-preinst install old-version + Error unwind: + +new-postrm abort-install old-version + + If this fails, the package is left in a + "Half-Installed" state, which requires a + reinstall. If it works, the packages is left in + a "Config Files" state. Otherwise (i.e., the package was completely purged): new-preinst install - - Error unwind actions, respectively: - -new-postrm abort-upgrade old-version -new-postrm abort-install old-version + + Error unwind: + new-postrm abort-install - + + If the error-unwind fails, the package is in a + "Half Installed" phase, and requires a + reinstall. If the error unwind works, the + package is in a not installed state. - + @@ -3551,11 +3837,26 @@ Package: libc6 new-postrm failed-upgrade old-version - Error unwind, for both cases: + If this works, installation continues. If not, + Error unwind: old-preinst abort-upgrade new-version - + If this fails, the old version is left in an + "Half Installed" state. If it works, dpkg now + calls: + +new-postrm abort-upgrade old-version + + If this fails, the old version is left in an + "Half Installed" state. If it works, dpkg now + calls: + +old-postinst abort-upgrade new-version + + If this fails, the old version is in an + "Unpacked" state. +

@@ -3663,7 +3964,8 @@ Package: libc6

No attempt is made to unwind after errors during - configuration. + configuration. If the configuration fails, the package is in + a "Failed Config" state, and an error message is generated.

@@ -3689,9 +3991,26 @@ Package: libc6

+

prerm remove +

+

+ If prerm fails during replacement due to conflict + +conflictor's-postinst abort-remove \ + in-favour package new-version + + Or else we call: + +postinst abort-remove + +

+

+ If this fails, the package is in a "Failed-Config" + state, or else it remains "Installed". +

The package's files are removed (except conffiles). @@ -3700,6 +4019,11 @@ Package: libc6 postrm remove + +

+ If it fails, there's no error unwind, and the package is in + an "Half-Installed" state. +

@@ -3722,19 +4046,21 @@ Package: libc6 are removed. +

postrm purge +

+

+ If this fails, the package remains in a "Config-Files" + state. +

The package's file list is removed. - If there are problems during this process, we call - postinst - abort-remove. No other attempt is made to unwind - after errors during removal.

@@ -3787,13 +4113,16 @@ Package: libc6 Whitespace may appear at any point in the version specification subject to the rules in , and must appear where it's necessary to - disambiguate; it is not otherwise significant. For + disambiguate; it is not otherwise significant. All of the + relationship fields may span multiple lines. For consistency and in case of future changes to dpkg it is recommended that a single space be used after a version relationship and before a version number; it is also conventional to put a single space after each comma, on either side of each vertical bar, and before - each open parenthesis. + each open parenthesis. When wrapping a relationship field, it + is conventional to do so after a comma and before the space + following that comma.

@@ -3815,7 +4144,7 @@ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent list of Debian architecture names separated by whitespace. Exclamation marks may be prepended to each of the names. (It is not permitted for some names to be prepended with - exclamation marks and others not.) If the current Debian + exclamation marks while others aren't.) If the current Debian host architecture is not in this list and there are no exclamation marks in the list, or it is in the list with a prepended exclamation mark, the package name and the @@ -3858,16 +4187,19 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],

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

- These six fields are used to declare a dependency + These seven 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 - recommending package's control file.) + Enhances and Breaks, they appear in the + depending (binary) package's control file. + (Enhances appears in the recommending package's + control file, and Breaks appears in the version of + depended-on package which causes the named package to + break).

@@ -3886,7 +4218,8 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], in detail below. (The other three dependency fields, Recommends, Suggests and Enhances, are only used by the various front-ends - to dpkg such as dselect.) + to dpkg such as apt-get, + aptitude, and dselect.)

@@ -3897,6 +4230,21 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], dependencies satisfied.

+

+ In case of circular dependencies, since installation or + removal order honoring the dependency order can't be + established, dependency loops are broken at some point + (based on rules below), and some packages may not be able to + rely on their dependencies being present when being + installed or removed, depending on which side of the break + of the circular dependency loop they happen to be on. If one + of the packages in the loop has no postinst script, then the + cycle will be broken at that package, so as to ensure that + all postinst scripts run with the dependencies properly + configured if this is possible. Otherwise the breaking point + is arbitrary. +

+

The Depends field thus allows package maintainers to impose an order in which packages should be configured. @@ -4025,6 +4373,53 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],

+ + Packages which break other packages - Breaks + +

+ Using Breaks may cause problems for upgrades from older + versions of Debian and should not be used until the stable + release of Debian supports Breaks. +

+ +

+ When one binary package declares that it breaks another, + dpkg will refuse to allow the package which + declares Breaks be installed unless the broken + package is deconfigured first, and it will refuse to + allow the broken package to be reconfigured. +

+ +

+ A package will not be regarded as causing breakage merely + because its configuration files are still installed; it must + be at least half-installed. +

+ +

+ A special exception is made for packages which declare that + they break their own package name or a virtual package which + they provide (see below): this does not count as a real + breakage. +

+ +

+ Normally a Breaks entry will have an "earlier than" + version clause; such a Breaks is introduced in the + version of an (implicit or explicit) dependency which + violates an assumption or reveals a bug in earlier versions + of the broken package. This use of Breaks will + inform higher-level package management tools that broken + package must be upgraded before the new one. +

+ +

+ If the breaking package also overwrites some files from the + older package, it should use Replaces (not + Conflicts) to ensure this goes smoothly. +

+ + Conflicting binary packages - Conflicts @@ -4070,7 +4465,9 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], "earlier than" version clause. This would prevent dpkg from upgrading or installing the package which declared such a conflict until the upgrade or removal - of the conflicted-with package had been completed. + of the conflicted-with package had been completed. Instead, + Breaks may be used (once Breaks is supported + by the stable release of Debian).

@@ -4081,7 +4478,7 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], As well as the names of actual ("concrete") packages, the package relationship fields Depends, Recommends, Suggests, Enhances, - Pre-Depends, Conflicts, + Pre-Depends, Breaks, Conflicts, Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep may mention "virtual packages". @@ -4106,10 +4503,8 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386], Package: foo Depends: bar - - and someone else releases an enhanced version of the - bar package (for example, a non-US variant), they - can say: + and someone else releases an enhanced version of + the bar package they can say: Package: bar-plus Provides: bar @@ -4119,16 +4514,16 @@ Provides: bar

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

@@ -4272,12 +4667,15 @@ Replaces: mail-transport-agent 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. + There is no Build-Depends-Arch; this role is essentially + met with Build-Depends. Anyone building the + build-indep and binary-indep targets + is basically assumed to be building the whole package + anyway and so installs all build dependencies. The + autobuilders use dpkg-buildpackage -B, which + calls build (not build-arch, since it + does not yet know how to check for its existence) and + binary-arch.

The purpose of the original split, I recall, was so that @@ -4337,10 +4735,21 @@ Replaces: mail-transport-agent 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 run-time shared library needs to be placed in a package + whose name changes whenever the shared object version + changes. +

+ Since it is common place to install several versions of a + package that just provides shared libraries, it is a + good idea that the library package should not + contain any extraneous non-versioned files, unless they + happen to be in versioned directories.

+ + The most common mechanism is to place it 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 @@ -4356,6 +4765,21 @@ Replaces: mail-transport-agent instead.

+

+ If your package includes run-time support programs that + do not need to be invoked manually by users, but are + nevertheless required for the package to function, then it + is recommended that these programs are placed + (if they are binary) in a subdirectory of + /usr/lib, preferably under + /usr/lib/package-name. + If the program is architecture independent, the + recommendation is for it to be placed in a subdirectory of + /usr/share instead, preferably under + /usr/share/package-name. +

+ +

If you have several shared libraries built from the same source tree you may lump them all together into a single @@ -4424,11 +4848,9 @@ Replaces: mail-transport-agent listed in /etc/ld.so.conf These are currently - /usr/X11R6/lib/Xaw3d /usr/local/lib /usr/lib/libc5-compat /lib/libc5-compat - /usr/X11R6/lib must use ldconfig to update the shared library @@ -4436,15 +4858,20 @@ Replaces: mail-transport-agent

- 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. + The package maintainer scripts must only call + ldconfig under these circumstances: + + When the postinst script is run with a + first argument of configure, the script must call + ldconfig, and may optionally invoke + ldconfig at other times. + + When the postrm script is run with a + first argument of remove, the script should call + ldconfig. + + +

During install or upgrade, the preinst is called before the new files are installed, so calling "ldconfig" is @@ -4478,16 +4905,16 @@ Replaces: mail-transport-agent

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. + argument just after the files are removed, so this is + the proper time to call "ldconfig" to notify the system + of the fact that the 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.

@@ -4578,8 +5005,12 @@ Replaces: mail-transport-agent 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 + ${binary:Version} substitution variable can be useful for this purpose. + + Previously, ${Source-Version} was used, but its name + was confusing and it has been deprecated since dpkg 1.13.19. +

@@ -4792,7 +5223,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 dpkg-gencontrol. You will need to place a - ${shlib:Depends} variable in the Depends + ${shlibs:Depends} variable in the Depends field in the control file for this to work.

@@ -4811,6 +5242,19 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ utilities to specify a different substvars file.

+

+ If you are creating a udeb for use in the Debian Installer, you + will need to specify that dpkg-shlibdeps should use + the dependency line of type udeb by adding + -tudeb as option + dh_shlibdeps from the debhelper suite + will automatically add this option if it knows it is + processing a udeb. + . If there is no dependency line of type udeb + in the shlibs file, dpkg-shlibdeps will + fall back to the regular dependency line. +

+

For more details on dpkg-shlibdeps, please see and @@ -4826,7 +5270,7 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ beginning with # are considered to be comments and are ignored. Each line is of the form: -library-name soname-version-number dependencies ... +[type: ]library-name soname-version dependencies ...

@@ -4836,6 +5280,13 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ installs the shared library /usr/lib/libz.so.1.1.3.

+

+ type is an optional element that indicates the type + of package for which the line is valid. The only type currently + in use is udeb. The colon and space after the type are + required. +

+

library-name is the name of the shared library, in this case libz. (This must match the name part @@ -4843,10 +5294,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

- soname-version-number is the version part of the - soname of the library. The soname is the thing that must - exactly match for the library to be recognized by the - dynamic linker, and is usually of the form + soname-version is the version part of the soname of + the library. The soname is the thing that must exactly match + for the library to be recognized by the dynamic linker, and is + usually of the form name.so.major-version, in our example, libz.so.1. This can be determined using the command @@ -4878,13 +5329,21 @@ libz 1 zlib1g (>= 1:1.1.3) the dynamic linker about using older shared libraries with newer binaries.

+ +

+ As zlib1g also provides a udeb containing the shared library, + there would also be a second line: + +udeb: libz 1 zlib1g-udeb (>= 1:1.1.3) + +

Providing a shlibs file

- If your package provides a shared library, you should create + If your package provides a shared library, you need to create 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 @@ -4902,7 +5361,10 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ debian/rules without using a debian/shlibs file at all, This is what dh_makeshlibs in the - debhelper suite does. + debhelper suite does. If your package also has a udeb + that provides a shared library, dh_makeshlibs can + automatically generate the udeb: lines if you specify + the name of the udeb with the --add-udeb option. since the debian/shlibs file itself is ignored by dpkg-shlibdeps. @@ -4991,20 +5453,78 @@ libbar 1 bar1 (>= 1.0-1) The Operating System - Filesystem hierarchy + File system hierarchy - Filesystem Structure + File system Structure

The location of all installed files and directories must - comply with the Filesystem Hierarchy Standard (FHS), - 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 - + +

+ Legacy XFree86 servers are permitted to retain the + configuration file location + /etc/X11/XF86Config-4. +

+ + +

+ The optional rules related to user specific + configuration files for applications are stored in + the user's home directory are relaxed. It is + recommended that such files start with the + '.' character (a "dot file"), and if an + application needs to create more than one dot file + then the preferred placement is in a subdirectory + with a name starting with a '.' character, (a "dot + directory"). In this case it is recommended the + configuration files not start with the '.' + character. +

+ + +

+ The requirement for amd64 to use /lib64 + for 64 bit binaries is removed. +

+ + +

+ The requirement that + /usr/local/share/man be "synonymous" + with /usr/local/man is relaxed to a + recommendation

+ + +

+ The requirement that windowmanagers with a single + configuration file call it system.*wmrc + is removed, as is the restriction that the window + manager subdirectory be named identically to the + window manager name itself. +

+ + +

+ The requirement that boot manager configuration + files live in /etc, or at least are + symlinked there, is relaxed to a recommendation. +

+ + + +

+

+ 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 = 1.0-1)

However, the package may create empty directories below /usr/local so that the system administrator knows - where to place site-specific files. These directories + where to place site-specific files. These are not + directories in /usr/local, but are + children of directories in /usr/local. These + directories (/usr/local/*/dir/) should be removed on package removal if they are empty.

@@ -5280,7 +5803,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true of simplicity, this document describes only the symbolic link method. However, it must not be assumed by maintainer scripts that this method is being used, and any automated - manipulation of the various runlevel behaviours by + manipulation of the various runlevel behaviors by maintainer scripts must be performed using update-rc.d as described below and not by manually installing or removing symlinks. For information @@ -5359,8 +5882,8 @@ rmdir /usr/local/share/emacs 2>/dev/null || true

- Also, if the script name ends .sh, the script - will be sourced in runlevel S rather that being + Also, if the script name ends in .sh, the script + will be sourced in runlevel S rather than being run in a forked subprocess, but will be explicitly run by sh in all other runlevels.

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

- The init.d scripts should ensure that they will + The init.d scripts must 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 @@ -5433,7 +5956,7 @@ rmdir /usr/local/share/emacs 2>/dev/null || true 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 + while making sure their changes aren't lost during the next package upgrade.

@@ -5456,7 +5979,7 @@ test -f program-executed-later-in-script || exit 0

Often there are some variables in the init.d - scripts whose values control the behaviour of the scripts, + scripts whose values control the behavior 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 @@ -5468,7 +5991,7 @@ test -f program-executed-later-in-script || exit 0 /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 + must contain only variable settings and comments in SUSv3 sh format. It may either be a conffile or a configuration file maintained by the package maintainer scripts. See @@ -5571,7 +6094,7 @@ test -f program-executed-later-in-script || exit 0

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

@@ -5588,14 +6111,10 @@ test -f program-executed-later-in-script || exit 0

- 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. + The package maintainer scripts must use + invoke-rc.d to invoke the + /etc/init.d/* initscripts, instead of + calling them directly.

@@ -5612,7 +6131,7 @@ test -f program-executed-later-in-script || exit 0 <action> in their postinst and prerm scripts to: - if command -v invoke-rc.d >/dev/null 2>&1; then + if which invoke-rc.d >/dev/null 2>&1; then invoke-rc.d package <action> else /etc/init.d/package <action> @@ -5629,7 +6148,7 @@ test -f program-executed-later-in-script || exit 0

For more information about using - invoke-rc.d, please consult its manpage + invoke-rc.d, please consult its man page .

@@ -5652,111 +6171,11 @@ test -f program-executed-later-in-script || exit 0 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 -# -# Original version by Robert Leslie -# <rob@mars.org>, edited by iwj and cs - -test -x /usr/sbin/named || exit 0 - -# Source defaults file. -PARAMS='' -if [ -f /etc/default/bind ]; then - . /etc/default/bind -fi - - -case "$1" in -start) - echo -n "Starting domain name service: named" - start-stop-daemon --start --quiet --exec /usr/sbin/named \ - -- $PARAMS - echo "." - ;; -stop) - echo -n "Stopping domain name service: named" - start-stop-daemon --stop --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - echo "." - ;; -restart) - echo -n "Restarting domain name service: named" - start-stop-daemon --stop --quiet --oknodo \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - start-stop-daemon --start --verbose --exec /usr/sbin/named \ - -- $PARAMS - echo "." - ;; -force-reload|reload) - echo -n "Reloading configuration of domain name service: named" - start-stop-daemon --stop --signal 1 --quiet \ - --pidfile /var/run/named.pid --exec /usr/sbin/named - echo "." - ;; -*) - echo "Usage: /etc/init.d/bind " \ - " {start|stop|restart|reload|force-reload}" >&2 - exit 1 - ;; -esac - -exit 0 - -

- -

- Complementing the above init script is a configuration - 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 - postrm script. - -# Specified parameters to pass to named. See named(8). -# You may uncomment the following line, and edit to taste. -#PARAMS="-u nobody" - -

- -

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

-

- If this package is happy with the default setup from - update-rc.d, namely an ordering number of 20 - and having named running in all runlevels, it can say in - its postinst: - -update-rc.d bind defaults >/dev/null - - And in its postrm, to remove the links when the - package is purged: - -if [ "$1" = purge ]; then - update-rc.d bind remove >/dev/null -fi - -

@@ -5774,38 +6193,34 @@ fi

- Here is a list of overall rules that you should use when you - create output messages. They can be useful if you have a - non-standard message that is not covered specifically in the - sections below. + Here is a list of overall rules that should be used for + messages generated by /etc/init.d scripts.

- Every message should fit in one line (fewer than 80 + The message should fit in one line (fewer than 80 characters), start with a capital letter and end with a period (.) and line feed ("\n"). - If you want to express that the computer is working on - something (that is, performing a specific task, not - starting or stopping a program), we use an "ellipsis" - (three dots: ...). Note that we don't insert - spaces before or after the dots. If the task has been - completed we write done. and a line feed. + If the script is performing some time consuming task in + the background (not merely starting or stopping a + program, for instance), an ellipsis (three dots: + ...) should be output to the screen, with no + leading or tailing whitespace or line feeds. - Design your messages as if the computer is telling you - what he is doing (let him be polite :-), but don't - mention "him" directly. For example, if you think of - saying + The messages should appear as if the computer is telling + the user what it is doing (politely :-), but should not + mention "it" directly. For example, instead of: I'm starting network daemons: nfsd mountd. - just say + the message should say Starting network daemons: nfsd mountd. @@ -5814,9 +6229,8 @@ Starting network daemons: nfsd mountd.

- There are standard message formats for the following - situations. They should be used by the init.d - scripts. + init.d script should use the following standard + message formats for the situations enumerated below.

@@ -5825,7 +6239,7 @@ Starting network daemons: nfsd mountd.

When daemons are started

- If your script starts one or more daemons, the output + If the script starts one or more daemons, the output should look like this (a single line, no leading spaces): @@ -5853,8 +6267,8 @@ echo -n "Starting printer spooler: lpd" start-stop-daemon --start --quiet --exec /usr/sbin/lpd echo "." - in the script. If you have more than one daemon to - start, you should do the following: + in the script. If there are more than one daemon to + start, the output should look like this: echo -n "Starting remote file system services:" echo -n " nfsd"; start-stop-daemon --start --quiet nfsd @@ -5862,12 +6276,12 @@ echo -n " mountd"; start-stop-daemon --start --quiet mountd echo -n " ugidd"; start-stop-daemon --start --quiet ugidd echo "." - This makes it possible for the user to see what takes - so long and when the final daemon has been started. - You should be careful where to put spaces: in the - example above the system administrator can easily - comment out a line if he don't wants to start a - specific daemon, while the displayed message still + This makes it possible for the user to see what is + happening and when the final daemon has been started. + Care should be taken in the placement of white spaces: + in the example above the system administrators can + easily comment out a line if they don't want to start + a specific daemon, while the displayed message still looks good.

@@ -5910,8 +6324,8 @@ echo "Setting DNS domainname to \"$domainname\"."

- For example, stopping the printer daemon will like - like this: + For example, stopping the printer daemon will look like + this: Stopping printer spooler: lpd. @@ -5933,7 +6347,7 @@ Doing something very useful...done. You should print the done. immediately after the job has been completed, so that the user is - informed why she has to wait. You can get this + informed why they have to wait. You can get this behavior by saying echo -n "Doing something very useful..." @@ -5974,12 +6388,13 @@ Reloading description configuration...done. via cron, it should place a file with the name of the package in one or more of the following directories: +/etc/cron.hourly /etc/cron.daily /etc/cron.weekly /etc/cron.monthly As these directory names imply, the files within them are - executed on a daily, weekly, or monthly basis, + executed on an hourly, daily, weekly, or monthly basis, respectively. The exact times are listed in /etc/crontab.

@@ -5987,13 +6402,12 @@ Reloading description configuration...done. All files installed in any of these directories must be scripts (e.g., shell scripts or Perl scripts) so that they can easily be modified by the local system administrator. - In addition, they should be treated as configuration - files. + In addition, they must be treated as configuration files.

- If a certain job has to be executed more frequently than - daily, the package should install a file + If a certain job has to be executed at some other frequency or + at a specific time, the package should install a file /etc/cron.d/package. This file uses the same syntax as /etc/crontab and is processed by cron automatically. The file must also be @@ -6017,9 +6431,8 @@ Reloading description configuration...done.

The Debian menu package provides a standard interface between packages providing applications and - documents, and menu programs (either X window - managers or text-based menu programs such as - pdmenu). + menu programs (either X window managers or + text-based menu programs such as pdmenu).

@@ -6040,17 +6453,14 @@ Reloading description configuration...done. files in the debian-policy package. It is also available from the Debian web mirrors at - and from the Debian archive mirrors at - . + id="http://www.debian.org/doc/packaging-manuals/menu-policy/">.

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

@@ -6082,10 +6492,7 @@ Reloading description configuration...done. files in the debian-policy package. It is also available from the Debian web mirrors at - and from the Debian archive mirrors at - . + id="http://www.debian.org/doc/packaging-manuals/mime-policy/">.

@@ -6281,6 +6688,27 @@ exec /usr/lib/foo/foo "$@"

+ + Registering Documents using doc-base + +

+ The doc-base package implements a + flexible mechanism for handling and presenting + documentation. The recommended practice is for every Debian + package that provides online documentation (other than just + manual pages) to register these documents with + doc-base by installing a + doc-base control file via the + +

+ Please refer to the documentation that comes with the + doc-base package for information and + details. +

+ + @@ -6317,7 +6745,7 @@ exec /usr/lib/foo/foo "$@" CC = gcc CFLAGS = -O2 -g -Wall # sane warning options vary between programs LDFLAGS = # none -install -s # (or use strip on the files in debian/tmp) +INSTALL = install -s # (or use strip on the files in debian/tmp)

@@ -6332,58 +6760,12 @@ install -s # (or use strip on the files in debian/tmp)

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 compiled 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 - 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 noopt,$(DEB_BUILD_OPTIONS))) -CFLAGS += -O0 -else -CFLAGS += -O2 -endif -ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) -INSTALL_PROGRAM += -s -endif - + 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 + (see ). This variable can contain + several flags to change how a package is compiled and built.

@@ -6404,13 +6786,70 @@ endif Libraries +

+ If the package is architecture: any, then + the shared library compilation and linking flags must have + -fPIC, or the package shall not build on some of + the supported architectures +

+ If you are using GCC, -fPIC produces code with + relocatable position independent code, which is required for + most architectures to create a shared library, with i386 and + perhaps some others where non position independent code is + permitted in a shared library. +

+

+ Position independent code may have a performance penalty, + especially on i386. However, in most cases the + speed penalty must be measured against the memory wasted on + the few architectures where non position independent code is + even possible. +

+ . Any exception to this rule must be discussed on + the mailing list debian-devel@lists.debian.org, and + a rough consensus obtained. The reasons for not compiling + with -fPIC flag must be recorded in the file + README.Debian, and care must be taken to either + restrict the architecture or arrange for -fPIC to + be used on architectures where it is required. +

+ Some of the reasons why this might be required is if the + library contains hand crafted assembly code that is not + relocatable, the speed penalty is excessive for compute + intensive libs, and similar reasons. +

+ +

- 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. + As to the static libraries, the common case is not to have + relocatable code, since there is no benefit, unless in specific + cases; therefore the static version must not be compiled + with the -fPIC flag. Any exception to this rule + should be discussed on the mailing list + debian-devel@lists.debian.org, and the reasons for + compiling with the -fPIC flag must be recorded in + the file README.Debian. +

+ Some of the reasons for linking static libraries with + the -fPIC flag are if, for example, one needs a + Perl API for a library that is under rapid development, + and has an unstable API, so shared libraries are + pointless at this phase of the library's development. In + that case, since Perl needs a library with relocatable + code, it may make sense to create a static library with + relocatable code. Another reason cited is if you are + distilling various libraries into a common shared + library, like mklibs does in the Debian + installer project. +

+

- +

+ In other words, if both a shared and a static library is + being built, each source unit (*.c, for example, + for C files) will need to be compiled twice, for the normal + case. +

You must specify the gcc option -D_REENTRANT when building a library (either static or shared) to make @@ -6552,6 +6991,12 @@ strip --strip-unneeded your-lib #!/usr/bin/perl.

+

+ When scripts are installed into a directory in the system + PATH, the script name should not include an extension such + as .sh or .pl that denotes the scripting + language currently used to implement it. +

Shell scripts (sh and bash) should almost certainly start with set -e so that @@ -6561,34 +7006,54 @@ strip --strip-unneeded your-lib

- 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 - 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 - required under POSIX, hence this explicit addition. - Also, rumour has it that this shall be mandated under - the LSB anyway. + Scripts may assume that /bin/sh implements the + SUSv3 Shell Command Language + Single UNIX Specification, version 3, which is also IEEE + 1003.1-2004 (POSIX), and is available on the World Wide Web + from after free + registration. + plus the following additional features not mandated by + SUSv3: + These features are in widespread use in the Linux community + and are implemented in all of bash, dash, and ksh, the most + common shells users may wish to use as /bin/sh. - 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 - 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 dash - (originally called ash), it's probably POSIX - compliant, but if you are in doubt, use + + echo -n, if implemented as a shell built-in, + must not generate a newline. + test, if implemented as a shell built-in, must + support -a and -o as binary logical + operators. + local to create a scoped variable must be + supported; however, local may or may not preserve + the variable value from an outer scope and may or may not + support arguments more complex than simple variables. Only + uses such as: + +fname () { + local a + a='' + # ... use a ... +} + + must be supported. + + + If a shell script requires non-SUSv3 features from the shell + interpreter other than those listed above, 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 bash). +

+ +

+ You may wish to restrict your script to SUSv3 features plus the + above set when possible so that it may use /bin/sh + as its interpreter. If your script works with dash + (originally called ash), it probably complies with + the above requirements, but if you are in doubt, use /bin/bash.

@@ -6602,7 +7067,7 @@ strip --strip-unneeded your-lib csh and tcsh should be avoided as scripting languages. See Csh Programming Considered Harmful, one of the comp.unix.* FAQs, which - can be found at . + can be found at . If an upstream package comes with csh scripts then you must make sure that they start with #!/bin/csh and make your package depend on the @@ -6612,8 +7077,8 @@ strip --strip-unneeded your-lib

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

@@ -6741,10 +7206,13 @@ 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 - configuration file and should be treated as such. + As noted elsewhere, /etc/init.d scripts, + /etc/default files, scripts installed in + /etc/cron.{hourly,daily,weekly,monthly}, and cron + configuration installed in /etc/cron.d must be + treated as configuration files. In general, any script that + embeds configuration information is de-facto a configuration + file and should be treated as such.

@@ -6827,8 +7295,8 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq variety of ways dpkg can call maintainer scripts, must not overwrite or otherwise mangle the user's configuration without asking, must not ask unnecessary - questions (particularly during upgrades), and otherwise be - good citizens. + questions (particularly during upgrades), and must + otherwise be good citizens.

@@ -6961,7 +7429,7 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq

Furthermore, programs should be configured by the Debian default installation to behave as closely to the upstream - default behaviour as possible. + default behavior as possible.

@@ -7071,9 +7539,25 @@ endscript mode 2775. The ownership of the directory should be consistent with its mode: if a directory is mode 2775, it should be owned by the group that needs write access to - it. + it. +

+ When a package is upgraded, and the owner or permissions + of a file included in the package has changed, dpkg + arranges for the ownership and permissions to be + correctly set upon installation. However, this does not + extend to directories; the permissions and ownership of + directories already on the system does not change on + install or upgrade of packages. This makes sense, since + otherwise common directories like /usr would + always be in flux. To correctly change permissions of a + directory the package owns, explicit action is required, + usually in the postinst script. Care must be + taken to handle downgrades as well, in that case. +

+

+

Setuid and setgid executables should be mode 4755 or 2755 respectively, and owned by the appropriate user or group. @@ -7106,7 +7590,7 @@ endscript normally have their permissions reset to the distributed permissions when the package is reinstalled. However, the use of dpkg-statoverride overrides this - default behaviour. If you use this method, you should + default behavior. If you use this method, you should remember to describe dpkg-statoverride in the package documentation; being a relatively new addition to Debian, it is probably not yet well-known. @@ -7170,21 +7654,11 @@ endscript description of the use of dpkg-statoverride.

-

- dpkg-statoverride is a replacement for the - deprecated suidmanager package. Packages which - previously used suidmanager should have a - Conflicts: suidmanager (<< 0.50) entry (or even - (<< 0.52)), and calls to suidregister - and suidunregister should now be simply removed - from the maintainer scripts. -

-

If a system administrator wishes to have a file (or directory or other such thing) installed with owner and permissions different from those in the distributed Debian - package, he can use the dpkg-statoverride + package, they can use the dpkg-statoverride program to instruct dpkg to use the different settings every time the file is installed. Thus the package maintainer should distribute the files with their @@ -7198,7 +7672,8 @@ endscript maintainer can use debconf to find out the preference, and call dpkg-statoverride in the maintainer script if necessary to accommodate the system - administrator's choice. + administrator's choice. Care must be taken during + upgrades to not override an existing setting.

@@ -7215,9 +7690,13 @@ endscript for i in /usr/bin/foo /usr/sbin/bar do - if ! dpkg-statoverride --list $i >/dev/null + # only do something when no setting exists + if ! dpkg-statoverride --list $i >/dev/null 2>&1 then - dpkg-statoverride --update --add sysuser root 4755 $i + #include: debconf processing, question about foo and bar + if [ "$RET" = "true" ] ; then + dpkg-statoverride --update --add sysuser root 4755 $i + fi fi done @@ -7238,21 +7717,51 @@ done

If a program needs to specify an architecture specification - string in some place, the following format should be - used: arch-os - The following architectures and operating systems are - currently recognised by dpkg-architecture. - The architecture, arch, is one of - the following: alpha, arm, - hppa, i386, ia64, - m68k, mips, mipsel, - powerpc, s390, sh, - sheb, sparc and sparc64. The - operating system, os, is one of: - linux, gnu, freebsd and - openbsd. Use of gnu in this string is - reserved for the GNU/Hurd operating system. - . + string in some place, it should select one of the + strings provided by dpkg-architecture -L. The + strings are in the format + os-arch, though the OS part + is sometimes elided, as when the OS is Linux. +

Currently, the strings are: + i386 ia64 alpha amd64 armeb arm hppa m32r m68k mips + mipsel powerpc ppc64 s390 s390x sh3 sh3eb sh4 sh4eb + sparc darwin-i386 darwin-ia64 darwin-alpha darwin-amd64 + darwin-armeb darwin-arm darwin-hppa darwin-m32r + darwin-m68k darwin-mips darwin-mipsel darwin-powerpc + darwin-ppc64 darwin-s390 darwin-s390x darwin-sh3 + darwin-sh3eb darwin-sh4 darwin-sh4eb darwin-sparc + freebsd-i386 freebsd-ia64 freebsd-alpha freebsd-amd64 + freebsd-armeb freebsd-arm freebsd-hppa freebsd-m32r + freebsd-m68k freebsd-mips freebsd-mipsel freebsd-powerpc + freebsd-ppc64 freebsd-s390 freebsd-s390x freebsd-sh3 + freebsd-sh3eb freebsd-sh4 freebsd-sh4eb freebsd-sparc + kfreebsd-i386 kfreebsd-ia64 kfreebsd-alpha + kfreebsd-amd64 kfreebsd-armeb kfreebsd-arm kfreebsd-hppa + kfreebsd-m32r kfreebsd-m68k kfreebsd-mips + kfreebsd-mipsel kfreebsd-powerpc kfreebsd-ppc64 + kfreebsd-s390 kfreebsd-s390x kfreebsd-sh3 kfreebsd-sh3eb + kfreebsd-sh4 kfreebsd-sh4eb kfreebsd-sparc knetbsd-i386 + knetbsd-ia64 knetbsd-alpha knetbsd-amd64 knetbsd-armeb + knetbsd-arm knetbsd-hppa knetbsd-m32r knetbsd-m68k + knetbsd-mips knetbsd-mipsel knetbsd-powerpc + knetbsd-ppc64 knetbsd-s390 knetbsd-s390x knetbsd-sh3 + knetbsd-sh3eb knetbsd-sh4 knetbsd-sh4eb knetbsd-sparc + netbsd-i386 netbsd-ia64 netbsd-alpha netbsd-amd64 + netbsd-armeb netbsd-arm netbsd-hppa netbsd-m32r + netbsd-m68k netbsd-mips netbsd-mipsel netbsd-powerpc + netbsd-ppc64 netbsd-s390 netbsd-s390x netbsd-sh3 + netbsd-sh3eb netbsd-sh4 netbsd-sh4eb netbsd-sparc + openbsd-i386 openbsd-ia64 openbsd-alpha openbsd-amd64 + openbsd-armeb openbsd-arm openbsd-hppa openbsd-m32r + openbsd-m68k openbsd-mips openbsd-mipsel openbsd-powerpc + openbsd-ppc64 openbsd-s390 openbsd-s390x openbsd-sh3 + openbsd-sh3eb openbsd-sh4 openbsd-sh4eb openbsd-sparc + hurd-i386 hurd-ia64 hurd-alpha hurd-amd64 hurd-armeb + hurd-arm hurd-hppa hurd-m32r hurd-m68k hurd-mips + hurd-mipsel hurd-powerpc hurd-ppc64 hurd-s390 hurd-s390x + hurd-sh3 hurd-sh3eb hurd-sh4 hurd-sh4eb hurd-sparc +

+

@@ -7315,7 +7824,7 @@ done

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

@@ -7329,7 +7838,7 @@ done program to edit or display a text document. Since there are lots of different editors and pagers available in the Debian distribution, the system administrator and each user should - have the possibility to choose his/her preferred editor and + have the possibility to choose their preferred editor and pager.

@@ -7405,6 +7914,7 @@ done http://localhost/cgi-bin/cgi-bin-name + @@ -7428,6 +7938,20 @@ http://localhost/doc/package/filename

+ +

Access to images

+

+ It is recommended that images for a package be stored + in /usr/share/images/package and + may be referred to through an alias /images/ + as + + http://localhost/images/<package>/<filename> + + +

+ +

Web Document Root

@@ -7436,8 +7960,8 @@ http://localhost/doc/package/filename the Web Document Root. Instead they should use the /usr/share/doc/package directory for documents and register the Web Application via the - menu package. If access to the web document root is - unavoidable then use + doc-base package. If access to the + web document root is unavoidable then use /var/www @@ -7446,7 +7970,19 @@ http://localhost/doc/package/filename has put the real document root.

- +

Providing httpd and/or httpd-cgi

+

+ All web servers should provide the virtual package + httpd. If a web server has CGI support it should + provide httpd-cgi additionally. +

+

+ All web applications which do not contain CGI scripts should + depend on httpd, all those web applications which + do contain CGI scripts, should depend on + httpd-cgi. +

+

@@ -7545,7 +8081,7 @@ http://localhost/doc/package/filename

- Such package should check for the existence of this file + Such a package should check for the existence of this file when it is being configured. If it exists, it should be used without comment, although an MTA's configuration script may wish to prompt the user even if it finds that this file @@ -7675,7 +8211,7 @@ name ["syshostname"]: "view" in a multiple-document interface (MDI). and runs the specified command, - interpreting the entirity of the rest of the command + interpreting the entirety of the rest of the command line as a command to pass straight to exec, in the manner that xterm does. @@ -7717,7 +8253,7 @@ name ["syshostname"]: If the window manager complies with , written by the , add 40 points. @@ -7742,7 +8278,7 @@ name ["syshostname"]: For the purposes of Debian Policy, a "font for the X Window System" is one which is accessed via X protocol requests. Fonts for the Linux console, for PostScript - renderers, or any other purpose, do not fit this + renderer, or any other purpose, do not fit this definition. Any tool which makes such fonts available to the X Window System, however, must abide by this font policy. @@ -7766,52 +8302,52 @@ name ["syshostname"]: be used. Packages must not Depend on font packages. This is because the X server may retrieve fonts - from the local filesystem or over the network + from the local file system or over the network from an X font server; the Debian package system is empowered to deal only with the local - filesystem. + file system. BDF fonts must be converted to PCF fonts with the bdftopcf utility (available in the - xutils package, gzipped, and + xfonts-utils 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/share/fonts/X11/100dpi/. 75 dpi fonts must be placed in - /usr/X11R6/lib/X11/fonts/75dpi/. + /usr/share/fonts/X11/75dpi/. Character-cell fonts, cursor fonts, and other low-resolution fonts must be placed in - /usr/X11R6/lib/X11/fonts/misc/. + /usr/share/fonts/X11/misc/. Speedo fonts must be placed in - /usr/X11R6/lib/X11/fonts/Speedo/. + /usr/share/fonts/X11/Speedo/. Type 1 fonts must be placed in - /usr/X11R6/lib/X11/fonts/Type1/. If font + /usr/share/fonts/X11/Type1/. If font metric files are available, they must be placed here as well. - Subdirectories of /usr/X11R6/lib/X11/fonts/ + Subdirectories of /usr/share/fonts/X11/ other than those listed above must be neither created nor used. (The PEX, CID, and cyrillic directories are excepted for @@ -7860,7 +8396,7 @@ name ["syshostname"]: /etc/X11/fonts/fontdir/package.extension, where fontdir is the name of the subdirectory of - /usr/X11R6/lib/X11/fonts/ where the + /usr/share/fonts/X11/ where the package's corresponding fonts are stored (e.g., 75dpi or misc), package is the name of the package @@ -7874,7 +8410,7 @@ name ["syshostname"]: Font packages must declare a dependency on - xutils (>> 4.0.3) in their control + xfonts-utils in their control data. @@ -7948,7 +8484,7 @@ name ["syshostname"]: configuration file. Note that this mechanism is not the same as using app-defaults; app-defaults are tied to the client - binary on the local filesystem, whereas X resources + binary on the local file system, whereas X resources are stored in the X server and affect all connecting clients. @@ -7966,25 +8502,10 @@ name ["syshostname"]:

Packages using the X Window System should not be - configured to install files under the /usr/X11R6/ - directory unless they use imake. The + configured to install files under the + /usr/X11R6/ directory. The /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/ - directory at the maintainer's discretion. - Imake-using programs are exempt because, - as long as they are written correctly, the pathnames - 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 - that is required for these programs is a recompile - against the corresponding X Window System library - development packages. - + regarded as obsolete.

@@ -8004,25 +8525,30 @@ name ["syshostname"]:

The installation of files into subdirectories of /usr/X11R6/include/X11/ and - /usr/X11R6/lib/X11/ is permitted but discouraged; + /usr/X11R6/lib/X11/ is now prohibited; package maintainers should determine if subdirectories of /usr/lib/ and /usr/share/ can be used - instead. (The use of symbolic links from the - 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, - 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 - referred to have not been moved to other FHS-compliant - locations. + instead. +

+ +

+ Packages should install any relevant files into the + directories /usr/include/X11/ and + /usr/lib/X11/, but if they do so, they must + pre-depend on x11-common (>= + 1:7.0.0) +

+ These libraries used to be all symbolic + links. However, with X11R7, + /usr/include/X11 and /usr/lib/X11 + are now real directories, and packages + should ship their files here instead + of in /usr/X11R6/{include,lib}/X11. + x11-common (>= 1:7.0.0) is the package + responsible for converting these symlinks into + directories. +

+

@@ -8057,7 +8583,7 @@ name ["syshostname"]: binaries linked against the library (whether statically or dynamically), it is the package maintainer's responsibility to determine whether this is permitted by - the license of the copy of Motif in his or her possession. + the license of the copy of Motif in their possession.

@@ -8074,10 +8600,7 @@ name ["syshostname"]: files in the debian-policy package. It is also available from the Debian web mirrors at - and from the Debian archive mirrors at - . + id="http://www.debian.org/doc/packaging-manuals/perl-policy/">.

@@ -8112,7 +8635,7 @@ name ["syshostname"]:

Games which require protected, privileged access to - high-score files, savegames, etc., may be made + high-score files, saved games, etc., may be made set-group-id (mode 2755) and owned by root.games, and use files and directories with appropriate permissions (770 root.games, for @@ -8158,7 +8681,7 @@ 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". + details). You must not install a pre-formatted "cat page".

@@ -8174,7 +8697,7 @@ name ["syshostname"]: 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. + until a proper man page is available. It is not very hard to write a man page. See the , @@ -8186,10 +8709,10 @@ name ["syshostname"]:

- You may forward a complaint about a missing manpage to the + You may forward a complaint about a missing man page to the upstream authors, and mark the bug as forwarded in the Debian bug tracking system. Even though the GNU Project do - not in general consider the lack of a manpage to be a bug, + not in general consider the lack of a man page 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. @@ -8200,29 +8723,63 @@ name ["syshostname"]:

- If one manpage needs to be accessible via several names it + If one man page needs to be accessible via several names it 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 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 - base of the manpage tree (usually + in a .so in a man page should be relative to the + base of the man page tree (usually /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, + in the file system to the alternate names of the man page, then you should not rely on man finding your - manpage under those names based solely on the information in - the manpage's header. + man page under those names based solely on the information in + the man page's header. Supporting this in man often requires unreasonable processing time to find a manual page or to report that none exists, and moves knowledge into man's - database that would be better left in the filesystem. + database that would be better left in the file system. This support is therefore deprecated and will cease to be present in the future.

+ +

+ Manual pages in locale-specific subdirectories of + /usr/share/man should use either UTF-8 or the usual + legacy encoding for that language (normally the one corresponding + to the shortest relevant locale name in + /usr/share/i18n/SUPPORTED). For example, pages under + /usr/share/man/fr should use either UTF-8 or + ISO-8859-1. + man will automatically detect whether UTF-8 is in + use. In future, all manual pages will be required to use + UTF-8. + +

+ +

+ A country name (the DE in de_DE) should not be + included in the subdirectory name unless it indicates a + significant difference in the language, as this excludes + speakers of the language in other countries. + At the time of writing, Chinese and Portuguese are the main + languages with such differences, so pt_BR, + zh_CN, and zh_TW are all allowed. + +

+ +

+ Due to limitations in current implementations, all characters + in the manual page source should be representable in the usual + legacy encoding for that language, even if the file is + actually encoded in UTF-8. Safe alternative ways to write many + characters outside that range may be found in + . +

@@ -8273,7 +8830,7 @@ 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 + Plain text documentation should be installed in the directory /usr/share/doc/package, where package is the name of the package, and compressed with gzip -9 unless it is small. @@ -8303,7 +8860,7 @@ install-info --quiet --remove /usr/share/info/foobar.info any programs to break. . Any files that are referenced by programs but are also - useful as standalone documentation should be installed under + useful as stand alone documentation should be installed under /usr/share/package/ with symbolic links from /usr/share/doc/package.

@@ -8312,7 +8869,18 @@ install-info --quiet --remove /usr/share/info/foobar.info /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. + first package Depends on the second. +

+ Please note that this does not override the section on + changelog files below, so the file + /usr/share/package/changelog.Debian.gz + must refer to the changelog for the current version of + package in question. In practice, this means + that the sources of the target and the destination of the + symlink must be the same (same source package and + version). +

+

@@ -8368,7 +8936,14 @@ install-info --quiet --remove /usr/share/info/foobar.info In addition, the copyright file must say where the upstream 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.

+ involved with its creation. +

+ +

+ Packages in the contrib or non-free categories + should state in the copyright file that the package is not part + of the Debian GNU/Linux distribution and briefly explain why. +

A copy of the file which will be installed in @@ -8386,13 +8961,26 @@ install-info --quiet --remove /usr/share/info/foobar.info

- 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, - rather than quoting them in the copyright file. + Packages distributed under the UCB BSD license, the Apache + license (version 2.0), the Artistic license, the GNU GPL + (version 2 or 3), the GNU LGPL (versions 2, 2.1, or 3), and + the GNU FDL (version 1.2) should refer to the corresponding + files under /usr/share/common-licenses, +

+ In particular, + /usr/share/common-licenses/BSD, + /usr/share/common-licenses/Apache-2.0, + /usr/share/common-licenses/Artistic, + /usr/share/common-licenses/GPL-2, + /usr/share/common-licenses/GPL-3, + /usr/share/common-licenses/LGPL-2, + /usr/share/common-licenses/LGPL-2.1, + /usr/share/common-licenses/LGPL-3, and + /usr/share/common-licenses/GFDL-1.2 + respectively. +

+ rather than quoting them in the copyright + file.

@@ -8517,7 +9105,7 @@ install-info --quiet --remove /usr/share/info/foobar.info dpkg is a suite of programs for creating binary package files and installing and removing them on Unix systems. - dpkg is targetted primarily at Debian + dpkg is targeted primarily at Debian GNU/Linux, but may work on or be ported to other systems. @@ -8532,7 +9120,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

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

@@ -8545,8 +9133,8 @@ install-info --quiet --remove /usr/share/info/foobar.info

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. + should therefore be read in conjunction with those programs' + man pages.

@@ -8554,7 +9142,7 @@ install-info --quiet --remove /usr/share/info/foobar.info for managing various system configuration and similar issues, such as update-rc.d and install-info, are not described in detail here - - please see their manpages. + please see their man pages.

@@ -8592,7 +9180,7 @@ install-info --quiet --remove /usr/share/info/foobar.info 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) man page.

@@ -8613,7 +9201,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

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. + you want to have in the file system data part of the package. In Debian-format source packages this directory is usually debian/tmp, relative to the top of the package's source tree. @@ -8635,7 +9223,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

You need to add one special directory to the root of the - miniature filesystem tree you're creating: + miniature file system tree you're creating: DEBIAN. It should contain the control information files, notably the binary package control file (see ). @@ -8643,7 +9231,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

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

@@ -8663,7 +9251,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

- See the manpage for details of how + See the man page for details of how to examine the contents of this newly-created file. You may find the output of following commands enlightening: @@ -8673,7 +9261,7 @@ install-info --quiet --remove /usr/share/info/foobar.info To view the copyright file for a package you could use this command: - dpkg --fsys-tarfile filename.deb | tar xof usr/share/doc/\*copyright | less + dpkg --fsys-tarfile filename.deb | tar xOf - \*/copyright | pager

@@ -8728,7 +9316,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

- These are exectuable files (usually scripts) which + These are executable files (usually scripts) which dpkg runs during installation, upgrade and removal of packages. They allow the package to deal with matters which are particular to that package @@ -9236,21 +9824,10 @@ install-info --quiet --remove /usr/share/info/foobar.info encoding of . -

- Support for Unicode, and specifically UTF-8, is - steadily increasing among popular applications in - Debian. For example, in unstable, GNOME 2 has - excellent support (almost level 2) in almost all its - applications; the big remaining one is gnome-terminal, - of which one requires development versions in order to - support UTF-8 (available in Debian experimental now if - you want to play). I think that by the time sarge is - released, UTF-8 support will start to hit critical - mass.

I think it is fairly obvious that we need to eventually transition to UTF-8 for our package - infrastructure; it is really the only sane charset in + infrastructure; it is really the only sane char-set in an international environment. Now, we can't switch to using UTF-8 for package control fields and the like until dpkg has better support, but one thing we can @@ -9359,7 +9936,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

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 + the output. The parser should not attempt to synthesize it or find it from other sources.

@@ -9401,7 +9978,7 @@ install-info --quiet --remove /usr/share/info/foobar.info This is the canonical temporary location for the construction of binary packages by the binary target. The directory tmp serves as the root of - the filesystem tree as it is being constructed (for + the file system tree as it is being constructed (for example, by using the package's upstream makefiles install targets and redirecting the output there), and it also contains the DEBIAN subdirectory. See -

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

+ the upstream authors of the program. +

@@ -9490,7 +10063,7 @@ install-info --quiet --remove /usr/share/info/foobar.info automatically make the debian/rules file executable (see below).

 - +

If there is no original source code - for example, if the @@ -9498,8 +10071,8 @@ install-info --quiet --remove /usr/share/info/foobar.info maintainer is the same as the upstream maintainer - the format is slightly different: then there is no diff, and the tarfile is named - package_version.tar.gz and - contains a directory + package_version.tar.gz, + and preferably contains a directory named package-version.

@@ -9613,7 +10186,7 @@ install-info --quiet --remove /usr/share/info/foobar.info are handled specially by dpkg-source - before applying the changes it will create the debian directory, and afterwards it will make - debian/rules world-exectuable. + debian/rules world-executable.

@@ -9691,7 +10264,7 @@ install-info --quiet --remove /usr/share/info/foobar.info This field in dpkg's status file records whether the user wants a package installed, removed or left alone, whether it is broken (requiring - reinstallation) or not and what its current state on the + re-installation) or not and what its current state on the system is. Each of these pieces of information is a single word.

@@ -9723,7 +10296,7 @@ install-info --quiet --remove /usr/share/info/foobar.info Obsolete fields

- These are still recognised by dpkg but should + These are still recognized by dpkg but should not appear anywhere any more. @@ -9837,7 +10410,7 @@ install-info --quiet --remove /usr/share/info/foobar.info 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. + file system.

@@ -9942,7 +10515,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

- See the manpage for details.

@@ -10019,4 +10592,7 @@ install-info --quiet --remove /usr/share/info/foobar.info + + +