Read the Debian Build API Level with dpkg-buildapi

You will finish with a safe way to ask Debian packaging tools which dpkg build API level applies to a source package, plus a small shell or Makefile check that uses the result. The installed command is from dpkg 1.22.6, supplied by the dpkg-dev package. Allow about ten minutes. You need a shell and a Debian source package tree, but no elevated privileges.

dpkg-buildapi reads the source package control file and prints one number. With no declared API dependency, that number is 0. A package that declares dpkg-build-api (= 1) gets 1. The command only reports the level: it does not edit debian/control, rebuild a package or change the system.

1. Confirm the installed command

Start with the two read-only queries below:

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

Your package revision can differ from the upstream tool version. Check the package record when you need an exact local installation:

$ dpkg-query -W -f='${Package} ${Version}\n' dpkg-dev dpkg
dpkg-dev 1.22.6ubuntu6.6
dpkg 1.22.6ubuntu6.6

Checkpoint: if the command is missing, install or repair dpkg-dev through your normal system administration process. Do not replace it with a copied binary from an unrelated distribution.

2. Read the package's default level

Change into the root of a source package and run the command without options:

$ cd /path/to/source-package
$ dpkg-buildapi
0

The default control path is debian/control. The command looks for an exact build dependency named dpkg-build-api in Build-Depends, Build-Depends-Indep or Build-Depends-Arch. If none of those fields declares a level, the result is the legacy global level, 0.

Do not confuse this with the package's minimum dpkg version. A dependency such as dpkg-dev (>= 1.22.0) does not select build API level 1. The package must declare the virtual build dependency itself.

3. Declare and verify API level 1

If the package has adopted level 1, its source control file should contain an exact dependency:

Build-Depends: dpkg-build-api (= 1)

That is a state-changing edit to package metadata, so review the surrounding dependency list and keep the change under version control. Once the field is present, verify what the installed tool resolves:

$ dpkg-buildapi
1
$ printf 'build API level: %s\n' "$(dpkg-buildapi)"
build API level: 1

Use the output as data, not as a sentence to parse. The value is an integer level that packaging helpers can compare with their supported interfaces. Level 1 is available in dpkg 1.22.0 and later. The exact behaviours attached to an API level are documented separately from this command, so check the matching dpkg-build-api(7) documentation before relying on a particular compatibility guarantee.

4. Select a different control file for a test

Use the compact -cFILE form when a script or test fixture is not using debian/control:

$ dpkg-buildapi -c/tmp/package-test/control
1

The option is written as -c immediately followed by the file name. Passing -c /tmp/package-test/control is not equivalent with this installed command: the program treats the separated path as an extra argument and exits with status 2. Verify a fixture without touching the real package:

$ dpkg-buildapi -c/tmp/package-test/control
1
$ printf 'status: %s\n' "$?"
status: 0

A missing default file is an error, not an implicit level 0:

$ dpkg-buildapi
dpkg-buildapi: error: cannot read debian/control: No such file or directory
$ printf 'status: %s\n' "$?"
status: 25

5. Use the environment override carefully

DPKG_BUILD_API is intended for tools run from debian/rules. It lets an internal helper reuse the already-resolved value without parsing the control file again. It is not the right way to hide a package's declared API level from the build driver.

$ DPKG_BUILD_API=1 dpkg-buildapi
1

The environment value takes precedence over the control file. It is still checked against the highest level supported by the installed dpkg. On this dpkg 1.22.6 system, asking for level 2 fails:

$ DPKG_BUILD_API=2 dpkg-buildapi
dpkg-buildapi: error: dpkg build API level '2' greater than max '1'
$ printf 'status: %s\n' "$?"
status: 25

Keep this override local to the helper invocation, as shown above. Exporting it broadly can make a build helper report a value that the build driver did not select. If a package needs level 1, declare it in the control file so dependency resolution and the build agree.

6. Put the result into Make

The installed package includes /usr/share/dpkg/buildapi.mk. Include it from a packaging makefile to populate DPKG_BUILD_API and use the supplied comparison function:

include /usr/share/dpkg/buildapi.mk

ifneq ($(call dpkg_build_api_ge,1),yes)
$(error this target needs dpkg build API level 1)
endif

print-api:
	@printf 'build API level: %s\n' '$(DPKG_BUILD_API)'

Run this from a package tree whose control file declares level 1:

$ make print-api
build API level: 1

The helper function compares numeric values and returns yes when the current level is at least its argument. Do not call it when the command has failed or returned an empty value. That usually means the build is outside a source tree, the control file is unreadable, or an override is invalid.

7. Handle the failures that matter

• Output 0: no exact dpkg-build-api dependency was found, or the package intentionally remains at the legacy level.
• Conflicting versions: more than one build dependency field selected different exact levels. Resolve the metadata instead of choosing one in a script.
• Needs an exact version: constraints such as >= 1 or << 1 do not declare the API level. Use (= 1).
• Greater than max: the package requests an API level this installed dpkg does not support. Do not silence the error with an environment override.
• Unreadable control file: check the current directory or pass the intended file with -cFILE. The command does not guess another control file.

No undo is needed for the read-only commands. If you added a dependency while testing, revert that metadata change with your normal version-control operation after reviewing the diff. Do not delete a package tree or rewrite a release control file just to make the query return a preferred number.