X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=4ea42e8afa2bdddc404eb02f4616b79e4ebb27d9;hb=0e70128cc33bac6d3147feb7d432e43eeb569c75;hp=7736ddb8e0e9f1ec76933d6afae1089d930d6b1f;hpb=105886046a19ef8dc906c3a2e563d8823fbbb967;p=debian%2Fdebian-policy.git
diff --git a/policy.sgml b/policy.sgml
index 7736ddb..4ea42e8 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -476,11 +476,9 @@
+ A .deb package contains two sets of files: a set of files
+ 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
+ and
+ 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
+ documented in . Only files referred to
+ specifically as control information files are the files
+ included in the control information file member of
+ the
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.
@@ -929,9 +950,9 @@- Every Debian package must have an extended description - stored in the appropriate field of the control record. - The technical information about the format of the + Every Debian package must have a Description control + field which contains a synopsis and extended description of the + package. Technical information about the format of the Description field is in .
@@ -1143,7 +1164,7 @@ must be available and usable on the system at all times, even when packages are in an unconfigured (but unpacked) state. Packages are tagged essential for a system using the - Essential control file field. The format of the + Essential control field. The format of the Essential control field is described in . @@ -1263,17 +1284,16 @@
Packages which use the Debian Configuration Management
- Specification may contain an additional
-
When
- 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
- These scripts are the files
- Additionally, packages interacting with users using
- debconf in the
+ Additionally, packages interacting with users
+ using
When a package is upgraded a combination of the scripts from @@ -4319,7 +4338,7 @@ Checksums-Sha256: In the Depends, Recommends, Suggests, Pre-Depends, Build-Depends and Build-Depends-Indep - control file fields of the package, which declare + control fields of the package, which declare dependencies on other packages, the package names listed may also include lists of alternative package names, separated by vertical bar (pipe) symbols |. In such a case, @@ -4483,7 +4502,7 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
This is done using the Depends, Pre-Depends,
Recommends, Suggests, Enhances,
- Breaks and Conflicts control file fields.
+ Breaks and Conflicts control fields.
Breaks is described in , and
Conflicts is described in . The
rest are described below.
@@ -4841,11 +4860,10 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
A virtual package is one which appears in the
- Provides control file field of another package.
- The effect is as if the package(s) which provide a
- particular virtual package name had been listed by name
- everywhere the virtual package name appears. (See also )
+ Provides control field of another package. The effect
+ is as if the package(s) which provide a particular virtual
+ package name had been listed by name everywhere the virtual
+ package name appears. (See also )
@@ -4913,9 +4931,9 @@ Provides: bar
Packages can declare in their control file that they should
- overwrite files in certain other packages, or completely
- replace other packages. The Replaces control file
- field has these two distinct purposes.
+ overwrite files in certain other packages, or completely replace
+ other packages. The Replaces control field has these
+ two distinct purposes.
This is done using the Build-Depends,
Build-Depends-Indep, Build-Conflicts and
- Build-Conflicts-Indep control file fields.
+ Build-Conflicts-Indep control fields.
@@ -5057,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
-
When packages are being built,
any
- 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.
@@ -8281,10 +8380,14 @@ done
These two files are managed through the
@@ -8333,11 +8436,13 @@ done
@@ -8603,8 +8707,9 @@ name ["syshostname"]:
Packages that provide an X server that, directly or
indirectly, communicates with real input and display
- hardware should declare in their control data that they
- provide the virtual package xserver.
Packages that provide a terminal emulator for the X Window
- System which meet the criteria listed below should declare
- in their control data that they provide the virtual
- package x-terminal-emulator. They should also
- register themselves as an alternative for
+ System which meet the criteria listed below should declare in
+ their Provides control field that they provide the
+ virtual package x-terminal-emulator. They should
+ also register themselves as an alternative for
@@ -8668,9 +8775,9 @@ name ["syshostname"]:
Packages that provide a window manager should declare in
- their control data that they provide the virtual package
- x-window-manager. They should also register
- themselves as an alternative for
+ their Provides control field that they provide the
+ virtual package x-window-manager. They should also
+ register themselves as an alternative for
It is possible to put other files in the package control
- area, but this is not generally a good idea (though they
- will largely be ignored).
+ information file area, but this is not generally a good idea
+ (though they will largely be ignored).
- Here is a brief list of the control info files supported by
-
@@ -10589,7 +10699,7 @@ END-INFO-DIR-ENTRY
- A package may contain a control area file called
+ A package may contain a control information file called
conffiles. This file should be a list of filenames
of configuration files needing automatic handling, separated
by newlines. The filenames should be absolute pathnames,
@@ -8704,6 +8811,9 @@ name ["syshostname"]:
configuration, add 10 points; otherwise add none.
+ That alternative should have a slave alternative
+ for