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.

       --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 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 .* 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.

   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>

0.0.12                                             2025-10-29                                   DH_BUILTUSING(1)