~vcs-imports/debian-policy/master

« back to all changes in this revision

Viewing changes to policy/ch-controlfields.rst

  • Committer: Russ Allbery
  • Author(s): Guillem Jover
  • Date: 2023-09-10 18:22:46 UTC
  • Revision ID: git-v1:01c18a882d2a21ee234f1bbc1d994e96625f2630
Clarify terminology for Debian control files

Their current descriptive names are very close and easily confused if
one is not paying close attention. Use new terminology that try to
make them less ambiguous and intuitive.

The new and unified terms are:

  * debian/control: «Debian source package template control file»
  * .dsc:           «Debian source package control file»
  * DEBIAN/control: «Debian binary package control file»
  * .changes:       «Debian upload changes control file»

For contents we use these new terms:

  First stanza in debian/control: «source package stanza»
  Next stanzas in debian/control: «binary package stanza»

Show diffs side-by-side

added added

removed removed

Lines of Context:
41
41
 
42
42
the field name is ``Package`` and the field value ``libc6``.
43
43
 
44
 
Empty field values are only permitted in source package control files
45
 
(``debian/control``). Such fields are ignored.
 
44
Empty field values are only permitted in source package template
 
45
control files (``debian/control``). Such fields are ignored.
46
46
 
47
47
A stanza must not contain more than one instance of a particular
48
48
field name.
93
93
 
94
94
.. _s-sourcecontrolfiles:
95
95
 
96
 
Source package control files -- ``debian/control``
97
 
--------------------------------------------------
 
96
Debian source package template control files -- ``debian/control``
 
97
------------------------------------------------------------------
98
98
 
99
99
The ``debian/control`` file contains the most vital (and
100
100
version-independent) information about the source package and about the
106
106
from this source package has a corresponding stanza, except for any
107
107
automatically-generated debug packages that do not require one.
108
108
 
109
 
The fields in the general stanza (the first one, for the source
110
 
package) are:
 
109
The fields in the source package stanza (the first one) are:
111
110
 
112
111
-  :ref:`Source <s-f-Source>` (mandatory)
113
112
 
172
171
 
173
172
.. _s-binarycontrolfiles:
174
173
 
175
 
Binary package control files -- ``DEBIAN/control``
176
 
--------------------------------------------------
 
174
Debian binary package control files -- ``DEBIAN/control``
 
175
---------------------------------------------------------
177
176
 
178
177
The ``DEBIAN/control`` file contains the most vital (and
179
178
version-dependent) information about a binary package. It consists of a
209
208
 
210
209
.. _s-debiansourcecontrolfiles:
211
210
 
212
 
Debian source control files -- ``.dsc``
213
 
---------------------------------------
 
211
Debian source package control files -- ``.dsc``
 
212
-----------------------------------------------
214
213
 
215
214
This file consists of a single stanza, possibly surrounded by an OpenPGP
216
215
signature. The fields of that stanza are listed below. Their syntax
249
248
 
250
249
-  :ref:`Files <s-f-Files>` (mandatory)
251
250
 
252
 
The Debian source control file is generated by ``dpkg-source`` when it
 
251
The Debian source package control file is generated by ``dpkg-source`` when it
253
252
builds the source archive, from other files in the source package,
254
253
described above. When unpacking, it is checked against the files and
255
254
directories in the other parts of the source package.
256
255
 
257
256
.. _s-debianchangesfiles:
258
257
 
259
 
Debian changes files -- ``.changes``
260
 
------------------------------------
 
258
Debian upload changes control files -- ``.changes``
 
259
---------------------------------------------------
261
260
 
262
261
The ``.changes`` files are used by the Debian archive maintenance
263
262
software to process updates to packages. They consist of a single
452
451
portable or is not useful on some architectures. Where possible, the
453
452
program should be made portable instead.
454
453
 
455
 
In the Debian source control file ``.dsc``, this field contains a list
 
454
In the Debian source package control file ``.dsc``, this field contains a list
456
455
of architectures and architecture wildcards separated by spaces. When
457
456
the list contains the architecture wildcard ``any``, the only other
458
457
value allowed in the list is ``all``.
460
459
The list may include (or consist solely of) the special value ``all``.
461
460
In other words, in ``.dsc`` files unlike the ``debian/control``, ``all``
462
461
may occur in combination with specific architectures. The
463
 
