NAME

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

SYNOPSIS

       dh_builtusing [debhelper options] [-c control]

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.

       -c control
           Read control instead of debian/control.

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 suffix
       The variable name may carry an architecture suffix, with the same meaning as in Build-
       Depends.

       For example, the dh-builtusing:libc6:amd64 variable may be used to disambiguate
       coinstallable variants.

   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 .* regular expressions.  An error is reported if there is not exactly one match.

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

ARCHITECTURE AND PROFILE RESTRICTIONS

       If an architecture or build profile restriction follows a detected variable substitution
       and is not satisfied in the current context, dh_builtusing will skip the variable.  This
       is good, as the dependency may be missing during some builds.

       For example, ${dh-builtusing:libc6} [amd64] only defines the variable on one specific
       architecture.

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.

   OTHER DEBHELPER TOOLS
       This part is only of interest for writers of other debhelper tools.

       Other debhelper tools define variables for the Built-Using field, that may refer to
       dependencies not explicitly listed in the Build-Depends field.  So that such tools may
       delegate the computation of the source version, dh_builtusing

       •   reads debian/package.substvars files, in addition to the main control file.

       •   searches all installed packages when no explicit build dependency is found.

       For example, dh_sphinxdoc may define sphinxdoc:Built-Using as
       dh-builtusing:libjs-sphinxdoc.

BUGS AND LIMITATIONS

       Optional assignments in substvars files (?=) are treated as normal assignments.

       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>