Commit | Line | Data |
---|---|---|
1479465f GJ |
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). |