X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=83d42a9f38b15210852ace0932ec427480d4dc3f;hb=ba95502cd0565d860bf41a70e5dddacd93d4dad4;hp=07b3a067619a522ff81f4903133316e2e533bb87;hpb=93d621ce37d21e34aba3ac29d324e08e249fcee7;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 07b3a06..83d42a9 100644 --- a/policy.sgml +++ b/policy.sgml @@ -802,6 +802,35 @@ in the .deb file format.
+
+ 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
- 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 .
@@ -1135,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 . @@ -1255,17 +1284,16 @@
Packages which use the Debian Configuration Management
- Specification may contain an additional
-
- When
@@ -2218,12 +2254,12 @@ endif
- 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 @@ -4311,7 +4346,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, @@ -4475,7 +4510,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.
@@ -4833,11 +4868,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 )
@@ -4905,9 +4939,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.
@@ -5098,55 +5132,134 @@ Replaces: mail-transport-agent
- 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.
+ 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.
- 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).
+ 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
+ (
When packages are being built,
any
@@ -7992,6 +8127,12 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
+ 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
@@ -8496,8 +8637,7 @@ http://localhost/doc/package/filename
this so programs should not fail if
@@ -8606,8 +8746,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
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
-
@@ -10597,7 +10738,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,
@@ -8851,8 +8992,8 @@ name ["syshostname"]: