man/dsc.man

   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 .TH dsc 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  20 .nh
  21 .SH NAME
  22 dsc \- Debian source packages' control file format
  23 .
  24 .SH SYNOPSIS
  25 .IB filename .dsc
  26 .
  27 .SH DESCRIPTION
  28 Each Debian source package is composed of a .dsc control file, which
  29 contains a number of fields.
  30 Each field begins with a tag, such as
  31 .B Source
  32 or
  33 .B Binary
  34 (case insensitive), followed by a colon, and the body of the field.
  35 Fields are delimited only by field tags.
  36 In other words, field text may be multiple lines in length, but the
  37 installation tools will generally join lines when processing the body
  38 of the field (except in case of the multiline fields
  39 .BR Package\-List ", " Files ", " Checksums\-Sha1 " and " Checksums\-Sha256 ,
  40 see below).
  41 .PP
  42 The control data might be enclosed in an OpenPGP ASCII Armored signature,
  43 as specified in RFC4880.
  44 .
  45 .SH FIELDS
  46 .TP
  47 .BR Format: " \fIformat-version\fP (required)"
  48 The value of this field declares the format version of the source package.
  49 The field value is used by programs acting on a source package to
  50 interpret the list of files in the source package and determine how
  51 to unpack it.
  52 The syntax of the field value is a numeric major revision (“0-9”), a
  53 period (“.”), a numeric minor revision (“0-9”), and then an optional
  54 subtype after whitespace (“\ \\t”), which if specified is a lowercase
  55 alphanumeric (“a-z0-9”) word in parentheses (“()”).
  56 The subtype is optional in the syntax but may be mandatory for particular
  57 source format revisions.
  58
  59 The source formats currently supported by \fBdpkg\fP are \fB1.0\fP,
  60 \fB2.0\fP, \fB3.0 (native)\fP, \fB3.0 (quilt)\fP, \fB3.0 (git)\fP,
  61 \fB3.0 (bzr)\fP and \fB3.0 (custom)\fP.
  62 See \fBdpkg\-source\fP(1) for their description.
  63 .TP
  64 .BR Source: " \fIsource-name\fP (required)"
  65 The value of this field determines the package name, and is used to
  66 generate file names by most installation tools.
  67 .TP
  68 .BI Binary: " binary-package-list"
  69 This folded field lists binary packages which this source package can produce,
  70 separated by commas.
  71
  72 This field has now been superseded by the \fBPackage\-List\fP field, which
  73 gives enough information about what binary packages are produced on which
  74 architecture, build-profile and other involved restrictions.
  75 .TP
  76 .BR Architecture: " \fIarch-list\fP (recommended)"
  77 A list of architectures and architecture wildcards separated by spaces
  78 which specify the type of hardware this package can be compiled for.
  79 Common architecture names and architecture wildcards are \fBamd64\fP,
  80 \fBarmel\fP, \fBi386\fP, \fBlinux\-any\fP, \fBany\-amd64\fP, etc.
  81
  82 Note that the \fBall\fP value is meant for packages that are architecture
  83 independent, and \fBany\fP for packages that are architecture dependent.
  84 The list may include (or consist solely of) the special value \fBall\fP.
  85 When the list contains the architecture wildcard \fBany\fP, the only
  86 other value allowed in the list is \fBall\fP.
  87
  88 The field value is generally generated from \fBArchitecture\fP fields
  89 from in the \fIdebian/control\fP in the source package.
  90 .TP
  91 .BR Version: " \fIversion-string\fP (required)"
  92 Typically, this is the original package's version number in whatever form
  93 the program's author uses.
  94 It may also include a Debian revision number (for non-native packages).
  95 The exact format and sorting algorithm are described in
  96 .BR deb\-version (7).
  97 .TP
  98 .BI Origin: " name"
  99 The name of the distribution this package is originating from.
 100 .TP
 101 .BR Maintainer: " \fIfullname-email\fP (recommended)"
 102 Should be in the format “Joe Bloggs <jbloggs@foo.com>”, and is
 103 typically the person who created the package, as opposed to the author
 104 of the software that was packaged.
 105 .TP
 106 .BI Uploaders: " fullname-email-list"
 107 Lists all the names and email addresses of co-maintainers of the package,
 108 in the same format as the \fBMaintainer\fP field.
 109 Multiple co-maintainers should be separated by a comma.
 110 .TP
 111 .BI Description " \fIshort-description\fP"
 112 .TQ
 113 .BI " " "long-description"
 114 The format for the source package description is a short brief summary on the
 115 first line (after the \fBDescription\fP field).
 116 The following lines should be used as a longer, more detailed description.
 117 Each line of the long description must be preceded by a space, and blank
 118 lines in the long description must contain a single ‘\fB.\fP’ following
 119 the preceding space.
 120 .TP
 121 .BI Homepage: " url"
 122 The upstream project home page \fIurl\fP.
 123 .TP
 124 .BR Standards\-Version: " \fIversion-string\fP (recommended)"
 125 This documents the most recent version of the distribution policy standards
 126 this package complies with.
 127 .TP
 128 .BI Vcs\-Browser: " url"
 129 The \fIurl\fP of a web interface to browse the Version Control System
 130 repository.
 131 .TP
 132 .BI Vcs\-Arch: " url"
 133 .TQ
 134 .BI Vcs\-Bzr: " url"
 135 .TQ
 136 .BI Vcs\-Cvs: " url"
 137 .TQ
 138 .BI Vcs\-Darcs: " url"
 139 .TQ
 140 .BI Vcs\-Git: " url"
 141 .TQ
 142 .BI Vcs\-Hg: " url"
 143 .TQ
 144 .BI Vcs\-Mtn: " url"
 145 .TQ
 146 .BI Vcs\-Svn: " url"
 147 These fields declare the \fIurl\fP of the Version Control System repository
 148 used to maintain this package.
 149 See \fBdeb\-src\-control\fP(5) for more details.
 150 .TP
 151 .BI Testsuite: " name-list"
 152 This field declares that the source package contains the specified test suites.
 153 The value is a comma-separated list of test suites.
 154 If the \fBautopkgtest\fP value is present, a \fIdebian/tests/control\fP is
 155 expected to be present, if the file is present but not the value, then
 156 \fBdpkg\-source\fP will automatically add it, preserving previous values.
 157 .TP
 158 .BI Testsuite\-Triggers: " package-list"
 159 This field declares the comma-separated union of all test dependencies
 160 (\fBDepends\fP fields in \fIdebian/tests/control\fP file), with all
 161 restrictions removed, and OR dependencies flattened (that is, converted to
 162 separate AND relationships), except for binaries generated by this source
 163 package and its meta-dependency equivalent \fB@\fP.
 164
 165 Rationale: this field is needed because otherwise to be able to get the
 166 test dependencies, each source package would need to be unpacked.
 167 .TP
 168 .BI Build\-Depends: " package-list"
 169 .TQ
 170 .BI Build\-Depends\-Arch: " package-list"
 171 .TQ
 172 .BI Build\-Depends\-Indep: " package-list"
 173 .TQ
 174 .BI Build\-Conflicts: " package-list"
 175 .TQ
 176 .BI Build\-Conflicts\-Arch: " package-list"
 177 .TQ
 178 .BI Build\-Conflicts\-Indep: " package-list"
 179 These fields declare relationships between the source package and packages
 180 used to build it.
 181 They are discussed in the \fBdeb\-src\-control\fP(5) manpage.
 182 .TP
 183 .BI Package\-List:
 184 .TQ
 185 .RI " " package " " package-type " " section " " priority " " key-value-list
 186 This multiline field contains a list of binary packages generated by this
 187 source package.
 188
 189 The \fIpackage\fP is the binary package name.
 190
 191 The \fIpackage-type\fP is the binary package type, usually \fBdeb\fP, another
 192 common value is \fBudeb\fP.
 193
 194 The \fIsection\fP and \fIpriority\fP match the binary package fields of the
 195 same name.
 196
 197 The \fIkey-value-list\fP is a space separated \fIkey\fP\fB=\fP\fIvalue\fP list,
 198 and the currently known optional keys are:
 199
 200 .RS
 201 .TP
 202 .B arch
 203 The architecture restriction from the binary package \fBArchitecture\fP
 204 field, with spaces converted to ‘,’.
 205 .TP
 206 .B profile
 207 The normalized build-profile restriction formula from the binary package
 208 \fBBuild\-Profile\fP field, with ORs converted to ‘+’ and ANDs to
 209 ‘,’.
 210 .TP
 211 .B essential
 212 If the binary package is essential, this key will contain the value of the
 213 \fBEssential\fP field, that is a \fByes\fP value.
 214 .RE
 215 .TP
 216 .BR Files: " (required)"
 217 .TQ
 218 .BR Checksums\-Sha1: " (required)"
 219 .TQ
 220 .BR Checksums\-Sha256: " (required)"
 221 .TQ
 222 .RI " " checksum " " size " " filename
 223 These multiline fields contain a list of files with a checksum and size
 224 for each one.
 225 These fields have the same syntax and differ only in the checksum algorithm
 226 used: MD5 for \fBFiles\fP, SHA-1 for \fBChecksums\-Sha1\fP and SHA-256 for
 227 \fBChecksums\-Sha256\fP.
 228
 229 The first line of the field value (the part on the same line as the field
 230 name followed by a colon) is always empty.
 231 The content of the field is expressed as continuation lines, one line per file.
 232 Each line consists of the checksum, a space, the file size, a space, and the
 233 file name.
 234
 235 These fields list all files that make up the source package.
 236 The list of files in these fields must match the list of files in the
 237 other related fields.
 238 .
 239 .\" .SH EXAMPLE
 240 .\" .RS
 241 .\" .nf
 242 .\" .fi
 243 .\" .RE
 244 .
 245 .SH BUGS
 246 The \fBFormat\fP field conflates the format for the \fB.dsc\fP file itself
 247 and the format of the extracted source package.
 248 .SH SEE ALSO
 249 .BR deb\-src\-control (5),
 250 .BR deb\-version (7),
 251 .BR dpkg\-source (1).