1dpkg-source(1) dpkg utilities dpkg-source(1)
2
6 dpkg-source - Debian source package (.dsc) manipulation tool
7
9 dpkg-source [options] command
10
12 dpkg-source packs and unpacks Debian source archives.
13 None of these commands allow multiple options to be combined into one,
15 and they do not allow the value for an option to be specified in a sep‐
16 arate argument.
17
19 -x filename.dsc [output-directory]
20 Extract a source package. One non-option argument must be sup‐
21 plied, the name of the Debian source control file (.dsc). An
22 optional second non-option argument may be supplied to specify
23 the directory to extract the source package to, this must not
24 exist. If no output directory is specified, the source package
25 is extracted into a directory named source-version under the
26 current working directory.
27 dpkg-source will read the names of the other file(s) making up
29 the source package from the control file; they are assumed to be
30 in the same directory as the .dsc.
31 The files in the extracted package will have their permissions
33 and ownerships set to those which would have been expected if
34 the files and directories had simply been created - directories
35 and executable files will be 0777 and plain files will be 0666,
36 both modified by the extractors' umask; if the parent directory
37 is setgid then the extracted directories will be too, and all
38 the files and directories will inherit its group ownership.
39 If the source package uses a non-standard format (currently this
41 means all formats except "1.0"), its name will be stored in
42 debian/source/format so that the following builds of the source
43 package use the same format by default.
44 -b directory [format-specific-parameters]
47 Build a source package. The first non-option argument is taken
48 as the name of the directory containing the debianized source
49 tree (i.e. with a debian sub-directory and maybe changes to the
50 original files). Depending on the source package format used to
51 build the package, additional parameters might be accepted.
52 dpkg-source will build the source package with the first format
54 that works from this ordered list: the format(s) indicated with
55 the --format command-line option(s), the format indicated in
56 debian/source/format, "1.0", "3.0 (quilt)", "3.0 (native)". See
57 section SOURCE PACKAGE FORMATS for an extensive description of
58 the various source package formats.
59 --print-format directory
62 Print the source format that would be used to build the source
63 package if dpkg-source -b directory was called (in the same con‐
64 ditions and with the same parameters). In particular it's impor‐
65 tant that the upstream tarball (if any) can be found in the cur‐
66 rent directory.
67 -h, --help
70 Show the usage message and exit.
71 --version
73 Show the version and exit.
74
76 -ccontrolfile
77 Specifies the main source control file to read information from.
78 The default is debian/control. If given with relative pathname
79 this is interpreted starting at the source tree's top level
80 directory.
81 -lchangelogfile
83 Specifies the change log file to read information from. The
84 default is debian/changelog. If given with relative pathname
85 this is interpreted starting at the source tree's top level
86 directory.
87 -Fchangelogformat
89 Specifies the format of the changelog. By default the format is
90 read from a special line near the bottom of the changelog or
91 failing that defaults to the debian standard format.
92 --format=value
94 Try first the given format for building the source package. If
95 used multiple times, they are tried in order. It does override
96 any format given in debian/source/format.
97 -Vname=value
99 Set an output substitution variable. See deb-substvars(5) for a
100 discussion of output substitution.
101 -Tsubstvarsfile
103 Read substitution variables in substvarsfile; the default is to
104 not read any file.
105 -Dfield=value
107 Override or add an output control file field.
108 -Ufield
110 Remove an output control file field.
111 -Zcompression, --compression=compression
113 Specify the compression to use for created files (tarballs and
114 diffs). Note that this option will not cause existing tarballs
115 to be recompressed, it only affects new files. Supported values
116 are: gzip, bzip2, lzma and xz. gzip is the default. xz is only
117 supported since dpkg-dev 1.15.5.
118 -zlevel, --compression-level=level
120 Compression level to use. As with -Z it only affects newly cre‐
121 ated files. Supported values are: 1 to 9, best, and fast. 9 is
122 the default.
123 -i[regexp]
125 You may specify a perl regular expression to match files you
126 want filtered out of the list of files for the diff. (This list
127 is generated by a find command.) (If the source package is being
128 built as a version 3 source package using a VCS, this can be
129 used to ignore uncommited changes on specific files. Using -i.*
130 will ignore all of them.) -i by itself enables the option, with
131 a default regexp that will filter out control files and directo‐
132 ries of the most common revision control systems, backup and
133 swap files and Libtool build output directories. There can only
134 be one active regexp, of multiple -i options only the last one
135 will take effect.
136 This is very helpful in cutting out extraneous files that get
138 included in the diff, e.g. if you maintain your source in a
139 revision control system and want to use a checkout to build a
140 source package without including the additional files and direc‐
141 tories that it will usually contain (e.g. CVS/, .cvsignore,
142 .svn/). The default regexp is already very exhaustive, but if
143 you need to replace it, please note that by default it can match
144 any part of a path, so if you want to match the begin of a file‐
145 name or only full filenames, you will need to provide the neces‐
146 sary anchors (e.g. '(^|/)', '($|/)') yourself.
147 -I[file-pattern]
149 If this option is specified, the pattern will be passed to
150 tar(1)'s --exclude option when it is called to generate a
151 .orig.tar or .tar file. For example, -ICVS will make tar skip
152 over CVS directories when generating a .tar.gz file. The option
153 may be repeated multiple times to list multiple patterns to
154 exclude.
155 -I by itself adds default --exclude options that will filter out
157 control files and directories of the most common revision con‐
158 trol systems, backup and swap files and Libtool build output
159 directories.
160 Note: While they have similar purposes, -i and -I have very different
162 syntax and semantics. -i can only be specified once and takes a perl
163 compatible regular expression which is matched against the full rela‐
164 tive path of each file. -I can specified multiple times and takes a
165 filename pattern with shell wildcards. The pattern is applied to the
166 full relative path but also to each part of the path individually. The
167 exact semantic of tar's --exclude option is somewhat complicated, see
168 http://www.gnu.org/software/tar/manual/tar.html#wildcards for a full
169 documentation.
170 The default regexp and patterns for both options can be seen in the
172 output of the --help command.
173
175 --no-copy
176 Do not copy original tarballs near the extracted source package.
177 --no-check
179 Do not check signatures and checksums before unpacking.
180 --require-valid-signature
182 Refuse to unpack the source package if it doesn't contain an
183 OpenPGP signature that can be verified either with the user's
184 trustedkeys.gpg keyring, one of the vendor-specific keyrings, or
185 one of the official Debian keyrings (/usr/share/keyrings/debian-
186 keyring.gpg and /usr/share/keyrings/debian-maintainers.gpg).
187
190 If you don't know what source format you should use, you should proba‐
191 bly pick either "3.0 (quilt)" or "3.0 (native)". They will become the
192 default formats in the near future. See
193 http://wiki.debian.org/Projects/DebSrc3.0 for information on the
194 deployment of those formats within Debian.
195 Format: 1.0
198 A source package in this format consists either of a .orig.tar.gz asso‐
199 ciated to a .diff.gz or a single .tar.gz (in that case the package is
200 said to be native).
201 Extracting
203 Extracting a native package is a simple extraction of the single tar‐
205 ball in the target directory. Extracting a non-native package is done
206 by first unpacking the .orig.tar.gz and then applying the patch con‐
207 tained in the .diff.gz file. The timestamp of all patched files is
208 reset to the extraction time of the source package (this avoids time‐
209 stamp skews leading to problems when autogenerated files are patched).
210 The diff can create new files (the whole debian directory is created
211 that way) but can't remove files (empty files will be left over).
212 Building
214 Building a native package is just creating a single tarball with the
216 source directory. Building a non-native package involves extracting the
217 original tarball in a separate ".orig" directory and regenerating the
218 .diff.gz by comparing the source package directory with the .orig
219 directory.
220 Build options (with -b):
223 If a second non-option argument is supplied it should be the name of
225 the original source directory or tarfile or the empty string if the
226 package is a Debian-specific one and so has no Debianisation diffs. If
227 no second argument is supplied then dpkg-source will look for the orig‐
228 inal source tarfile package_upstream-version.orig.tar.gz or the origi‐
229 nal source directory directory.orig depending on the -sX arguments.
230 -sa, -sp, -sk, -su and -sr will not overwrite existing tarfiles or
232 directories. If this is desired then -sA, -sP, -sK, -sU and -sR should
233 be used instead.
234 -sk Specifies to expect the original source as a tarfile, by default
236 package_upstream-version.orig.tar.extension. It will leave this
237 original source in place as a tarfile, or copy it to the current
238 directory if it isn't already there. The tarball will be
239 unpacked into directory.orig for the generation of the diff.
240 -sp Like -sk but will remove the directory again afterwards.
242 -su Specifies that the original source is expected as a directory,
244 by default package-upstream-version.orig and dpkg-source will
245 create a new original source archive from it.
246 -sr Like -su but will remove that directory after it has been used.
248 -ss Specifies that the original source is available both as a direc‐
250 tory and as a tarfile. dpkg-source will use the directory to
251 create the diff, but the tarfile to create the .dsc. This
252 option must be used with care - if the directory and tarfile do
253 not match a bad source archive will be generated.
254 -sn Specifies to not look for any original source, and to not gener‐
256 ate a diff. The second argument, if supplied, must be the empty
257 string. This is used for Debian-specific packages which do not
258 have a separate upstream source and therefore have no debianisa‐
259 tion diffs.
260 -sa or -sA
262 Specifies to look for the original source archive as a tarfile
263 or as a directory - the second argument, if any, may be either,
264 or the empty string (this is equivalent to using -sn). If a
265 tarfile is found it will unpack it to create the diff and remove
266 it afterwards (this is equivalent to -sp); if a directory is
267 found it will pack it to create the original source and remove
268 it afterwards (this is equivalent to -sr); if neither is found
269 it will assume that the package has no debianisation diffs, only
270 a straightforward source archive (this is equivalent to -sn).
271 If both are found then dpkg-source will ignore the directory,
272 overwriting it, if -sA was specified (this is equivalent to -sP)
273 or raise an error if -sa was specified. -sA is the default.
274 Extract options (with -x):
276 In all cases any existing original source tree will be removed.
278 -sp Used when extracting then the original source (if any) will be
280 left as a tarfile. If it is not already located in the current
281 directory or if an existing but different file is there it will
282 be copied there. (This is the default).
283 -su Unpacks the original source tree.
285 -sn Ensures that the original source is neither copied to the cur‐
287 rent directory nor unpacked. Any original source tree that was
288 in the current directory is still removed.
289 All the -sX options are mutually exclusive. If you specify more than
291 one only the last one will be used.
292 --skip-debianization
294 Skips application of the debian diff on top of the upstream
295 sources.
296 Format: 2.0
298 Also known as wig&pen. This format is not recommended for wide-spread
299 usage, the format "3.0 (quilt)" replaces it. Wig&pen was the first
300 specification of a new-generation source package format.
301 The behaviour of this format is the same as the "3.0 (quilt)" format
303 except that it doesn't use an explicit list of patches. All files in
304 debian/patches/ matching the perl regular expression [\w-]+ must be
305 valid patches: they are applied at extraction time.
306 When building a new source package, any change to the upstream source
308 is stored in a patch named zz_debian-diff-auto.
309 Format: 3.0 (native)
311 This format is an extension of the native package format as defined in
312 the 1.0 format. It supports all compression methods and will ignore by
313 default any VCS specific files and directories as well as many tempo‐
314 rary files (see default value associated to -I option in the --help
315 output).
316 Format: 3.0 (quilt)
318 A source package in this format contains at least an original tarball
319 (.orig.tar.ext where ext can be gz, bz2, lzma and xz) and a debian tar‐
320 ball (.debian.tar.ext). It can also contain additional original tar‐
321 balls (.orig-component.tar.ext). component can only contain alphanu‐
322 meric characters and dashes ("-").
323 Extracting
325 The main original tarball is extracted first, then all additional orig‐
327 inal tarballs are extracted in subdirectories named after the component
328 part of their filename (any pre-existing directory is replaced). The
329 debian tarball is extracted on top of the source directory after prior
330 removal of any pre-existing debian directory. Note that the debian tar‐
331 ball must contain a debian sub-directory but it can also contain binary
332 files outside of that directory (see --include-binaries option).
333 All patches listed in debian/patches/debian.series or
335 debian/patches/series are then applied. If the former file is used and
336 the latter one doesn't exist (or is a symlink), then the latter is
337 replaced with a symlink to the former. This is meant to simplify usage
338 of quilt to manage the set of patches. Note however that while
339 dpkg-source parses correctly series files with explicit options used
340 for patch application (stored on each line after the patch filename and
341 one or more spaces), it does ignore those options and always expect
342 patches that can be applied with the -p1 option of patch. It will thus
343 emit a warning when it encounters such options, and the build is likely
344 to fail.
345 Similarly to quilt's default behaviour, the patches can remove files
347 too.
348 The file .pc/applied-patches is created if some patches have been
350 applied during the extraction.
351 Building
353 All original tarballs found in the current directory are extracted in a
355 temporary directory by following the same logic as for the unpack, the
356 debian directory is copied over in the temporary directory, and all
357 patches except the automatic patch (debian-changes-version or debian-
358 changes, depending on --single-debian-patch) are applied. The temporary
359 directory is compared to the source package directory and the diff (if
360 non-empty) is stored in the automatic patch. If the automatic patch is
361 created/deleted, it's added/removed from the series file and from the
362 quilt metadata.
363 Any change on a binary file is not representable in a diff and will
365 thus lead to a failure unless the maintainer deliberately decided to
366 include that modified binary file in the debian tarball (by listing it
367 in debian/source/include-binaries). The build will also fail if it
368 finds binary files in the debian sub-directory unless they have been
369 whitelisted through debian/source/include-binaries.
370 The updated debian directory and the list of modified binaries is then
372 used to generate the debian tarball.
373 The automatically generated diff doesn't include changes on VCS spe‐
375 cific files as well as many temporary files (see default value associ‐
376 ated to -i option in the --help output). In particular, the .pc direc‐
377 tory used by quilt is ignored during generation of the automatic patch.
378 Note: dpkg-source expects the source tree to have all patches listed in
380 the series file applied when you generate the source package. This is
381 not the case when the source tree has been obtained by unpacking a
382 source package using the Format: 1.0 for instance. To mitigate the
383 problem, dpkg-source will apply the patches by itself if it believes
384 that they have not yet been applied. To detect this situation, it uses
385 the following heuristic: it finds the list of supposedly unapplied
386 patches (they are listed in the series file but not in .pc/applied-
387 patches), and if the first patch in that set can be applied without
388 errors, it will apply them all. The option --no-preparation can be
389 used to disable this behaviour.
390 Build options
392 --allow-version-of-quilt-db=version
394 Allow dpkg-source to build the source package if the version of
395 the quilt metadata is the one specified, even if dpkg-source
396 doesn't know about it. Effectively this says that the given ver‐
397 sion of the quilt metadata is compatible with the version 2 that
398 dpkg-source currently supports. The version of the quilt meta‐
399 data is stored in .pc/.version.
400 --include-removal
402 Do not ignore removed files and include them in the automati‐
403 cally generated patch.
404 --include-timestamp
406 Include timestamp in the automatically generated patch.
407 --include-binaries
409 Add all modified binaries in the debian tarball. Also add them
410 to debian/source/include-binaries: they will be added by default
411 in subsequent builds and this option is thus no more needed.
412 --no-preparation
414 Do not try to prepare the build tree by applying patches which
415 are apparently unapplied.
416 --single-debian-patch
418 Use debian/patches/debian-changes instead of
419 debian/patches/debian-changes-version for the name of the auto‐
420 matic patch generated during build. This option is particularly
421 useful when the package is maintained in a VCS and a patch set
422 can't reliably be generated. Instead the current diff with
423 upstream should be stored in a single patch. When using this
424 option, it is recommended to create a debian/source/patch-header
425 file explaining how the Debian changes can be best reviewed, for
426 example in the VCS that is used.
427 Extract options
430 --skip-debianization
432 Skips extraction of the debian tarball on top of the upstream
433 sources.
434 --skip-patches
436 Do not apply patches at the end of the extraction.
437 Format: 3.0 (custom)
439 This format is particular. It doesn't represent a real source package
440 format but can be used to create source packages with arbitrary files.
441 Build options
443 All non-option arguments are taken as files to integrate in the gener‐
445 ated source package. They must exist and are preferrably in the current
446 directory. At least one file must be given.
447 --target-format=value
449 Required. Defines the real format of the generated source pack‐
450 age. The generated .dsc file will contain this value in its
451 Format field and not "3.0 (custom)".
452 Format: 3.0 (git) and 3.0 (bzr)
454 Those formats are experimental. They generate a single tarball contain‐
455 ing the corresponding VCS repository.
456 Extracting
458 The tarball is unpacked and then the VCS is used to checkout the cur‐
460 rent branch.
461 Building
463 Before going any further, some checks are done to ensure that we don't
465 have any non-ignored uncommitted changes.
466 Then the VCS specific part of the source directory is copied over to a
468 temporary directory. Before this temporary directory is packed in a
469 tarball, various cleanup are done to save space.
470
472 debian/source/format
473 This file contains on a single line the format that should be used to
474 build the source package (possible formats are described above). No
475 leading or trailing spaces are allowed.
476 debian/source/include-binaries
478 This file contains a list of binary files (one per line) that should be
479 included in the debian tarball. Leading and trailing spaces are
480 stripped. Lines starting with "#" are comments and are skipped. Empty
481 lines are ignored.
482 debian/source/options
484 This file contains a list of long options that should be automatically
485 prepended to the set of command line options of a dpkg-source -b or
486 dpkg-source --print-format call. Options like --compression and --com‐
487 pression-level are well suited for this file.
488 Each option should be put on a separate line. Empty lines and lines
490 starting with "#" are ignored. The leading "--" should be stripped and
491 short options are not allowed. Optional spaces are allowed around the
492 "=" symbol and optional quotes are allowed around the value. Here's an
493 example of such a file:
494 # let dpkg-source create a debian.tar.bz2 with maximal compression
496 compression = "bzip2"
497 compression-level = 9
498 # use debian/patches/debian-changes as automatic patch
499 single-debian-patch
500 Note: format options are not accepted in this file, you should use
502 debian/source/format instead.
503 debian/source/patch-header
505 Free form text that is put on top of the automatic patch generated in
506 formats "2.0" or "3.0 (quilt)".
507 debian/patches/series
509 This file lists all patches that have to be applied (in the given
510 order) on top of the upstream source package. Leading and trailing spa‐
511 ces are stripped. Lines starting with "#" are comments and are skipped.
512 Empty lines are ignored. Remaining lines start with a patch filename
513 (relative to the debian/patches/ directory) up to the first space char‐
514 acter or the end of line. Optional quilt options can follow up to the
515 end of line or the first "#" preceded by one or more spaces (which
516 marks the start of a comment up to the end of line).
517
519 The point at which field overriding occurs compared to certain standard
520 output field settings is rather confused.
521
523 dpkg-deb(1), dpkg(1), dselect(1).
524
526 Copyright © 1995-1996 Ian Jackson
527 Copyright © 2000 Wichert Akkerman
528 Copyright © 2008-2009 Raphaël Hertzog
529 This is free software; see the GNU General Public Licence version 2 or
531 later for copying conditions. There is NO WARRANTY.
532Debian Project 2009-11-11 dpkg-source(1)