---
name: "dh_builtusing"
section: "1"
platform: "linux"
package: "dh-builtusing"
version: "0.0.7"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/dh_builtusing"
---

# dh\_builtusing(1)

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

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

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)](/debhelper/7.md), [**dh\_gencontrol**(1)](/dh_gencontrol/1.md), [**deb-substvars**(5)](/deb-substvars/5.md)

## AUTHOR

Nicolas Boulenguez \<nicolas@debian.org\>