Generate a Useful Debian .buildinfo File with dpkg-genbuildinfo

You will finish with a Debian .buildinfo file that records the package build, its output checksums, the build architecture and relevant installed dependencies. You will also know where the command looks for its input and which metadata it deliberately leaves out. Allow about 10 minutes once the package build itself is complete.

This guide uses dpkg-genbuildinfo from dpkg-dev version 1.22.6ubuntu6.6, reporting dpkg version 1.22.6 on the machine used for these examples. The command reads an unpacked Debian source tree and the files produced by its build. It does not build the package for you.

1. Check the installed command

Run the version check before relying on option or field details in automation:

$ dpkg-genbuildinfo --version
Debian dpkg-genbuildinfo version 1.22.6.

The command accepts no package name in its normal syntax. Run it from the unpacked source tree, where the default input files are debian/control, debian/changelog and debian/files. You normally run it as your build user. It does not need root, and using sudo can make the resulting environment record less representative of the build.

2. Finish the build and check its file list

Only generate the record after the build has produced the files you intend to describe. From the source tree, inspect the list first:

$ cd /path/to/source-tree
$ sed -n '1,80p' debian/files
demo_0.1-1_amd64.deb debian optional
demo_0.1-1.dsc debian optional

The exact lines depend on the package and build. The important point is that debian/files names the generated files and that those files are in the directory where dpkg-genbuildinfo expects to find them, normally the parent directory of the source tree. A missing file is a hard failure, not a warning that should be ignored.

Checkpoint: verify the named files without changing them. Adjust the example names to match your list:

$ test -f ../demo_0.1-1_amd64.deb
$ test -f ../demo_0.1-1.dsc
$ echo "build outputs are present"
build outputs are present

3. Generate the default full record

With the usual Debian layout, the shortest command is:

$ dpkg-genbuildinfo

With no --build option, the default is full. That includes the unqualified, architecture-specific and architecture-independent build dependency classes. The output file is written beside the source tree, using a name based on the source name, version and architecture. For example, a build that includes architecture-specific output may produce ../demo_0.1-1_amd64.buildinfo.

The filename is not cosmetic. The deb-buildinfo(5) format uses a name that is only as specific as the build: an any build uses an architecture name, an all-only build uses all, and a source-only build uses source. Do not rename a file into a different build category.

If the command prints informative messages on standard error and you have already checked the inputs, -q suppresses those messages. It does not suppress errors.

4. Choose the build scope deliberately

Use --build=type when the record must describe a particular part of a build:

• --build=any includes Build-Depends and Build-Depends-Arch.
• --build=all includes Build-Depends and Build-Depends-Indep.
• --build=source records the unqualified Build-Depends set.
• --build=binary is an alias for any,all.
• --build=full is an alias for any,all,source, and is the default.

For example, generate an architecture-independent record explicitly:

$ dpkg-genbuildinfo --build=all

Use a comma-separated list only when it reflects what was actually built. Do not select full merely because it sounds more complete: the build type affects dependency information and the output filename.

5. Write to a known destination

For scripts and CI, -O avoids having to discover the generated filename. With a filename, it writes the record there:

$ dpkg-genbuildinfo -O../artifacts/demo.buildinfo
$ test -s ../artifacts/demo.buildinfo
$ sed -n '1,18p' ../artifacts/demo.buildinfo
Format: 1.0
Source: demo
Binary: demo
Architecture: amd64 source
Version: 0.1-1

Create ../artifacts before running this command if it does not exist. The destination is ordinary output state, so check it before overwriting a record you may need for an upload or reproducibility investigation. A safer replacement pattern is to write to a new name, inspect it, then move it into place only after it passes your checks.

With bare -O, the record is printed to standard output. That is useful for inspection or a controlled pipeline, but do not mix it with command output that would make the deb822 document invalid:

$ dpkg-genbuildinfo -O | sed -n '1,12p'
Format: 1.0
Source: demo
Binary: demo

6. Read the record without mistaking optional fields for failures

A valid file is deb822-style control data. Required build information includes Format, Source, Architecture, Version, the checksum sets, Build-Architecture and Installed-Build-Depends. A binary build normally has Binary; a source-only build omits it from dpkg 1.20.0 onwards.

The checksum sections list each file with its digest, size and filename. They are multiline fields, so preserve their continuation indentation if you process the file. The Build-Date, distribution origin and environment details describe the build context, not package dependencies that you should edit by hand.

Some fields are intentionally conditional. Build-Kernel-Version is omitted unless requested with --always-include-kernel. Build-Path is normally included only for an allowed path pattern, which on Debian and derivatives starts with /build/. --always-include-path forces it on, and can disclose a local absolute path. Treat both options as metadata and privacy decisions, not routine troubleshooting switches.

7. Diagnose the common failures

If the command says it cannot find a .deb or .dsc, inspect debian/files, the parent directory and the spelling of the version. Do not create empty placeholder artefacts: their checksums would describe the wrong build.

If your project keeps outputs somewhere else, use -u to tell the command where to look:

$ dpkg-genbuildinfo -u../artifacts -O../artifacts/demo.buildinfo

The same option also affects the default output directory when -O is not used. If the control or changelog file has a non-standard location, use -c/path/to/control or -l/path/to/changelog. A non-standard changelog format can be selected with -F, as documented by dpkg-parsechangelog(1).

When investigating a record, compare its build scope, source version and checksum list with the build log. A successful exit status means the file was generated from the inputs it found; it does not prove that the package is reproducible or that the listed outputs came from the intended build.