Build and inspect Debian source packages with dpkg-source

You will choose an explicit Debian source format, build a small source package, inspect its .dsc metadata, and extract it into a clean directory. The commands and option names below match dpkg-source 1.22.6, installed by dpkg-dev on this machine.

1. Check the installed command

Confirm which executable you will use and record its version. This catches the common mistake of reading documentation for a different dpkg release:

$ command -v dpkg-source
/usr/bin/dpkg-source
$ dpkg-source --version
Debian dpkg-source version 1.22.6.

If your version differs, keep the local manual page beside you. Source formats and defaults are versioned behaviour.

2. Make the source format explicit

Put one format name on one line in debian/source/format. For a normal package whose Debian changes are represented as quilt patches, 3.0 (quilt) is the usual choice. For a Debian-specific package with no separate upstream release, use 3.0 (native).

The old fallback is 1.0 when the file is absent, but the manual page marks that fallback as deprecated. Do not leave the choice implicit in a package you maintain.

$ mkdir -p debian/source
$ printf '%s\n' '3.0 (quilt)' > debian/source/format
$ dpkg-source --print-format .
3.0 (quilt)

Checkpoint: the printed format must match the line you intended. --format=VALUE can override the file for one build, but that does not document the choice for later builds.

3. Check the control files before building

debian/control is a deb822 file. It needs a source stanza followed by one stanza for each binary package. Fields are separated by a colon, and continuation lines begin with a space. The source stanza normally includes Source, Maintainer, and Build-Depends; each binary stanza needs fields such as Package, Architecture, and Description.

debian/changelog supplies the package name and version used in generated filenames. A quick read avoids building a package with an unexpected identity:

$ sed -n '1,28p' debian/control
$ sed -n '1,8p' debian/changelog
$ dpkg-source --print-format .
3.0 (quilt)

Do not use a shell variable or command substitution as a substitute for checking these files. The source package name, version, and format are recorded in the resulting .dsc.

4. Build the source package

Run --build with the source-tree directory as its one positional argument:

$ dpkg-source --build .
dpkg-source: info: using source format '3.0 (quilt)'
dpkg-source: info: building PACKAGE in PACKAGE_VERSION.debian.tar.xz
dpkg-source: info: building PACKAGE in PACKAGE_VERSION.dsc

Replace the example names in the expected output with the package and version from your changelog. For 3.0 (quilt), the output normally includes an upstream tarball, a Debian tarball, and a .dsc. A 3.0 (native) package has a single source tarball plus the .dsc.

Compression defaults to xz for formats 2.0 and newer. --compression=gzip or another supported value affects newly created files only; it does not recompress an archive already present.

Warning: A quilt build can generate an automatic patch for unrecorded upstream changes, or fail when a binary change cannot be represented as a text diff. Review the output and the working tree before distributing anything. If the change is intentional, record it as a named patch or deliberately use the documented automatic-patch options.

5. Inspect the .dsc before sharing it

The .dsc is another deb822 document. It names the source format, package, version, binary packages, and the files that make up the source package. Its Files, Checksums-Sha1, and Checksums-Sha256 fields list a checksum, size, and filename for each file.

$ dsc=$(find .. -maxdepth 1 -name '*.dsc' -print -quit)
$ sed -n '1,80p' "$dsc"
Format: 3.0 (quilt)
Source: PACKAGE
Version: PACKAGE_VERSION
Checksums-Sha256:
 ...

The exact checksum values and field order vary. Check that every file named by the .dsc is beside it and that the format is the one you selected. A missing or moved tarball makes the source package unusable.

6. Extract into a new staging directory

Keep the .dsc and its referenced archives together, then extract to a directory that does not exist:

$ mkdir -p ../source-review
$ dpkg-source --extract PACKAGE_VERSION.dsc ../source-review/PACKAGE-VERSION
dpkg-source: info: extracting PACKAGE in ../source-review/PACKAGE-VERSION
dpkg-source: info: unpacking PACKAGE_VERSION.orig.tar.xz
dpkg-source: info: unpacking PACKAGE_VERSION.debian.tar.xz

If you omit the second argument, dpkg-source creates a source-version directory below the current directory. The explicit path makes it harder to confuse a review tree with your working tree.

By default, extraction checks signatures and checksums. Keep that protection. --no-check disables it and should be reserved for a deliberate recovery or investigation. --require-valid-signature raises the bar by refusing an unsigned or unverifiable package. --require-strong-checksums requires a strong checksum, currently SHA-256.

Security boundary: Source archives and their control data are untrusted input. Extract them as an ordinary user in a disposable directory, not as root. Review the package before compiling or running its build machinery.

7. Recover from the usual errors

The extraction example changes only the staging directory. To undo it, remove that specific review directory after checking its path, or leave it for comparison. Rebuilding does create archives beside the source tree, so clean up only generated files that you have identified and no longer need.

Done means