DH_BUILTUSING(1)

NAME
dh_builtusing - set dpkg-gencontrol substitution variables for the Built-Using field

SYNOPSIS
dh_builtusing [debhelper options]

DESCRIPTION
The dh_builtusing tool belongs to the debhelper collection. It defines dpkg-gencontrol substitutions variables useful in the Built-Using fields of the control file.

Each item in such fields is the source package of a build dependency, with an exact (=) restriction to the version used during the build. This version is not known in advance, and must be passed to dpkg-gencontrol via substitution variables.

dh_builtusing searches the Built-Using or Static-Built-Using fields of each binary package in the source control file for substitution of variables named dh-builtusing:pattern, looks for pattern in the Build-Depends fields, deduces the source package and version, then defines the variable accordingly in debian/package.substvars.

It is enabled when the Build-Depends field, or a more specific Build-Depends-Arch or Build-Depends-Indep variant, mentions the dh-sequence-builtusing virtual package.

OPTIONS
Common debhelper command line options and environment variables are recognized. In particular, dh_builtusing only defines variables for the packages selected by options like -a, -I and -p.

--logorrheic
    Intensively --verbose.

PATTERN SYNTAX

  Character encoding
In order to ensure a one-to-one correspondence between dependency names and substitution variables, the dot chararcter (.) and the plus character (+) characters are respectively encoded as D and P.

For example, the dh-builtusing:gPP variable refers to the g++ dependency.

  Architecture qualifier
Architecture qualifiers in patterns are deprecated. Coinstallable packages have the same source and version.

  Wildcards
It may not be convenient that the variable name in Built-Using duplicates the full name in Build-Depends. For example, when the name contains a version, the maintainer may not want to manually update both fields.

For such situations, the S character is allowed in pattern, and matches any sequence of characters in the name of a build-dependency, like the star character (*) in glob patterns or the .* in regular expressions.

The wildcard may select multiple installed packages, but an error is reported if there is no match at all.

For example, the dh-builtusing:gcc-S-source variable may refer to either gcc-12-source, or gcc-13-source, or both.

ARCHITECTURE AND PROFILE RESTRICTIONS
A dependency may be disabled by architecture or build profile restrictions, in which case the version does not matter, or can even not be computed if the dependency is not installed. However, the expansion must result in a syntactically valid control file.

If an architecture or build profile restriction follows a detected variable substitution and is not satisfied in the current context, dh_builtusing sets the variable to disabled-by-restriction (= 0).

For example, ${dh-builtusing:libc6} [amd64] expands as libc6 (= VERSION) [amd64] when the host architecture matches, else as disabled-by-restriction (= 0) [amd64].

DEBHELPER INTEGRATION

  DH SEQUENCER
The details described here should rarely be needed.

The dh-sequence-builtusing virtual package in the Build-Depends field (or a variant) is equivalent to the dh-builtusing concrete package, except that the --with=builtusing option is implicitly passed to dh.

The --with=builtusing option has the same effect than an execute_before_dh_gencontrol target invoking dh_builtusing.

When debugging, it may be convenient to define an override_dh_builtusing target invoking dh_builtusing with the -v option.

BUGS AND LIMITATIONS
When a Build-Depends field contains an alternative (|), both options may match.

EXAMPLE
If debian/control contains

  Source: foo
  Build-Depends-Arch: dh-sequence-builtusing, gcc-12-source

  Package: bar
  Architecture: any
  Built-Using: ${dh-builtusing:gcc-S-source}

then the dependency on dh-sequence-builtusing has the same effect than this construct in debian/rules.

  gcc_major = ...
  format = $${source:Package} (= $${source:Version})
  value != dpkg-query -Wf'$(format)' gcc-$(gcc_major)-source
  override_dh_gencontrol-arch:
        dh_gencontrol -a -- -Vdh-builtusing:gcc-S-source='$(value)'

SEE ALSO
debhelper(7), dh_gencontrol(1), deb-substvars(5)

AUTHOR
Nicolas Boulenguez <nicolas@debian.org>