po: Update German man pages translation
[dpkg.git] / man / dsc.pod
blobf82fdc966f97717aa3806c6bc57656df0dc4b70b
1 # dpkg manual page - dsc(5)
3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
4 # Copyright © 2015 Guillem Jover <guillem@debian.org>
6 # This is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; either version 2 of the License, or
9 # (at your option) any later version.
11 # This is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
19 =encoding utf8
21 =head1 NAME
23 dsc - Debian source package control file format
25 =head1 SYNOPSIS
27 I<filename>B<.dsc>
29 =head1 DESCRIPTION
31 Each Debian source package is composed of a .dsc control file, which
32 contains a number of fields, in L<deb822(5)> format.
34 Each field begins with a tag, such as
35 B<Source>
37 B<Binary>
38 (case insensitive), followed by a colon, and the body of the field
39 (case sensitive unless stated otherwise).
40 Fields are delimited only by field tags.
41 In other words, field text may be multiple lines in length, but the
42 installation tools will generally join lines when processing the body
43 of the field (except in case of the multiline fields
44 B<Package-List>, B<Files>, B<Checksums-Sha1> and B<Checksums-Sha256>,
45 see below).
47 The control data might be enclosed in an OpenPGP ASCII Armored signature,
48 as specified in RFC4880.
50 =head1 FIELDS
52 =over
54 =item B<Format:> I<format-version> (required)
56 The value of this field declares the format version of the source package.
57 The field value is used by programs acting on a source package to
58 interpret the list of files in the source package and determine how
59 to unpack it.
60 The syntax of the field value is a numeric major revision (“0-9”), a
61 period (“.”), a numeric minor revision (“0-9”), and then an optional
62 subtype after whitespace (“ \t”), which if specified is a lowercase
63 alphanumeric (“a-z0-9”) word in parentheses (“()”).
64 The subtype is optional in the syntax but may be mandatory for particular
65 source format revisions.
67 The source formats currently supported by B<dpkg> are B<1.0>,
68 B<2.0>, B<3.0 (native)>, B<3.0 (quilt)>, B<3.0 (git)>,
69 B<3.0 (bzr)> and B<3.0 (custom)>.
70 See L<dpkg-source(1)> for their description.
72 =item B<Source:> I<source-name> (required)
74 The value of this field determines the package name, and is used to
75 generate file names by most installation tools.
77 =item B<Binary:> I<binary-package-list>
79 This folded field lists binary packages which this source package can produce,
80 separated by commas.
82 This field has now been superseded by the B<Package-List> field, which
83 gives enough information about what binary packages are produced on which
84 architecture, build-profile and other involved restrictions.
86 =item B<Architecture:> I<arch-list> (recommended)
88 A list of architectures and architecture wildcards separated by spaces
89 which specify the type of hardware this package can be compiled for.
90 Common architecture names and architecture wildcards are B<amd64>,
91 B<armel>, B<i386>, B<linux-any>, B<any-amd64>, etc.
93 Note that the B<all> value is meant for packages that are architecture
94 independent, and B<any> for packages that are architecture dependent.
95 The list may include (or consist solely of) the special value B<all>.
96 When the list contains the architecture wildcard B<any>, the only
97 other value allowed in the list is B<all>.
99 The field value is generally generated from B<Architecture> fields
100 from in the I<debian/control> in the source package.
102 =item B<Version:> I<version-string> (required)
104 Typically, this is the original package's version number in whatever form
105 the program's author uses.
106 It may also include a Debian revision number (for non-native packages).
107 The exact format and sorting algorithm are described in
108 L<deb-version(7)>.
110 =item B<Origin:> I<name>
112 The name of the distribution this package is originating from.
114 =item B<Maintainer:> I<fullname-email> (recommended)
116 Should be in the format “Joe Bloggs E<lt>jbloggs@foo.comE<gt>”, and is
117 typically the person who created the package, as opposed to the author
118 of the software that was packaged.
120 =item B<Uploaders:> I<fullname-email-list>
122 Lists all the names and email addresses of co-maintainers of the package,
123 in the same format as the B<Maintainer> field.
124 Multiple co-maintainers should be separated by a comma.
126 =item B<Description> I<short-description>
128 =item S< >I<long-description>
130 The format for the source package description is a short brief summary on the
131 first line (after the B<Description> field).
132 The following lines should be used as a longer, more detailed description.
133 Each line of the long description must be preceded by a space, and blank
134 lines in the long description must contain a single ‘B<.>’ following
135 the preceding space.
137 =item B<Homepage:> I<url>
139 The upstream project home page I<url>.
141 =item B<Standards-Version:> I<version-string> (recommended)
143 This documents the most recent version of the distribution policy standards
144 this package complies with.
146 =item B<Vcs-Browser:> I<url>
148 The I<url> of a web interface to browse the Version Control System
149 repository.
151 =item B<Vcs-Arch:> I<url>
153 =item B<Vcs-Bzr:> I<url>
155 =item B<Vcs-Cvs:> I<url>
157 =item B<Vcs-Darcs:> I<url>
159 =item B<Vcs-Git:> I<url>
161 =item B<Vcs-Hg:> I<url>
163 =item B<Vcs-Mtn:> I<url>
165 =item B<Vcs-Svn:> I<url>
167 These fields declare the I<url> of the Version Control System repository
168 used to maintain this package.
169 See L<deb-src-control(5)> for more details.
171 =item B<Testsuite:> I<name-list>
173 This field declares that the source package contains the specified test suites.
174 The value is a comma-separated list of test suites.
175 If the B<autopkgtest> value is present, a I<debian/tests/control> is
176 expected to be present, if the file is present but not the value, then
177 B<dpkg-source> will automatically add it, preserving previous values.
179 =item B<Testsuite-Triggers:> I<package-list>
181 This field declares the comma-separated union of all test dependencies
182 (B<Depends> fields in I<debian/tests/control> file), with all
183 restrictions removed, and OR dependencies flattened (that is, converted to
184 separate AND relationships), except for binaries generated by this source
185 package and its meta-dependency equivalent B<@>.
187 B<Rationale>: this field is needed because otherwise to be able to get the
188 test dependencies, each source package would need to be unpacked.
190 =item B<Build-Depends:> I<package-list>
192 =item B<Build-Depends-Arch:> I<package-list>
194 =item B<Build-Depends-Indep:> I<package-list>
196 =item B<Build-Conflicts:> I<package-list>
198 =item B<Build-Conflicts-Arch:> I<package-list>
200 =item B<Build-Conflicts-Indep:> I<package-list>
202 These fields declare relationships between the source package and packages
203 used to build it.
204 They are discussed in the L<deb-src-control(5)> manual page.
206 =item B<Package-List:>
208 =item S< >I<package> I<package-type> I<section> I<priority> I<key-value-list>
210 This multiline field contains a list of binary packages generated by this
211 source package.
213 The I<package> is the binary package name.
215 The I<package-type> is the binary package type, usually B<deb>, another
216 common value is B<udeb>.
218 The I<section> and I<priority> match the binary package fields of the
219 same name.
221 The I<key-value-list> is a space separated I<key>B<=>I<value> list,
222 and the currently known optional keys are:
224 =over
226 =item B<arch>
228 The architecture restriction from the binary package B<Architecture>
229 field, with spaces converted to ‘,’.
231 =item B<profile>
233 The normalized build-profile restriction formula from the binary package
234 B<Build-Profile> field, with ORs converted to ‘+’ and ANDs to
235 ‘,’.
237 =item B<protected>
239 If the binary package is protected, this key will contain the value of the
240 B<Protected> field, that is a B<yes> value.
242 Supported since dpkg 1.20.1.
244 =item B<essential>
246 If the binary package is essential, this key will contain the value of the
247 B<Essential> field, that is a B<yes> value.
249 =back
251 =item B<Files:> (required, weak)
253 =item B<Checksums-Sha1:> (required, weak)
255 =item B<Checksums-Sha256:> (required, strong)
257 =item S< >I<checksum> I<size> I<filename>
259 These multiline fields contain a list of files with a checksum and size
260 for each one.
261 These fields have the same syntax and differ only in the checksum algorithm
262 used: MD5 for B<Files>, SHA-1 for B<Checksums-Sha1> and SHA-256 for
263 B<Checksums-Sha256>.
265 The first line of the field value (the part on the same line as the field
266 name followed by a colon) is always empty.
267 The content of the field is expressed as continuation lines, one line per file.
268 Each line consists of the checksum, a space, the file size, a space, and the
269 file name.
271 These fields list all files that make up the source package.
272 The list of files in these fields must match the list of files in the
273 other related fields.
275 B<Note>: The MD5 and SHA-1 checksums are considered weak,
276 and should never be assumed to be sufficient for secure verification.
278 =back
280 =head1 BUGS
282 The B<Format> field conflates the format for the B<.dsc> file itself
283 and the format of the extracted source package.
285 =head1 SEE ALSO
287 L<deb822(5)>,
288 L<deb-src-control(5)>,
289 L<deb-version(7)>,
290 L<dpkg-source(1)>.