X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=ae7149ff130ac8c9b8bc39ccbe62db152ed9a82f;hb=6e1b2d9c86e05355da2081276decbf3ae3fce4c2;hp=532fcf220ed7cf02861b39b8fe6fc8b5bd85b93f;hpb=81370db444e19bc938e5be6936c78b1ce6160ce6;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index 532fcf2..ae7149f 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -46,7 +46,7 @@
This manual is distributed via the Debian package
-
@@ -165,14 +168,21 @@
the Debian web mirrors at
The
@@ -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.
- 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
-
-
-
- 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
- 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:
- 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
- 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. -
-- 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:
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.
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"+ 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
@@ -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).
- 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
- 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. -
-
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
@@ -1266,7 +1209,7 @@
.
The
+ 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
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
Changes in the Debian version of the package should be
briefly explained in the Debian changelog file
-
+ Mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting
+ history" by editing old changelog entries.
+
- 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
@@ -1618,8 +1567,7 @@
The date should be in RFC822 format
+ Every package must be accompanied by a verbatim copy of
+ its copyright and distribution license in the file
+
+ 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.
+ +
+ 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.
+ The meaning of the following tags has been standardized:
+
+ Unknown flags must be ignored by
+ 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.
+
+ 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
+ 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.
+ If running
+ 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. +
+ +
+
- 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
@@ -2272,6 +2445,7 @@ Package: libc6
- In a main source control information, a
- In the control file of a binary package it may be followed
- by a version number in parentheses
+ 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
+
+ Any parser that interprets the Uploaders field in
+
- By default,
- By default,
@@ -2650,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. @@ -2664,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.
@@ -2674,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. @@ -2714,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.
@@ -2779,7 +2975,7 @@ 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
@@ -3110,6 +3315,19 @@ Package: libc6
+ 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 + <>. +
+
These scripts are the files
@@ -3192,6 +3411,13 @@ Package: libc6 well.
+
+ Additionally, packages interacting with users using
+ debconf in the
When a package is upgraded a combination of the scripts from
the old and new packages is called during the upgrade
@@ -3216,7 +3442,7 @@ Package: libc6
It is necessary for the error recovery procedures that the @@ -3252,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
- 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.
+ If that works, then
+
+ If it fails, then the old version is left + in an "Half-Installed" state. +
+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.
@@ -3690,9 +3991,26 @@ Package: libc6
+ If prerm fails during replacement due to conflict
+
+ If this fails, the package is in a "Failed-Config"
+ state, or else it remains "Installed".
+
+ If it fails, there's no error unwind, and the package is in
+ an "Half-Installed" state.
+
@@ -3723,19 +4046,21 @@ Package: libc6
are removed.
+ If this fails, the package remains in a "Config-Files"
+ state.
+
@@ -3816,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 @@ -3859,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).
@@ -3887,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
@@ -3898,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. @@ -4026,6 +4373,53 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
++ 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,
+
+ 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. +
+- 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.
@@ -4273,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
@@ -4338,10 +4735,21 @@ Replaces: mail-transport-agent
- The run-time shared library needs to be placed in a package called
-
+ 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.
+ 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
+
If you have several shared libraries built from the same
source tree you may lump them all together into a single
@@ -4425,11 +4848,9 @@ Replaces: mail-transport-agent
listed in
-
- The package must call
During install or upgrade, the preinst is called before
the new files are installed, so calling "ldconfig" is
@@ -4479,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.
+
+
+ If you are creating a udeb for use in the Debian Installer, you
+ will need to specify that
For more details on dpkg-shlibdeps, please see
and
@@ -4827,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:
+ 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 @@ -4844,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.
+ As zlib1g also provides a udeb containing the shared library,
+ there would also be a second line:
+
- If your package provides a shared library, you should create
+ If your package provides a shared library, you need to create
a
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
+
+ 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
+ The requirement that
+
+ The requirement that windowmanagers with a single
+ configuration file call it
+ The requirement that boot manager configuration
+ files live in
+ The version of this document referred here can be
+ found in the debian-policy package or on
However, the package may create empty directories below
- 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
- The
Often there are some variables in the
For more information about using update-rc.d,
- please consult its manpage
- The use of
@@ -5613,7 +6131,7 @@ test -f program-executed-later-in-script || exit 0
<action> in their
For more information about using
-
- The
-
- Complementing the above init script is a configuration
- file
- Another example on which you can base your
+ An example on which you can base your
- If this package is happy with the default setup from
-
- 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
- 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.
@@ -5826,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):
- For example, stopping the printer daemon will like
- like this:
+ For example, stopping the printer daemon will look like
+ this:
- 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
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
-
@@ -6041,17 +6453,14 @@ Reloading description configuration...done.
files in the debian-policy package.
It is also available from the Debian web mirrors at
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
+ The
+ Please refer to the documentation that comes with the
+
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. -
- -
-
- 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.
-
@@ -6405,13 +6786,70 @@ endif
+ 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.
+
+ 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
@@ -6553,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 (
- The standard shell interpreter
- You may wish to restrict your script to POSIX features when
- possible so that it may use
+ You may wish to restrict your script to SUSv3 features plus the
+ above set when possible so that it may use
Any scripts which create files in world-writeable
directories (e.g., in
@@ -6742,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
+
+ 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
@@ -6962,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.
@@ -7072,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.
@@ -7107,7 +7590,7 @@ endscript
normally have their permissions reset to the distributed
permissions when the package is reinstalled. However,
the use of
-
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
@@ -7216,9 +7690,13 @@ endscript
If a program needs to specify an architecture specification
- string in some place, the following format should be
- used: arch-os 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
+
@@ -7316,7 +7824,7 @@ done
The files
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
+
Web Document Root
@@ -7437,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 +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. +
+
- 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
@@ -7676,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.
@@ -7718,7 +8253,7 @@ name ["syshostname"]:
Packages using the X Window System should not be
- configured to install files under the
@@ -8005,25 +8525,30 @@ name ["syshostname"]:
The installation of files into subdirectories
of
- Packages must not provide or install files into the directories
-
+ Packages should install any relevant files into the
+ directories
+ 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.
+
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
@@ -8159,7 +8681,7 @@ name ["syshostname"]:
You should install manual pages in
@@ -8175,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.
- 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. @@ -8201,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
+ Manual pages in locale-specific subdirectories of
+
+ 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.
+ 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
+
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
+ Please note that this does not override the section on
+ changelog files below, so the file
+
@@ -8369,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 @@ -8387,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
+ In particular,
+
@@ -8518,7 +9105,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
This manual describes the technical aspects of creating Debian
binary packages (
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.
@@ -8555,7 +9142,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
for managing various system configuration and similar issues,
such as
@@ -8593,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
-
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
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:
The
- See the manpage
- These are exectuable files (usually scripts) which
+ These are executable files (usually scripts) which
- 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
@@ -9360,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.
This is a compressed (with gzip -9)
If there is no original source code - for example, if the
@@ -9499,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
-
- These are still recognised by
@@ -9943,7 +10515,7 @@ install-info --quiet --remove /usr/share/info/foobar.info
- See the manpage