X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=15d2a95b417baf51ad57ce56fbf960b00a2c36f4;hb=ca3ca70d0ce3d1f5e19c9341f216804666d35128;hp=3d5334dcb92350f567b403ff23c6f8eaefc7ab6a;hpb=80616bc18b8b9c183fb91e7b7a791420274dd1ae;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index 3d5334d..15d2a95 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -476,11 +476,9 @@
A .deb package contains two sets of files: a set of files
- to installed on the system when the package is installed, and a
- set of files that provide additional metadata about the package or
+ to install on the system when the package is installed, and a set
+ of files that provide additional metadata about the package or
which are executed when the package is installed or removed. This
second set of files is called control information files.
Among those files are the package maintainer scripts
@@ -821,7 +819,7 @@
- There is an unfortunately collision of terminology here between
+ There is unfortunately a collision of terminology here between
control information files and files in the Debian control file
format. Throughout this document, a control file refers
to a file in the Debian control file format. These files are
@@ -880,36 +878,30 @@
In general, Debian packages should use the same version
- numbers as the upstream sources.
-
- However, in some cases where the upstream version number is
- based on a date (e.g., a development "snapshot" release) the
- package management system cannot handle these version
- numbers without epochs. For example, dpkg will consider
- "96May01" to be greater than "96Dec24".
+ numbers as the upstream sources. However, upstream version
+ numbers based on some date formats (sometimes used for
+ development or "snapshot" releases) will not be ordered
+ correctly by the package management software. For
+ example,
To prevent having to use epochs for every new upstream
- 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.
+ version, the date-based portion of any upstream version number
+ should be given in a way that sorts correctly: four-digit year
+ first, followed by a two-digit numeric month, followed by a
+ two-digit numeric date, possibly with punctuation between the
+ components.
- Note that other version formats based on dates which are
- parsed correctly by the package management system should
- not be changed.
-
- Native Debian packages (i.e., packages which have been
- written especially for Debian) whose version numbers include
- dates should always use the "YYYYMMDD" format.
+ Native Debian packages (i.e., packages which have been written
+ especially for Debian) whose version numbers include dates
+ should also follow these rules. If punctuation is desired
+ between the date components, remember that hyphen (-)
+ cannot be used in native package versions. Period
+ (.) is normally a good choice.
- When
@@ -4400,21 +4392,24 @@ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
- All fields that specify build-time relationships
+ Relationships may be restricted to a certain set of
+ architectures. This is indicated in brackets after each
+ individual package name and the optional version specification.
+ The brackets enclose a 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 while others aren't.)
+
+ For build relationship fields
(Build-Depends, Build-Depends-Indep,
- Build-Conflicts and Build-Conflicts-Indep)
- may be restricted to a certain set of architectures. This
- is indicated in brackets after each individual package name and
- the optional version specification. The brackets enclose a
- 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 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
- associated version specification are ignored completely for
- the purposes of defining the relationships.
+ Build-Conflicts and Build-Conflicts-Indep), 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
+ associated version specification are ignored completely for the
+ purposes of defining the relationships.
@@ -4430,6 +4425,29 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
gnumach-dev only on hurd-i386.
+ For binary relationship fields, the architecture restriction
+ syntax is only supported in the source package control
+ file
+ For example:
+
If the architecture-restricted dependency is part of a set of
alternatives using |, that alternative is ignored
@@ -4444,11 +4462,11 @@ Build-Depends: foo [!i386] | bar [!amd64]
- All fields that specify build-time relationships may also be
- restricted to a certain set of architectures using architecture
- wildcards. The syntax for declaring such restrictions is the
- same as declaring restrictions using a certain set of
- architectures without architecture wildcards. For example:
+ Relationships may also be restricted to a certain set of
+ architectures using architecture wildcards. The syntax for
+ declaring such restrictions is the same as declaring
+ restrictions using a certain set of architectures without
+ architecture wildcards. For example:
+ Neither Breaks nor Conflicts should be used
+ unless two packages cannot be installed at the same time or
+ installing them both causes one of them to be broken or
+ unusable. Having similar functionality or performing the same
+ tasks as another package is not sufficient reason to
+ declare Breaks or Conflicts with that package.
+
A Conflicts entry may have an "earlier than" version
clause if the reason for the conflict is corrected in a later
@@ -5048,7 +5075,7 @@ Replaces: mail-transport-agent
There is no Build-Depends-Arch; this role is essentially
met with Build-Depends. Anyone building the
- build-indep and binary-indep targets is
+ build-indep and binary-indep targets is
assumed to be building the whole package, and therefore
installation of all build dependencies is required.
- Packages involving shared libraries should be split up into - several binary packages. This section mostly deals with how - this separation is to be accomplished; rules for files within - the shared library packages are in instead. + This section deals only with public shared libraries: shared + libraries that are placed in directories searched by the dynamic + linker by default or which are intended to be linked against + normally and possibly used by other, independent packages. Shared + libraries that are internal to a particular package or that are + only loaded as dynamic modules are not covered by this section and + are not subject to its requirements.
-
+ A shared library is identified by the SONAME attribute
+ stored in its dynamic section. When a binary is linked against a
+ shared library, the SONAME of the shared library is
+ recorded in the binary's NEEDED section so that the
+ dynamic linker knows that library must be loaded at runtime. The
+ shared library file's full name (which usually contains additional
+ version information not needed in the SONAME) is
+ therefore normally not referenced directly. Instead, the shared
+ library is loaded by its SONAME, which exists on the file
+ system as a symlink pointing to the full name of the shared
+ library. This symlink must be provided by the
+ package. describes how to do this.
+
- 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.
- If you have several shared libraries built from the same - source tree you may lump them all together into a single - shared library package, provided that you change all of - their sonames at once (so that you don't get filename - clashes if you try to install different versions of the - combined shared libraries package). + Shared libraries are normally split into several binary packages. + The SONAME symlink is installed by the runtime shared + library package, and the bare .so symlink is installed in + the development package since it's only used when linking binaries + or shared libraries. However, there are some exceptions for + unusual shared libraries or for shared libraries that are also + loaded as dynamic modules by other programs.
++ This section is primarily concerned with how the separation of + shared libraries into multiple packages should be done and how + dependencies on and between shared library binary packages are + managed in Debian. should be read in + conjunction with this section and contains additional rules for + the files contained in the shared library packages. +
+ +
+ The run-time shared library must be placed in a package
+ whose name changes whenever the SONAME of the shared
+ library changes. This allows several versions of the shared
+ library to be installed at the same time, allowing installation
+ of the new version of the shared library without immediately
+ breaking binaries that depend on the old version. Normally, the
+ run-time shared library and its SONAME symlink should
+ be placed in a package named
+
+ If you have several shared libraries built from the same source + tree, you may lump them all together into a single shared + library package provided that all of their SONAMEs will + always change together. Be aware that this is not normally the + case, and if the SONAMEs do not change together, + upgrading such a merged shared library package will be + unnecessarily difficult because of file conflicts with the old + version of the package. When in doubt, always split shared + library packages so that each binary package installs a single + shared library. +
+ ++ Every time the shared library ABI changes in a way that may + break binaries linked against older versions of the shared + library, the SONAME of the library and the + corresponding name for the binary package containing the runtime + shared library should change. Normally, this means + the SONAME should change any time an interface is + removed from the shared library or the signature of an interface + (the number of parameters or the types of parameters that it + takes, for example) is changed. This practice is vital to + allowing clean upgrades from older versions of the package and + clean transitions between the old ABI and new ABI without having + to upgrade every affected package simultaneously. +
+ +
+ The SONAME and binary package name need not, and indeed
+ normally should not, change if new interfaces are added but none
+ are removed or changed, since this will not break binaries
+ linked against the old shared library. Correct versioning of
+ dependencies on the newer shared library by binaries that use
+ the new interfaces is handled via
+ the
The package should install the shared libraries under
their normal names. For example, the
- The run-time library package should include the symbolic link that
-
+ If the package provides Ada Library Information
+ (
- You must specify the gcc option -D_REENTRANT - when building a library (either static or shared) to make - the library compatible with LinuxThreads. + Libraries should be built with threading support and to be + thread-safe if the library supports this.
@@ -7946,7 +8061,7 @@ endscript
@@ -7987,6 +8102,12 @@ endscript
+
+ Control information files should be owned by root:root
+ and either mode 644 (for most files) or mode 755 (for
+ executables such as
Setuid and setgid executables should be mode 4755 or 2755 @@ -8273,10 +8394,14 @@ done
These two files are managed through the
@@ -8325,11 +8450,13 @@ done
@@ -8696,6 +8825,9 @@ name ["syshostname"]:
configuration, add 10 points; otherwise add none.
+ That alternative should have a slave alternative
+ for