DH_BUILTUSING(1)

📦
version 0.0.14 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 DH_BUILTUSING — ok bestie, let's talk Built-Using ✨

so like, this is a page from the Debhelper manual, section 1. the tool is called dh_builtusing and it sets those dpkg-gencontrol substitution variables for the Built-Using field. yes queen, it's giving build metadata realness. 👑

🌸 NAME 🌸

dh_builtusing — sets the dpkg-gencontrol substitution variables for the Built-Using field. that's it, that's the job, and it does it flawlessly. 💅

🦋 SYNOPSIS 🦋

dh_builtusing [debhelper options]

like every other debhelper child, it just wants your debhelper options and nothing else. low maintenance. icon behavior. ✨

🎀 DESCRIPTION 🎀

okay so dh_builtusing is part of the debhelper collection, and what it does is define dpkg-gencontrol substitution variables that are useful in the Built-Using fields of the control file.

now, every single item in one of those fields is the source package of a build dependency, with an exact (=) restriction to the version that got used during the build. and here's the plot twist: that version is not known in advance. it literally cannot be, bestie. so it has to be passed to dpkg-gencontrol through substitution variables. it's the only way. 🙈

so what dh_builtusing does is:

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

and when does it even turn on? it's 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. that's the vibe check that wakes it up. 🌈

💅 OPTIONS 💅

the common debhelper command line options and environment variables are recognized, obvi. and in particular: dh_builtusing only defines variables for the packages that get selected by options like -a, -I and -p. so pick your faves, bestie, it respects the selection. 🫶

  • --logorrheic — it's --verbose but intensively. like, turned all the way up. screaming. but in a helpful way. 🔥

⭐ PATTERN SYNTAX ⭐

🔤 Character encoding 🔤

so to make sure there's a one-to-one correspondence between dependency names and substitution variables, two characters get encoded:

  • the dot character (.) becomes D
  • the plus character (+) becomes P

for example, the dh-builtusing:gPP variable refers to the g++ dependency. see what they did there? + + → P P. iykyk. 😭

🏛️ Architecture qualifier 🏛️

architecture qualifiers in patterns are deprecated. do not use them, bestie. and the reason is actually super clean: coinstallable packages have the same source and version. so the qualifier was just doing nothing but vibes. 💀

🌟 Wildcards 🌟

okay so sometimes it's just not 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 is NOT about to manually update both fields every single time. that's a chore and we don't do chores. 🙅

so for those situations, the S character is allowed in a pattern, and it matches any sequence of characters in the name of a build-dependency — just 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. so like, zero matches = not it. ✋

for example, the dh-builtusing:gcc-S-source variable may refer to either gcc-12-source, or gcc-13-source, or both. it's flexible like that. slay. 💜

🧚 ARCHITECTURE AND PROFILE RESTRICTIONS 🧚

a dependency may be disabled by architecture or build profile restrictions, in which case the version does not matter — or it can even not be computed at all if the dependency isn't installed. but here's the rule that matters: the expansion must result in a syntactically valid control file. no exceptions, no shortcuts. 👑

so 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]. cute, right? conditional but make it control-file-legal. ✨

🍓 DEBHELPER INTEGRATION 🍓

🎵 DH SEQUENCER 🎵

the details described here should rarely be needed. so like, read it if you're curious, bestie, but you probably won't need it. 🫶

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. sneaky. convenient. iconic. 💅

and 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. main character debugging energy. 🔍

💀 BUGS AND LIMITATIONS 💀

when a Build-Depends field contains an alternative (|), both options may match. so like, watch out for that one. it's the one chaotic corner of this whole thing. 🫠

🌈 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)'

like, look at it. it just works. no cap. 🔥

👑 SEE ALSO 👑

go read those too, bestie, they're the whole friend group. 🫶

🌸 AUTHOR 🌸

Nicolas Boulenguez <nicolas@debian.org> — thank you for your service, legend. 🎀

and that's the whole page, babes. this version is 0.0.14, dated 2026-03-06, straight from the Debhelper source. mwah. 💖✨🎀

📦 where this page comes from