``Architecture`` field in the Debian source control file ``.dsc`` is
 
462
``Architecture`` field in the Debian source package control file ``.dsc`` is
464
463
generally constructed from the ``Architecture`` fields in the
465
464
``debian/control`` in the source package.
466
465
 
500
499
~~~~~~~~~~~~~
501
500
 
502
501
This is a boolean field which may occur only in the control file of a
503
 
binary package or in a per-package fields stanza of a source package
504
 
control file.
 
502
binary package or in a binay package stanza of a source package
 
503
template control file.
505
504
 
506
505
If set to ``yes`` then the package management system will refuse to
507
506
remove the package (upgrading and replacing it is still possible). The
773
772
``Description``
774
773
~~~~~~~~~~~~~~~
775
774
 
776
 
In a source or binary control file, the ``Description`` field contains a
777
 
description of the binary package, consisting of two parts, the synopsis
778
 
or the short description, and the long description. It is a multiline
779
 
field with the following format:
 
775
In a source template control file or binary control file, the ``Description``
 
776
field contains a description of the binary package, consisting of two parts,
 
777
the synopsis or the short description, and the long description. It is a
 
778
multiline field with the following format:
780
779
 
781
780
.. code-block:: debcontrol
782
781
 
934
933
``Installed-Size``
935
934
~~~~~~~~~~~~~~~~~~
936
935
 
937
 
This field appears in the control files of binary packages, and in the
 
936
This field appears in the binary package control files, and in the
938
937
``Packages`` files. It gives an estimate of the total amount of disk
939
938
space required to install the named package. Actual installed size may
940
939
vary based on block size, file system properties, or actions taken by
983
982
     7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
984
983
 
985
984
The :ref:`section <s-f-Section>` and :ref:`priority <s-f-Priority>` are the
986
 
values of the corresponding fields in the main source control file. If
 
985
values of the corresponding fields in the source template control file. If
987
986
no section or priority is specified then ``-`` should be used, though
988
987
section and priority values must be specified for new packages to be
989
988
installed properly.
1154
1153
 
1155
1154
Simple field containing a word indicating the type of package: ``deb``
1156
1155
for binary packages and ``udeb`` for micro binary packages. Other types
1157
 
not defined here may be indicated. In source package control files, the
1158
 
``Package-Type`` field should be omitted instead of giving it a value of
 
1156
not defined here may be indicated. In source package template control files,
 
1157
the ``Package-Type`` field should be omitted instead of giving it a value of
1159
1158
``deb``, as this value is assumed for stanzas lacking this field.
1160
1159
 
1161
1160
.. _s-f-Dgit:
1185
1184
This field is automatically added to Debian source control files
1186
1185
(``.dsc``) by ``dpkg``, with the value ``autopkgtest``, when a
1187
1186
``debian/tests/control`` file is present in the source package. This
1188
 
field may also be used in source package control files
 
1187
field may also be used in source package template control files
1189
1188
(``debian/control``) if needed in other situations.
1190
1189
 
1191
1190
.. _s-f-Rules-Requires-Root:
1304
1303
User-defined fields
1305
1304
-------------------
1306
1305
 
1307
 
Additional user-defined fields may be added to the source package
 
1306
Additional user-defined fields may be added to the source package template
1308
1307
control file. Such fields will be ignored, and not copied to (for
1309
 
example) binary or Debian source control files or upload control files.
 
1308
example) binary or Debian source control files or
 
1309
Debian upload changes control files.
1310
1310
 
1311
1311
If you wish to add additional unsupported fields to these output files
1312
1312
you should use the mechanism described here.
1317
1317
name after the hyphen will be used in the output file. Where the letter
1318
1318
``B`` is used the field will appear in binary package control files,
1319
1319
where the letter ``S`` is used in Debian source control files and where
1320
 
``C`` is used in upload control (``.changes``) files.
 
1320
``C`` is used in Debian upload changes control files.
1321
1321
 
1322
 
For example, if the main source information control file contains the
 
1322
For example, if the source package template control file contains the
1323
1323
field
1324
1324
 
1325
1325
.. code-block:: debcontrol