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