man/dsc.pod

   1 # dpkg manual page - dsc(5)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2015 Guillem Jover <guillem@debian.org>
   5 #
   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.
  10 #
  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.
  15 #
  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/>.
  18
  19 =encoding utf8
  20
  21 =head1 NAME
  22
  23 dsc - Debian source package control file format
  24
  25 =head1 SYNOPSIS
  26
  27 I<filename>B<.dsc>
  28
  29 =head1 DESCRIPTION
  30
  31 Each Debian source package is composed of a .dsc control file, which
  32 contains a number of fields, in L<deb822(5)> format.
  33
  34 Each field begins with a tag, such as
  35 B<Source>
  36 or
  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).
  46
  47 The control data might be enclosed in an OpenPGP ASCII Armored signature,
  48 as specified in RFC9580.
  49
  50 =head1 FIELDS
  51
  52 =over
  53
  54 =item B<Format:> I<format-version> (required)
  55
  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.
  66
  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.
  71
  72 =item B<Source:> I<source-name> (required)
  73
  74 The value of this field determines the package name, and is used to
  75 generate file names by most installation tools.
  76
  77 =item B<Binary:> I<binary-package-list>
  78
  79 This folded field lists binary packages which this source package can produce,
  80 separated by commas.
  81
  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.
  85
  86 =item B<Architecture:> I<arch-list> (recommended)
  87
  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.
  92
  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>.
  98
  99 The field value is generally generated from B<Architecture> fields
 100 from in the I<debian/control> in the source package.
 101
 102 =item B<Version:> I<version-string> (required)
 103
 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)>.
 109
 110 =item B<Origin:> I<name>
 111
 112 The name of the distribution this package is originating from.
 113
 114 =item B<Maintainer:> I<fullname-email> (recommended)
 115
 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.
 119
 120 =item B<Uploaders:> I<fullname-email-list>
 121
 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.
 125
 126 =item B<Description> I<short-description>
 127
 128 =item S< >I<long-description>
 129
 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.
 136
 137 =item B<Homepage:> I<url>
 138
 139 The upstream project home page I<url>.
 140
 141 =item B<Standards-Version:> I<version-string> (recommended)
 142
 143 This documents the most recent version of the distribution policy standards
 144 this package complies with.
 145
 146 =item B<Vcs-Browser:> I<url>
 147
 148 The I<url> of a web interface to browse the Version Control System
 149 repository.
 150
 151 =item B<Vcs-Arch:> I<url>
 152
 153 =item B<Vcs-Bzr:> I<url>
 154
 155 =item B<Vcs-Cvs:> I<url>
 156
 157 =item B<Vcs-Darcs:> I<url>
 158
 159 =item B<Vcs-Git:> I<url>
 160
 161 =item B<Vcs-Hg:> I<url>
 162
 163 =item B<Vcs-Mtn:> I<url>
 164
 165 =item B<Vcs-Svn:> I<url>
 166
 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.
 170
 171 =item B<Testsuite:> I<name-list>
 172
 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.
 178
 179 =item B<Testsuite-Triggers:> I<package-list>
 180
 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<@>.
 186
 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.
 189
 190 =item B<Build-Depends:> I<package-list>
 191
 192 =item B<Build-Depends-Arch:> I<package-list>
 193
 194 =item B<Build-Depends-Indep:> I<package-list>
 195
 196 =item B<Build-Conflicts:> I<package-list>
 197
 198 =item B<Build-Conflicts-Arch:> I<package-list>
 199
 200 =item B<Build-Conflicts-Indep:> I<package-list>
 201
 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.
 205
 206 =item B<Package-List:>
 207
 208 =item S< >I<package> I<package-type> I<section> I<priority> I<key-value-list>
 209
 210 This multiline field contains a list of binary packages generated by this
 211 source package.
 212
 213 The I<package> is the binary package name.
 214
 215 The I<package-type> is the binary package type, usually B<deb>, another
 216 common value is B<udeb>.
 217
 218 The I<section> and I<priority> match the binary package fields of the
 219 same name.
 220
 221 The I<key-value-list> is a space separated I<key>B<=>I<value> list,
 222 and the currently known optional keys are:
 223
 224 =over
 225
 226 =item B<arch>
 227
 228 The architecture restriction from the binary package B<Architecture>
 229 field, with spaces converted to ‘,’.
 230
 231 =item B<profile>
 232
 233 The normalized build-profile restriction formula from the binary package
 234 B<Build-Profile> field, with ORs converted to ‘+’ and ANDs to
 235 ‘,’.
 236
 237 =item B<protected>
 238
 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.
 241
 242 Supported since dpkg 1.20.1.
 243
 244 =item B<essential>
 245
 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.
 248
 249 =back
 250
 251 =item B<Files:> (required, weak)
 252
 253 =item B<Checksums-Sha1:> (required, weak)
 254
 255 =item B<Checksums-Sha256:> (required, strong)
 256
 257 =item S< >I<checksum> I<size> I<filename>
 258
 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>.
 264
 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.
 270
 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.
 274
 275 B<Note>: The MD5 and SHA-1 checksums are considered weak,
 276 and should never be assumed to be sufficient for secure verification.
 277
 278 =back
 279
 280 =head1 BUGS
 281
 282 The B<Format> field conflates the format for the B<.dsc> file itself
 283 and the format of the extracted source package.
 284
 285 =head1 SEE ALSO
 286
 287 L<deb822(5)>,
 288 L<deb-src-control(5)>,
 289 L<deb-version(7)>,
 290 L<dpkg-source(1)>.