From: Russ Allbery Date: Sun, 4 Jul 2010 01:11:48 +0000 (-0700) Subject: Use consistent terminology for control files X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=80616bc18b8b9c183fb91e7b7a791420274dd1ae;p=debian%2Fdebian-policy.git Use consistent terminology for control files Introduce control information files, which refer to the members of the control.tar.gz part of the .deb, and change terminology to be consistent about that term, control files, and control fields. --- diff --git a/policy.sgml b/policy.sgml index bad28af..3d5334d 100644 --- a/policy.sgml +++ b/policy.sgml @@ -804,6 +804,35 @@ in the .deb file format.

+

+ 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 + 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 control, the binary + package control file that contains the control fields for + the package. Other control information files + include the shlibs + file used to store shared library dependency information + and the conffiles file that lists the package's + configuration files (described in ). +

+ +

+ There is an unfortunately 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 .deb file format used by binary packages. Most + control information files are not in the Debian control file + format. +

+ The package name @@ -929,9 +958,9 @@ The description of a package

- 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 +1172,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 +1292,16 @@

Packages which use the Debian Configuration Management - Specification may contain an additional - config script and a templates - file in their control archive - The control.tar.gz inside the .deb. - See . - . - The config script might be run before the - preinst script, and before the package is unpacked - or any of its dependencies or pre-dependencies are satisfied. - Therefore it must work using only the tools present in - essential packages. + Specification may contain the additional control information + files config + and templates. config is an + additional maintainer script used for package configuration, + and templates contains templates used for user + prompting. The config script might be run before + the preinst script and before the package is + unpacked 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 implements the Debian Configuration Management Specification will also be installed, and any @@ -2200,7 +2228,7 @@ endif

When dpkg-gencontrol, dpkg-genchanges and dpkg-source - generate control files they perform variable substitutions + generate control files, they perform variable substitutions on their output just before writing it. Variable substitutions have the form ${variable}. The optional file debian/substvars contains @@ -2226,12 +2254,12 @@ endif 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 + This is an optional, recommended configuration 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.

@@ -3618,12 +3646,11 @@ Checksums-Sha256:

- 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 + These scripts are the control information + files preinst, postinst, prerm + and postrm. 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.

@@ -3638,12 +3665,12 @@ Checksums-Sha256: they exit with a zero status if everything went well.

-

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

+

+ Additionally, packages interacting with users + using debconf in the postinst script + should install a config script as a control + information file. See for details. +

When a package is upgraded a combination of the scripts from @@ -4319,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, @@ -4457,7 +4484,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. @@ -4806,11 +4833,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 )

@@ -4878,9 +4904,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.

Overwriting files in other packages @@ -5007,7 +5033,7 @@ Replaces: mail-transport-agent

This is done using the Build-Depends, Build-Depends-Indep, Build-Conflicts and - Build-Conflicts-Indep control file fields. + Build-Conflicts-Indep control fields.

@@ -5498,10 +5524,10 @@ Replaces: mail-transport-agent

When packages are being built, any debian/shlibs files are copied into the - control file area of the temporary build directory and - given the name shlibs. These files give - details of any shared libraries included in the same - package. + control information file area of the temporary build + directory and given the name shlibs. These + files give details of any shared libraries included in the + same package. An example may help here. Let us say that the source package foo generates two binary packages, libfoo2 and foo-runtime. @@ -5702,7 +5728,8 @@ udeb: libz 1 zlib1g-udeb (>= 1:1.1.3) It is usual to call this file debian/shlibs (but if you have multiple binary packages, you might want to call it debian/shlibs.package instead). Then - let debian/rules install it in the control area: + let debian/rules install it in the control + information file area: install -m644 debian/shlibs debian/tmp/DEBIAN @@ -5711,9 +5738,9 @@ install -m644 debian/shlibs debian/tmp/DEBIAN install -m644 debian/shlibs.package debian/package/DEBIAN/shlibs An alternative way of doing this is to create the - shlibs file in the control area directly from - debian/rules without using a debian/shlibs - file at all, + shlibs file in the control information file area + directly from debian/rules without using + a debian/shlibs file at all, This is what dh_makeshlibs in the debhelper suite does. If your package also has a udeb that provides a shared @@ -8458,8 +8485,7 @@ http://localhost/doc/package/filename this so programs should not fail if newaliases cannot be found. Note that because of this, all MTA packages must have Provides, Conflicts and - Replaces: mail-transport-agent control file - fields. + Replaces: mail-transport-agent control fields.

@@ -8568,8 +8594,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. + hardware should declare in their Provides control + field that they provide the virtual + package xserver. This implements current practice, and provides an actual policy for usage of the xserver virtual package which appears in the virtual packages @@ -8587,10 +8614,10 @@ name ["syshostname"]:

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 /usr/bin/x-terminal-emulator, with a priority of 20.

@@ -8633,9 +8660,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 /usr/bin/x-window-manager, with a priority calculated as follows: @@ -8808,8 +8835,8 @@ name ["syshostname"]: Font packages must declare a dependency on - xfonts-utils in their control - data. + xfonts-utils in their Depends + or Pre-Depends control field. @@ -9677,13 +9704,13 @@ END-INFO-DIR-ENTRY

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 - dpkg and a summary of what they're used for. + Here is a brief list of the control information files supported + by dpkg and a summary of what they're used for.

@@ -10554,7 +10581,7 @@ END-INFO-DIR-ENTRY Package_Revision The Debian revision part of the package version was - at one point in a separate control file field. This + at one point in a separate control field. This field went through several names. @@ -10611,7 +10638,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,