Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | .\" dpkg manual page - dpkg-source(1) |
2 | .\" | |
3 | .\" Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk> | |
4 | .\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org> | |
5 | .\" Copyright © 2006-2007 Frank Lichtenheld <djpig@debian.org> | |
6 | .\" Copyright © 2006-2015 Guillem Jover <guillem@debian.org> | |
7 | .\" Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org> | |
8 | .\" Copyright © 2010 Joey Hess <joeyh@debian.org> | |
9 | .\" | |
10 | .\" This is free software; you can redistribute it and/or modify | |
11 | .\" it under the terms of the GNU General Public License as published by | |
12 | .\" the Free Software Foundation; either version 2 of the License, or | |
13 | .\" (at your option) any later version. | |
14 | .\" | |
15 | .\" This is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public License | |
21 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
22 | . | |
23 | .TH dpkg\-source 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite" | |
24 | .nh | |
25 | .SH NAME | |
26 | dpkg\-source \- Debian source package (.dsc) manipulation tool | |
27 | . | |
28 | .SH SYNOPSIS | |
29 | .B dpkg\-source | |
30 | .RI [ option "...] " command | |
31 | . | |
32 | .SH DESCRIPTION | |
33 | .B dpkg\-source | |
34 | packs and unpacks Debian source archives. | |
35 | ||
36 | None of these commands allow multiple options to be combined into one, | |
37 | and they do not allow the value for an option to be specified in a | |
38 | separate argument. | |
39 | . | |
40 | .SH COMMANDS | |
41 | .TP | |
42 | .BR \-x ", " \-\-extract " \fIfilename\fP.dsc [\fIoutput-directory\fP]" | |
43 | Extract a source package (\fB\-\-extract\fP since dpkg 1.17.14). | |
44 | One non-option argument must be supplied, | |
45 | the name of the Debian source control file | |
46 | .RB ( .dsc ). | |
47 | An optional second non-option argument may be supplied to specify the | |
48 | directory to extract the source package to, this must not exist. If | |
49 | no output directory is specified, the source package is extracted into | |
50 | a directory named \fIsource\fR-\fIversion\fR under the current working | |
51 | directory. | |
52 | ||
53 | .B dpkg\-source | |
54 | will read the names of the other file(s) making up the source package | |
55 | from the control file; they are assumed to be in the same directory as | |
56 | the | |
57 | .BR .dsc . | |
58 | ||
59 | The files in the extracted package will have their permissions and | |
60 | ownerships set to those which would have been expected if the files | |
61 | and directories had simply been created - directories and executable | |
62 | files will be 0777 and plain files will be 0666, both modified by the | |
63 | extractors' umask; if the parent directory is setgid then the | |
64 | extracted directories will be too, and all the files and directories | |
65 | will inherit its group ownership. | |
66 | ||
67 | If the source package uses a non-standard format (currently this means all | |
68 | formats except “1.0”), its name will be stored in | |
69 | \fBdebian/source/format\fP so that the following builds of the source | |
70 | package use the same format by default. | |
71 | ||
72 | .TP | |
73 | .BR \-b ", " \-\-build " \fIdirectory\fP [\fIformat-specific-parameters\fP]" | |
74 | Build a source package (\fB\-\-build\fP since dpkg 1.17.14). | |
75 | The first non-option argument is taken as the | |
76 | name of the directory containing the debianized source tree (i.e. with a | |
77 | debian sub-directory and maybe changes to the original files). | |
78 | Depending on the source package format used to build the package, | |
79 | additional parameters might be accepted. | |
80 | ||
81 | \fBdpkg\-source\fP will build the source package with the first format | |
82 | found in this ordered list: | |
83 | the format indicated with the \fI\-\-format\fP command line option, | |
84 | the format indicated in \fBdebian/source/format\fP, | |
85 | “1.0”. | |
86 | The fallback to “1.0” is deprecated and will be removed at some | |
87 | point in the future, you should always document the desired source format | |
88 | in \fBdebian/source/format\fP. See section \fBSOURCE PACKAGE FORMATS\fP | |
89 | for an extensive description of the various source package formats. | |
90 | ||
91 | .TP | |
92 | .RI "\fB\-\-print\-format\fP " directory | |
93 | Print the source format that would be used to build the source package if | |
94 | \fBdpkg\-source \-\-build \fIdirectory\fR was called (in the same conditions | |
95 | and with the same parameters; since dpkg 1.15.5). | |
96 | ||
97 | .TP | |
98 | .RI "\fB\-\-before\-build\fP " directory | |
99 | Run the corresponding hook of the source package format (since dpkg 1.15.8). | |
100 | This hook is | |
101 | called before any build of the package (\fBdpkg\-buildpackage\fP calls it | |
102 | very early even before \fBdebian/rules clean\fP). This command is | |
103 | idempotent and can be called multiple times. Not all source formats | |
104 | implement something in this hook, and those that do usually prepare the | |
105 | source tree for the build for example by ensuring that the Debian patches | |
106 | are applied. | |
107 | ||
108 | .TP | |
109 | .RI "\fB\-\-after\-build\fP " directory | |
110 | Run the corresponding hook of the source package format (since dpkg 1.15.8). | |
111 | This hook is | |
112 | called after any build of the package (\fBdpkg\-buildpackage\fP calls it | |
113 | last). This command is idempotent and can be called multiple times. Not | |
114 | all source formats implement something in this hook, and those that do | |
115 | usually use it to undo what \fB\-\-before\-build\fP has done. | |
116 | ||
117 | .TP | |
118 | .RI "\fB\-\-commit\fP [" directory "] ..." | |
119 | Record changes in the source tree unpacked in \fIdirectory\fP | |
120 | (since dpkg 1.16.1). | |
121 | This command can take supplementary parameters depending on the source format. | |
122 | It will error out for formats where this operation doesn't mean anything. | |
123 | ||
124 | .TP | |
125 | .BR \-? ", " \-\-help | |
126 | Show the usage message and exit. | |
127 | The format specific build and extract options can be shown by using the | |
128 | \fB\-\-format\fP option. | |
129 | .TP | |
130 | .BR \-\-version | |
131 | Show the version and exit. | |
132 | . | |
133 | .SH OPTIONS | |
134 | .SS Generic build options | |
135 | .TP | |
136 | .BI \-c control-file | |
137 | Specifies the main source control file to read information from. The | |
138 | default is | |
139 | .BR debian/control . | |
140 | If given with relative pathname this is interpreted starting at | |
141 | the source tree's top level directory. | |
142 | .TP | |
143 | .BI \-l changelog-file | |
144 | Specifies the changelog file to read information from. The | |
145 | default is | |
146 | .BR debian/changelog . | |
147 | If given with relative pathname this is interpreted starting at | |
148 | the source tree's top level directory. | |
149 | .TP | |
150 | .BI \-F changelog-format | |
151 | Specifies the format of the changelog. See \fBdpkg\-parsechangelog\fP(1) | |
152 | for information about alternative formats. | |
153 | .TP | |
154 | .BI \-\-format= value | |
155 | Use the given format for building the source package (since dpkg 1.14.17). | |
156 | It does override any format given in \fBdebian/source/format\fP. | |
157 | .TP | |
158 | .BI \-V name = value | |
159 | Set an output substitution variable. | |
160 | See \fBdeb\-substvars\fP(5) for a discussion of output substitution. | |
161 | .TP | |
162 | .BI \-T substvars-file | |
163 | Read substitution variables in | |
164 | .IR substvars-file ; | |
165 | the default is to not read any file. This option can be used multiple | |
166 | times to read substitution variables from multiple files (since dpkg 1.15.6). | |
167 | .TP | |
168 | .BI \-D field = value | |
169 | Override or add an output control file field. | |
170 | .TP | |
171 | .BI \-U field | |
172 | Remove an output control file field. | |
173 | .TP | |
174 | .BR \-Z "\fIcompression\fP, " \-\-compression =\fIcompression\fP | |
175 | Specify the compression to use for created tarballs and diff files | |
176 | (\fB\-\-compression\fP since dpkg 1.15.5). | |
177 | Note that this option will not cause existing tarballs to be recompressed, | |
178 | it only affects new files. Supported values are: | |
179 | .IR gzip ", " bzip2 ", " lzma " and " xz . | |
180 | The default is \fIxz\fP for formats 2.0 and newer, and \fIgzip\fP for | |
181 | format 1.0. \fIxz\fP is only supported since dpkg 1.15.5. | |
182 | .TP | |
183 | .BR \-z "\fIlevel\fP, " \-\-compression\-level =\fIlevel\fP | |
184 | Compression level to use (\fB\-\-compression\-level\fP since dpkg 1.15.5). | |
185 | As with \fB\-Z\fP it only affects newly created | |
186 | files. Supported values are: | |
187 | .IR 1 " to " 9 ", " best ", and " fast . | |
188 | The default is \fI9\fP for gzip and bzip2, \fI6\fP for xz and lzma. | |
189 | .TP | |
190 | .BR \-i "[\fIregex\fP], " \-\-diff\-ignore [=\fIregex\fP] | |
191 | You may specify a perl regular expression to match files you want | |
192 | filtered out of the list of files for the diff (\fB\-\-diff\-ignore\fP | |
193 | since dpkg 1.15.6). | |
194 | (This list is | |
195 | generated by a find command.) (If the source package is being built as a | |
196 | version 3 source package using a VCS, this can be used to ignore | |
197 | uncommitted changes on specific files. Using \-i.* will ignore all of them.) | |
198 | ||
199 | The \fB\-i\fP option by itself enables this setting with a default regex | |
200 | (preserving any modification to the default regex done by a previous use | |
201 | of \fB\-\-extend\-diff\-ignore\fP) that will filter out control files and | |
202 | directories of the most common revision control systems, backup and swap | |
203 | files and Libtool build output directories. There can only be one active | |
204 | regex, of multiple \fB\-i\fP options only the last one will take effect. | |
205 | ||
206 | This is very helpful in cutting out extraneous files that get included | |
207 | in the diff, e.g. if you maintain your source in a revision control | |
208 | system and want to use a checkout to build a source package without | |
209 | including the additional files and directories that it will usually | |
210 | contain (e.g. CVS/, .cvsignore, .svn/). The default regex is already | |
211 | very exhaustive, but if you need to replace it, please note that by | |
212 | default it can match any part of a path, so if you want to match the | |
213 | begin of a filename or only full filenames, you will need to provide | |
214 | the necessary anchors (e.g. ‘(^|/)’, ‘($|/)’) yourself. | |
215 | .TP | |
216 | .BR \-\-extend\-diff\-ignore =\fIregex\fP | |
217 | The perl regular expression specified will extend the default value used by | |
218 | \fB\-\-diff\-ignore\fP and its current value, if set (since dpkg 1.15.6). | |
219 | It does this by concatenating “\fB|\fP\fIregex\fP” to the existing value. | |
220 | This option is convenient to use in \fBdebian/source/options\fP to exclude | |
221 | some auto-generated files from the automatic patch generation. | |
222 | .TP | |
223 | .BR \-I "[\fIfile-pattern\fP], " \-\-tar\-ignore [=\fIfile-pattern\fP] | |
224 | If this option is specified, the pattern will be passed to | |
225 | .BR tar (1)'s | |
226 | .B \-\-exclude | |
227 | option when it is called to generate a .orig.tar or .tar file | |
228 | (\fB\-\-tar\-ignore\fP since dpkg 1.15.6). | |
229 | For | |
230 | example, \fB\-I\fPCVS will make tar skip over CVS directories when generating | |
231 | a .tar.gz file. The option may be repeated multiple times to list multiple | |
232 | patterns to exclude. | |
233 | ||
234 | \fB\-I\fP by itself adds default \fB\-\-exclude\fP options that will | |
235 | filter out control files and directories of the most common revision | |
236 | control systems, backup and swap files and Libtool build output | |
237 | directories. | |
238 | .PP | |
239 | .B Note: | |
240 | While they have similar purposes, \fB\-i\fP and \fB\-I\fP have very | |
241 | different syntax and semantics. \fB\-i\fP can only be specified once and | |
242 | takes a perl compatible regular expression which is matched against | |
243 | the full relative path of each file. \fB\-I\fP can specified | |
244 | multiple times and takes a filename pattern with shell wildcards. | |
245 | The pattern is applied to the full relative path but also | |
246 | to each part of the path individually. The exact semantic of tar's | |
247 | \fB\-\-exclude\fP option is somewhat complicated, see | |
248 | https://www.gnu.org/software/tar/manual/tar.html#wildcards for a full | |
249 | documentation. | |
250 | ||
251 | The default regex and patterns for both options can be seen | |
252 | in the output of the \fB\-\-help\fP command. | |
253 | .SS Generic extract options | |
254 | .TP | |
255 | .BI \-\-no\-copy | |
256 | Do not copy original tarballs near the extracted source package | |
257 | (since dpkg 1.14.17). | |
258 | .TP | |
259 | .BI \-\-no\-check | |
260 | Do not check signatures and checksums before unpacking (since dpkg 1.14.17). | |
261 | .TP | |
262 | .B \-\-no\-overwrite\-dir | |
263 | Do not overwrite the extraction directory if it already exists | |
264 | (since dpkg 1.18.8). | |
265 | .TP | |
266 | .BI \-\-require\-valid\-signature | |
267 | Refuse to unpack the source package if it doesn't contain an OpenPGP | |
268 | signature that can be verified (since dpkg 1.15.0) either with the user's | |
269 | \fItrustedkeys.gpg\fP keyring, one of the vendor-specific keyrings, or one | |
270 | of the official Debian keyrings | |
271 | (\fI/usr/share/keyrings/debian\-keyring.gpg\fP | |
272 | and \fI/usr/share/keyrings/debian\-maintainers.gpg\fP). | |
273 | .TP | |
274 | .BI \-\-require\-strong\-checksums | |
275 | Refuse to unpack the source package if it does not contain any strong | |
276 | checksums (since dpkg 1.18.7). | |
277 | Currently the only known checksum considered strong is \fBSHA-256\fP. | |
278 | .TP | |
279 | .B \-\-ignore\-bad\-version | |
280 | Turns the bad source package version check into a non-fatal warning | |
281 | (since dpkg 1.17.7). | |
282 | This option should only be necessary when extracting ancient source | |
283 | packages with broken versions, just for backwards compatibility. | |
284 | ||
285 | .SH SOURCE PACKAGE FORMATS | |
286 | If you don't know what source format to use, you should probably pick | |
287 | either “3.0 (quilt)” or “3.0 (native)”. | |
288 | See https://wiki.debian.org/Projects/DebSrc3.0 for information on the | |
289 | deployment of those formats within Debian. | |
290 | ||
291 | .SS Format: 1.0 | |
292 | A source package in this format consists either of a \fB.orig.tar.gz\fP | |
293 | associated to a \fB.diff.gz\fP or a single \fB.tar.gz\fP (in that case | |
294 | the package is said to be \fInative\fP). | |
295 | Optionally the original tarball might be accompanied by a detached | |
296 | upstream signature \fB.orig.tar.gz.asc\fP, extraction | |
297 | supported since dpkg 1.18.5. | |
298 | ||
299 | .B Extracting | |
300 | ||
301 | Extracting a native package is a simple extraction of the single | |
302 | tarball in the target directory. Extracting a non-native package | |
303 | is done by first unpacking the \fB.orig.tar.gz\fP and then applying | |
304 | the patch contained in the \fB.diff.gz\fP file. The timestamp of | |
305 | all patched files is reset to the extraction time of the source | |
306 | package (this avoids timestamp skews leading to problems when | |
307 | autogenerated files are patched). The diff can create new files (the whole | |
308 | debian directory is created that way) but can't remove files (empty files | |
309 | will be left over). | |
310 | ||
311 | .B Building | |
312 | ||
313 | Building a native package is just creating a single tarball with | |
314 | the source directory. Building a non-native package involves | |
315 | extracting the original tarball in a separate “.orig” directory and | |
316 | regenerating the \fB.diff.gz\fP by comparing the source package | |
317 | \fIdirectory\fP with the .orig directory. | |
318 | ||
319 | .B Build options (with \-\-build): | |
320 | ||
321 | If a second non-option argument is supplied it should be the name of the | |
322 | original source directory or tarfile or the empty string if the package is | |
323 | a Debian-specific one and so has no debianization diffs. If no second | |
324 | argument is supplied then | |
325 | .B dpkg\-source | |
326 | will look for the original source tarfile | |
327 | .IB package _ upstream-version .orig.tar.gz | |
328 | or the original source directory | |
329 | .IB directory .orig | |
330 | depending on the \fB\-sX\fP arguments. | |
331 | ||
332 | .BR \-sa ", " \-sp ", " \-sk ", " \-su " and " \-sr | |
333 | will not overwrite existing tarfiles or directories. If this is | |
334 | desired then | |
335 | .BR \-sA ", " \-sP ", " \-sK ", " \-sU " and " \-sR | |
336 | should be used instead. | |
337 | .PP | |
338 | .TP | |
339 | .BR \-sk | |
340 | Specifies to expect the original source as a tarfile, by default | |
341 | .IB package _ upstream-version .orig.tar. extension \fR. | |
342 | It will leave this original source in place as a tarfile, or copy it | |
343 | to the current directory if it isn't already there. The | |
344 | tarball will be unpacked into | |
345 | .IB directory .orig | |
346 | for the generation of the diff. | |
347 | .TP | |
348 | .B \-sp | |
349 | Like | |
350 | .B \-sk | |
351 | but will remove the directory again afterwards. | |
352 | .TP | |
353 | .B \-su | |
354 | Specifies that the original source is expected as a directory, by | |
355 | default | |
356 | .IB package - upstream-version .orig | |
357 | and | |
358 | .B dpkg\-source | |
359 | will create a new original source archive from it. | |
360 | .TP | |
361 | .B \-sr | |
362 | Like | |
363 | .B \-su | |
364 | but will remove that directory after it has been used. | |
365 | .TP | |
366 | .B \-ss | |
367 | Specifies that the original source is available both as a directory | |
368 | and as a tarfile. \fBdpkg\-source\fP will use the directory to create | |
369 | the diff, but the tarfile to create the | |
370 | .BR .dsc . | |
371 | This option must be used with care - if the directory and tarfile do | |
372 | not match a bad source archive will be generated. | |
373 | .TP | |
374 | .B \-sn | |
375 | Specifies to not look for any original source, and to not generate a diff. | |
376 | The second argument, if supplied, must be the empty string. This is | |
377 | used for Debian-specific packages which do not have a separate | |
378 | upstream source and therefore have no debianization diffs. | |
379 | .TP | |
380 | .BR \-sa " or " \-sA | |
381 | Specifies to look for the original source archive as a tarfile or as a | |
382 | directory - the second argument, if any, may be either, or the empty | |
383 | string (this is equivalent to using | |
384 | .BR \-sn ). | |
385 | If a tarfile is found it will unpack it to create the diff and remove | |
386 | it afterwards (this is equivalent to | |
387 | .BR \-sp ); | |
388 | if a directory is found it will pack it to create the original source | |
389 | and remove it afterwards (this is equivalent to | |
390 | .BR \-sr ); | |
391 | if neither is found it will assume that the package has no | |
392 | debianization diffs, only a straightforward source archive (this is | |
393 | equivalent to | |
394 | .BR \-sn ). | |
395 | If both are found then \fBdpkg\-source\fP will ignore the directory, | |
396 | overwriting it, if | |
397 | .B \-sA | |
398 | was specified (this is equivalent to | |
399 | .BR \-sP ) | |
400 | or raise an error if | |
401 | .B \-sa | |
402 | was specified. | |
403 | .B \-sA | |
404 | is the default. | |
405 | .TP | |
406 | .B \-\-abort\-on\-upstream\-changes | |
407 | The process fails if the generated diff contains changes to files | |
408 | outside of the debian sub-directory (since dpkg 1.15.8). | |
409 | This option is not allowed in | |
410 | \fBdebian/source/options\fP but can be used in | |
411 | \fBdebian/source/local\-options\fP. | |
412 | .PP | |
413 | ||
414 | .B Extract options (with \-\-extract): | |
415 | ||
416 | In all cases any existing original source tree will be removed. | |
417 | .TP | |
418 | .B \-sp | |
419 | Used when extracting then the original source (if any) will be left | |
420 | as a tarfile. If it is not already located in the current directory | |
421 | or if an existing but different file is there it will be copied there. | |
422 | (\fBThis is the default\fP). | |
423 | .TP | |
424 | .B \-su | |
425 | Unpacks the original source tree. | |
426 | .TP | |
427 | .B \-sn | |
428 | Ensures that the original source is neither copied to the current | |
429 | directory nor unpacked. Any original source tree that was in the | |
430 | current directory is still removed. | |
431 | .PP | |
432 | All the | |
433 | .BI \-s X | |
434 | options are mutually exclusive. If you specify more than one only the | |
435 | last one will be used. | |
436 | .TP | |
437 | .B \-\-skip\-debianization | |
438 | Skips application of the debian diff on top of the upstream sources | |
439 | (since dpkg 1.15.1). | |
440 | . | |
441 | .SS Format: 2.0 | |
442 | Extraction supported since dpkg 1.13.9, building supported since dpkg 1.14.8. | |
443 | Also known as wig&pen. This format is not recommended for wide-spread | |
444 | usage, the format “3.0 (quilt)” replaces it. | |
445 | Wig&pen was the first specification of a new-generation source package format. | |
446 | ||
447 | The behaviour of this format is the same as the “3.0 (quilt)” format | |
448 | except that it doesn't use an explicit list of patches. All files in | |
449 | \fBdebian/patches/\fP matching the perl regular expression \fB[\\w\-]+\fP | |
450 | must be valid patches: they are applied at extraction time. | |
451 | ||
452 | When building a new source package, any change to the upstream source | |
453 | is stored in a patch named \fBzz_debian\-diff\-auto\fP. | |
454 | . | |
455 | .SS Format: 3.0 (native) | |
456 | Supported since dpkg 1.14.17. | |
457 | This format is an extension of the native package format as defined | |
458 | in the 1.0 format. It supports all compression methods and | |
459 | will ignore by default any VCS specific files and directories | |
460 | as well as many temporary files (see default value associated to | |
461 | \fB\-I\fP option in the \fB\-\-help\fP output). | |
462 | . | |
463 | .SS Format: 3.0 (quilt) | |
464 | Supported since dpkg 1.14.17. | |
465 | A source package in this format contains at least | |
466 | an original tarball (\fB.orig.tar.\fP\fIext\fP where \fIext\fP can be | |
467 | \fBgz\fP, \fBbz2\fP, \fBlzma\fP and \fBxz\fP) and a debian tarball | |
468 | (\fB.debian.tar.\fP\fIext\fP). It can also contain additional original | |
469 | tarballs (\fB.orig\-\fP\fIcomponent\fP\fB.tar.\fP\fIext\fP). | |
470 | \fIcomponent\fP can only contain alphanumeric characters and hyphens | |
471 | (‘\-’). | |
472 | Optionally each original tarball can be accompanied by a detached | |
473 | upstream signature (\fB.orig.tar.\fP\fIext\fP\fB.asc\fP and | |
474 | \fB.orig\-\fP\fIcomponent\fP\fB.tar.\fP\fIext\fP\fB.asc\fP), extraction | |
475 | supported since dpkg 1.17.20, building supported since dpkg 1.18.5. | |
476 | ||
477 | .PP | |
478 | .B Extracting | |
479 | .PP | |
480 | The main original tarball is extracted first, then all additional original | |
481 | tarballs are extracted in subdirectories named after the \fIcomponent\fP | |
482 | part of their filename (any pre-existing directory is replaced). The | |
483 | debian tarball is extracted on top of the source directory after prior | |
484 | removal of any pre-existing \fBdebian\fP directory. Note that the | |
485 | debian tarball must contain a \fBdebian\fP sub-directory but it | |
486 | can also contain binary files outside of that directory (see | |
487 | \fB\-\-include\-binaries\fP option). | |
488 | .PP | |
489 | All patches listed in \fBdebian/patches/debian.series\fP or | |
490 | \fBdebian/patches/series\fP are then applied. | |
491 | If the former file is used and the latter one doesn't exist (or is a | |
492 | symlink), then the latter is replaced with a symlink to the former. This | |
493 | is meant to simplify usage of \fBquilt\fP to manage the set of patches. Note | |
494 | however that while \fBdpkg\-source\fP parses correctly series files with | |
495 | explicit options used for patch application (stored on each line | |
496 | after the patch filename and one or more spaces), it does ignore those | |
497 | options and always expect patches that can be applied with the \fB\-p1\fP | |
498 | option of \fBpatch\fP. It will thus emit a warning when it encounters | |
499 | such options, and the build is likely to fail. | |
500 | .PP | |
501 | The timestamp of all patched files is reset to the extraction time of | |
502 | the source package (this avoids timestamp skews leading to problems | |
503 | when autogenerated files are patched). | |
504 | .PP | |
505 | Contrary to \fBquilt\fP's default behaviour, patches are expected to apply | |
506 | without any fuzz. When that is not the case, you should refresh such | |
507 | patches with \fBquilt\fP, or \fBdpkg\-source\fP will error out while | |
508 | trying to apply them. | |
509 | .PP | |
510 | Similarly to \fBquilt\fP's default behaviour, the patches can remove | |
511 | files too. | |
512 | .PP | |
513 | The file \fB.pc/applied\-patches\fP is created if some | |
514 | patches have been applied during the extraction. | |
515 | .PP | |
516 | .B Building | |
517 | .PP | |
518 | All original tarballs found in the current directory are extracted in a | |
519 | temporary directory by following the same logic as for the unpack, the | |
520 | debian directory is copied over in the temporary directory, and all | |
521 | patches except the automatic patch (\fBdebian\-changes\-\fP\fIversion\fP | |
522 | or \fBdebian\-changes\fP, depending on \fB\-\-single\-debian\-patch\fP) are | |
523 | applied. The temporary directory is compared to the source package | |
524 | directory. When the diff is non-empty, the build fails unless | |
525 | \fB\-\-single\-debian\-patch\fP or \fB\-\-auto\-commit\fP | |
526 | has been used, in which case the diff is stored in the automatic patch. | |
527 | If the automatic patch is created/deleted, it's added/removed from the | |
528 | series file and from the \fBquilt\fP metadata. | |
529 | ||
530 | Any change | |
531 | on a binary file is not representable in a diff and will thus lead to a | |
532 | failure unless the maintainer deliberately decided to include that | |
533 | modified binary file in the debian tarball (by listing it in | |
534 | \fBdebian/source/include\-binaries\fP). The build will also fail if it | |
535 | finds binary files in the debian sub-directory unless they have been | |
536 | whitelisted through \fBdebian/source/include\-binaries\fP. | |
537 | ||
538 | The updated debian directory and the list of modified binaries is then | |
539 | used to generate the debian tarball. | |
540 | ||
541 | The automatically generated diff doesn't include changes on VCS specific | |
542 | files as well as many temporary files (see default value associated to | |
543 | \fB\-i\fP option in the \fB\-\-help\fP output). In particular, the | |
544 | \fB.pc\fP directory used by \fBquilt\fP is ignored during generation of the | |
545 | automatic patch. | |
546 | ||
547 | Note: \fBdpkg\-source\fP \fB\-\-before\-build\fP (and \fB\-\-build\fP) will | |
548 | ensure that all patches listed in the series file are applied so that a | |
549 | package build always has all patches applied. It does this by finding | |
550 | unapplied patches (they are listed in the \fBseries\fP file but not in | |
551 | \fB.pc/applied\-patches\fP), and if the first patch in that set can be | |
552 | applied without errors, it will apply them all. The option | |
553 | \fB\-\-no\-preparation\fP can be used to disable this | |
554 | behavior. | |
555 | ||
556 | .PP | |
557 | .B Recording changes | |
558 | .TP | |
559 | .RI "\fB\-\-commit\fP [" directory "] [" patch-name "] [" patch-file ] | |
560 | Generates a patch corresponding to the local changes that are not managed | |
561 | by the \fBquilt\fP patch system and integrates it in the patch system under | |
562 | the name \fIpatch-name\fP. If the name is missing, it will be asked | |
563 | interactively. If \fIpatch-file\fP is given, it is used as the patch | |
564 | corresponding to the local changes to integrate. Once integrated, an | |
565 | editor is launched so that you can edit the meta-information in the patch | |
566 | header. | |
567 | ||
568 | Passing \fIpatch-file\fP is mainly useful after a build failure that | |
569 | pre-generated this file, and on this ground the given file is removed | |
570 | after integration. Note also that the changes contained in the patch file | |
571 | must already be applied on the tree and that the files modified by the | |
572 | patch must not have supplementary unrecorded changes. | |
573 | ||
574 | If the patch generation detects modified binary files, they will be | |
575 | automatically added to \fBdebian/source/include\-binaries\fP so that | |
576 | they end up in the debian tarball (exactly like \fBdpkg-source | |
577 | \-\-include\-binaries \-\-build\fP would do). | |
578 | .PP | |
579 | .B Build options | |
580 | .TP | |
581 | .BI \-\-allow\-version\-of\-quilt\-db= version | |
582 | Allow \fBdpkg\-source\fP to build the source package if the version of | |
583 | the \fBquilt\fP metadata is the one specified, even if \fBdpkg\-source\fP | |
584 | doesn't know about it (since dpkg 1.15.5.4). | |
585 | Effectively this says that the given version of the | |
586 | \fBquilt\fP metadata is compatible with the version 2 that \fBdpkg\-source\fP | |
587 | currently supports. The version of the \fBquilt\fP metadata is stored in | |
588 | \fB.pc/.version\fP. | |
589 | .TP | |
590 | .B \-\-include\-removal | |
591 | Do not ignore removed files and include them in the automatically | |
592 | generated patch. | |
593 | .TP | |
594 | .B \-\-include\-timestamp | |
595 | Include timestamp in the automatically generated patch. | |
596 | .TP | |
597 | .B \-\-include\-binaries | |
598 | Add all modified binaries in the debian tarball. Also add them to | |
599 | \fBdebian/source/include\-binaries\fP: they will be added by default | |
600 | in subsequent builds and this option is thus no more needed. | |
601 | .TP | |
602 | .B \-\-no\-preparation | |
603 | Do not try to prepare the build tree by applying patches which are | |
604 | apparently unapplied (since dpkg 1.14.18). | |
605 | .TP | |
606 | .B \-\-single\-debian\-patch | |
607 | Use \fBdebian/patches/debian\-changes\fP instead of | |
608 | \fBdebian/patches/debian\-changes\-\fP\fIversion\fP for the name of the | |
609 | automatic patch generated during build (since dpkg 1.15.5.4). | |
610 | This option is particularly | |
611 | useful when the package is maintained in a VCS and a patch set can't reliably | |
612 | be generated. Instead the current diff with upstream should be stored in a | |
613 | single patch. The option would be put in \fBdebian/source/local\-options\fP | |
614 | and would be accompanied by a \fBdebian/source/local\-patch\-header\fP file | |
615 | explaining how the Debian changes can be best reviewed, for example in the | |
616 | VCS that is used. | |
617 | .TP | |
618 | .B \-\-create\-empty\-orig | |
619 | Automatically create the main original tarball as empty if it's missing | |
620 | and if there are supplementary original tarballs (since dpkg 1.15.6). | |
621 | This option is meant to | |
622 | be used when the source package is just a bundle of multiple upstream | |
623 | software and where there's no “main” software. | |
624 | .TP | |
625 | .B \-\-no\-unapply\-patches, \-\-unapply\-patches | |
626 | By default, \fBdpkg\-source\fP will automatically unapply the patches in the | |
627 | \fB\-\-after\-build\fP hook if it did apply them during | |
628 | \fB\-\-before\-build\fP (\fB\-\-unapply\-patches\fP since dpkg 1.15.8, | |
629 | \fB\-\-no\-unapply\-patches\fP since dpkg 1.16.5). | |
630 | Those options allow you to forcefully disable | |
631 | or enable the patch unapplication process. Those options are only allowed | |
632 | in \fBdebian/source/local\-options\fP so that all generated source | |
633 | packages have the same behavior by default. | |
634 | .TP | |
635 | .B \-\-abort\-on\-upstream\-changes | |
636 | The process fails if an automatic patch has been generated | |
637 | (since dpkg 1.15.8). | |
638 | This option | |
639 | can be used to ensure that all changes were properly recorded in separate | |
640 | \fBquilt\fP patches prior to the source package build. This option is not | |
641 | allowed in \fBdebian/source/options\fP but can be used in | |
642 | \fBdebian/source/local\-options\fP. | |
643 | .TP | |
644 | .B \-\-auto\-commit | |
645 | The process doesn't fail if an automatic patch has been generated, instead | |
646 | it's immediately recorded in the \fBquilt\fP series. | |
647 | ||
648 | .PP | |
649 | .B Extract options | |
650 | .TP | |
651 | .B \-\-skip\-debianization | |
652 | Skips extraction of the debian tarball on top of the upstream sources | |
653 | (since dpkg 1.15.1). | |
654 | .TP | |
655 | .B \-\-skip\-patches | |
656 | Do not apply patches at the end of the extraction (since dpkg 1.14.18). | |
657 | . | |
658 | .SS Format: 3.0 (custom) | |
659 | Supported since dpkg 1.14.17. | |
660 | This format is special. | |
661 | It doesn't represent a real source package | |
662 | format but can be used to create source packages with arbitrary files. | |
663 | .PP | |
664 | .B Build options | |
665 | .PP | |
666 | All non-option arguments are taken as files to integrate in the | |
667 | generated source package. They must exist and are preferably | |
668 | in the current directory. At least one file must be given. | |
669 | .TP | |
670 | .BI \-\-target\-format= value | |
671 | \fBRequired\fP. Defines the real format of the generated source package. | |
672 | The generated .dsc file will contain this value in its \fBFormat\fP field | |
673 | and not “3.0 (custom)”. | |
674 | . | |
675 | .SS Format: 3.0 (git) | |
676 | Supported since dpkg 1.14.17. | |
677 | This format is experimental. | |
678 | .PP | |
679 | A source package in this format consists of a | |
680 | single bundle of a git repository \fB.git\fP to hold the source of a package. | |
681 | There may also be a \fB.gitshallow\fP file listing revisions for a shallow | |
682 | git clone. | |
683 | .PP | |
684 | .B Extracting | |
685 | .PP | |
686 | The bundle is cloned as a git repository to the target directory. | |
687 | If there is a gitshallow file, it is installed as \fI.git/shallow\fP inside | |
688 | the cloned git repository. | |
689 | .PP | |
690 | Note that by default the new repository will have the same branch checked | |
691 | out that was checked out in the original source. | |
692 | (Typically “master”, but it could be anything.) | |
693 | Any other branches will be available under \fIremotes/origin/\fP. | |
694 | .PP | |
695 | .B Building | |
696 | .PP | |
697 | Before going any further, some checks are done to ensure that we | |
698 | don't have any non-ignored uncommitted changes. | |
699 | .PP | |
700 | \fBgit\-bundle\fP(1) is used to generate a bundle of the git repository. | |
701 | By default, all branches and tags in the repository are included in the | |
702 | bundle. | |
703 | .PP | |
704 | .B Build options | |
705 | .TP | |
706 | .BI \-\-git\-ref= ref | |
707 | Allows specifying a git ref to include in the git bundle. Use disables | |
708 | the default behavior of including all branches and tags. May be specified | |
709 | multiple times. The \fIref\fP can be the name of a branch or tag to | |
710 | include. It may also be any parameter that can be passed to | |
711 | \fBgit\-rev\-list\fP(1). For example, to include only | |
712 | the master branch, use \fB\-\-git\-ref=\fPmaster. To include all tags and | |
713 | branches, except for the private branch, use \fB\-\-git\-ref=\fP\-\-all | |
714 | \fB\-\-git\-ref=\fP^private | |
715 | .TP | |
716 | .BI \-\-git\-depth= number | |
717 | Creates a shallow clone with a history truncated to the specified number of | |
718 | revisions. | |
719 | .SS Format: 3.0 (bzr) | |
720 | Supported since dpkg 1.14.17. | |
721 | This format is experimental. | |
722 | It generates a single tarball containing the bzr repository. | |
723 | .PP | |
724 | .B Extracting | |
725 | .PP | |
726 | The tarball is unpacked and then bzr is used to checkout the current | |
727 | branch. | |
728 | .PP | |
729 | .B Building | |
730 | .PP | |
731 | Before going any further, some checks are done to ensure that we | |
732 | don't have any non-ignored uncommitted changes. | |
733 | .PP | |
734 | Then the VCS specific part of the source directory is copied over to a | |
735 | temporary directory. Before this temporary directory is packed in a tarball, | |
736 | various cleanup are done to save space. | |
737 | .SH DIAGNOSTICS | |
738 | .SS no source format specified in debian/source/format | |
739 | The file \fBdebian/source/format\fP should always exist and indicate the | |
740 | desired source format. For backwards compatibility, format “1.0” is | |
741 | assumed when the file doesn't exist but you should not rely on this: | |
742 | at some point in the future \fBdpkg\-source\fP will be modified to fail | |
743 | when that file doesn't exist. | |
744 | ||
745 | The rationale is that format “1.0” is no longer the recommended format, | |
746 | you should usually pick one of the newer formats (“3.0 (quilt)”, “3.0 | |
747 | (native)”) but \fBdpkg\-source\fP will not do this automatically for you. | |
748 | If you want to continue using the old format, you should be explicit about | |
749 | it and put “1.0” in \fBdebian/source/format\fP. | |
750 | .SS the diff modifies the following upstream files | |
751 | When using source format “1.0” it is usually a bad idea to modify | |
752 | upstream files directly as the changes end up hidden and mostly | |
753 | undocumented in the .diff.gz file. Instead you should store your changes | |
754 | as patches in the debian directory and apply them at build-time. To avoid | |
755 | this complexity you can also use the format “3.0 (quilt)” that offers | |
756 | this natively. | |
757 | .SS cannot represent change to \fIfile\fP | |
758 | Changes to upstream sources are usually stored with patch files, but not | |
759 | all changes can be represented with patches: they can only alter the | |
760 | content of plain text files. If you try replacing a file with something of | |
761 | a different type (for example replacing a plain file with a symlink or a | |
762 | directory), you will get this error message. | |
763 | .SS newly created empty file \fIfile\fB will not be represented in diff | |
764 | Empty files can't be created with patch files. Thus this change is not | |
765 | recorded in the source package and you are warned about it. | |
766 | .SS executable mode \fIperms\fB of \fIfile\fB will not be represented in diff | |
767 | Patch files do not record permissions of files and thus executable | |
768 | permissions are not stored in the source package. This warning reminds you | |
769 | of that fact. | |
770 | .SS special mode \fIperms\fB of \fIfile\fB will not be represented in diff | |
771 | Patch files do not record permissions of files and thus modified | |
772 | permissions are not stored in the source package. This warning reminds you | |
773 | of that fact. | |
774 | . | |
775 | .SH ENVIRONMENT | |
776 | .TP | |
777 | .B SOURCE_DATE_EPOCH | |
778 | If set, it will be used as the timestamp (as seconds since the epoch) to | |
779 | clamp the mtime in the \fBtar\fP(5) file entries. | |
780 | .TP | |
781 | .B VISUAL | |
782 | .TQ | |
783 | .B EDITOR | |
784 | Used by the “2.0” and “3.0 (quilt)” source format modules. | |
785 | .TP | |
786 | .B GIT_DIR | |
787 | .TQ | |
788 | .B GIT_INDEX_FILE | |
789 | .TQ | |
790 | .B GIT_OBJECT_DIRECTORY | |
791 | .TQ | |
792 | .B GIT_ALTERNATE_OBJECT_DIRECTORIES | |
793 | .TQ | |
794 | .B GIT_WORK_TREE | |
795 | Used by the “3.0 (git)” source format modules. | |
796 | . | |
797 | .SH FILES | |
798 | .SS debian/source/format | |
799 | This file contains on a single line the format that should be used to | |
800 | build the source package (possible formats are described above). No leading | |
801 | or trailing spaces are allowed. | |
802 | .SS debian/source/include\-binaries | |
803 | This file contains a list of binary files (one per line) that should be | |
804 | included in the debian tarball. Leading and trailing spaces are stripped. | |
805 | Lines starting with ‘\fB#\fP’ are comments and are skipped. | |
806 | Empty lines are ignored. | |
807 | .SS debian/source/options | |
808 | This file contains a list of long options that should be automatically | |
809 | prepended to the set of command line options of a \fBdpkg\-source \-\-build\fR | |
810 | or \fBdpkg\-source \-\-print\-format\fR call. Options like | |
811 | \fB\-\-compression\fR and \fB\-\-compression\-level\fR are well suited for | |
812 | this file. | |
813 | .P | |
814 | Each option should be put on a separate line. Empty lines and lines | |
815 | starting with ‘\fB#\fP’ are ignored. | |
816 | The leading ‘\fB\-\-\fP’ should be stripped and short options are | |
817 | not allowed. | |
818 | Optional spaces are allowed around the ‘\fB=\fP’ symbol and optional | |
819 | quotes are allowed around the value. | |
820 | Here's an example of such a file: | |
821 | .P | |
822 | # let dpkg\-source create a debian.tar.bz2 with maximal compression | |
823 | compression = "bzip2" | |
824 | compression\-level = 9 | |
825 | # use debian/patches/debian\-changes as automatic patch | |
826 | single\-debian\-patch | |
827 | # ignore changes on config.{sub,guess} | |
828 | extend-diff-ignore = "(^|/)(config\.sub|config\.guess)$" | |
829 | .P | |
830 | Note: \fBformat\fR options are not accepted in this file, you should | |
831 | use \fBdebian/source/format\fR instead. | |
832 | .SS debian/source/local\-options | |
833 | Exactly like \fBdebian/source/options\fP except that the file is not | |
834 | included in the generated source package. It can be useful to store | |
835 | a preference tied to the maintainer or to the VCS repository where | |
836 | the source package is maintained. | |
837 | .SS debian/source/local\-patch\-header \fRand\fP debian/source/patch\-header | |
838 | Free form text that is put on top of the automatic patch generated | |
839 | in formats “2.0” or “3.0 (quilt)”. \fBlocal\-patch\-header\fP is not | |
840 | included in the generated source package while \fBpatch\-header\fP is. | |
841 | .SS debian/patches/series | |
842 | This file lists all patches that have to be applied (in the given order) | |
843 | on top of the upstream source package. Leading and trailing spaces are | |
844 | stripped. | |
845 | Lines starting with ‘\fB#\fP’ are comments and are skipped. | |
846 | Empty lines are ignored. | |
847 | Remaining lines start with a patch filename (relative | |
848 | to the \fBdebian/patches/\fP directory) up to the first space character or | |
849 | the end of line. Optional \fBquilt\fP options can follow up to the end of line | |
850 | or the first ‘\fB#\fP’ preceded by one or more spaces (which marks the | |
851 | start of a comment up to the end of line). | |
852 | .SH BUGS | |
853 | The point at which field overriding occurs compared to certain | |
854 | standard output field settings is rather confused. | |
855 | .SH SEE ALSO | |
856 | .ad l | |
857 | .BR deb\-src\-control (5), | |
858 | .BR deb\-changelog (5), | |
859 | .BR dsc (5). |