Generate and Check a Debian Control File with dpkg-gencontrol

dpkg-gencontrol writes the binary control metadata to debian/tmp/DEBIAN/control, and you can preview it first. Allow about fifteen minutes. You need an unpacked Debian source tree, the dpkg-dev package, and a valid debian/control plus debian/changelog.

The installed command used for this guide is dpkg-gencontrol from dpkg-dev version 1.22.6ubuntu6.6, reporting Debian dpkg version 1.22.6. Details such as fields and diagnostics can differ in other releases.

1. Check the command and package layout

Start with read-only checks from the top of the source tree. This does not require elevated privileges:

$ command -v dpkg-gencontrol
/usr/bin/dpkg-gencontrol
$ dpkg-gencontrol --version | head -n 2
Debian dpkg-gencontrol version 1.22.6
$ test -f debian/control && test -f debian/changelog && echo "packaging files found"
packaging files found

debian/control supplies source and binary package stanzas. The changelog supplies the version and other release information. If the source stanza describes several binary packages, you must select one with -p. With one binary package, selection can be omitted, but using it makes a script explicit.

Checkpoint: run dpkg-parsechangelog if the version is unclear. Its Version line should be the version you expect in the generated binary stanza.

2. Generate a control file for one package

Use an explicit package name and the default build directory:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE

Replace YOUR_BINARY_PACKAGE with the exact Package: value from debian/control. The command writes debian/tmp/DEBIAN/control and adds the presumed binary archive name to debian/files. It also calculates the default Installed-Size from the package build directory.

This is a normal build-tree operation. It does change those two generated files, so do not run it in a working tree where you need an untouched build state without first checking the diff:

$ sed -n '1,80p' debian/tmp/DEBIAN/control
$ tail -n 5 debian/files

The exact archive name depends on package version, architecture and the package metadata. Do not hand-edit debian/files to make it match a guess. Rerun the relevant build step after changing package metadata.

3. Inspect output without writing the default file

For a dry inspection, send the control file to standard output with -O. This avoids changing the default control-file path:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE -O

A successful result starts with fields such as Package, Version, Architecture, Maintainer and Installed-Size. The output also includes the package description. Capture it in a new temporary file when you need to review or compare it:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE -O /tmp/YOUR_BINARY_PACKAGE.control
$ sed -n '1,80p' /tmp/YOUR_BINARY_PACKAGE.control

The file in /tmp is disposable review output, not an installed package control file. Avoid naming it after a real file that another build process expects.

4. Apply substitutions and field changes deliberately

Use -Vname=value to provide an output substitution variable and -Dfield=value to override or add a field. For example, this supplies a value used by a ${binary:Version} or other supported substitution in the package metadata:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE -Vbuild.channel=local -DXB-Build-Channel=local -O

Substitution variables are read from debian/substvars by default. Use -TFILE to read another substitution file, and repeat -T when several files are needed:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE -Tdebian/substvars -O

Use -Ufield to remove a field from the output. For example, -USection removes the generated Section field. The older -is, -ip and -isp switches are deprecated compatibility options and are ignored; use -U when you intentionally need to remove a field.

Keep overrides close to the build command that needs them. A field override can produce metadata that is syntactically valid but wrong for a repository, so inspect the result before uploading.

5. Choose a different build directory or filename

When the package contents are staged somewhere other than debian/tmp, pass that directory with -P:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE -Pbuild/package-root -O

This changes the directory scanned for the default Installed-Size, and also changes the default destination if -O is not used. Use -nFILENAME when the presumed archive filename must differ from the normal package-version-architecture form:

$ dpkg-gencontrol -pYOUR_BINARY_PACKAGE -n YOUR_BINARY_PACKAGE-custom.deb -O

Keep -P pointed at the actual staged package root. A successful command with the wrong directory can calculate a misleading installed size. If the directory is owned by another user or is not readable, investigate permissions first; do not make the whole build tree writable as a shortcut.

6. Diagnose failures without damaging the build

For an unknown option or spelling error, use --help. For a missing binary package, compare the requested name with every Package: stanza in debian/control. For a version or changelog error, run dpkg-parsechangelog and fix the source metadata before retrying.

A missing debian/tmp/DEBIAN directory, an unreadable control file, or a failed substitution can stop generation. Check paths and permissions with read-only commands such as find and stat. The command does not install the package and does not need sudo. Running it as root can leave generated files owned by root, creating a later cleanup problem.

If you need to discard generated output, first inspect git diff -- debian/files debian/tmp/DEBIAN/control. Then use your normal build-clean command or remove only files you have positively identified as generated. Do not delete the whole debian directory: it contains source metadata that is not recreated by dpkg-gencontrol.