1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
=head1 NAME
dh_builtusing - set dpkg-gencontrol substitution variables for the Built-Using field
=head1 SYNOPSIS
B<dh_builtusing> [S<I<debhelper options>>] [B<-c> I<control>]
=head1 DESCRIPTION
The B<dh_builtusing> tool belongs to the debhelper collection.
It defines B<dpkg-gencontrol> substitutions variables useful in the
B<Built-Using> fields of the control file.
Each item in such fields is the source package of a build dependency,
with an exact (B<=>) restriction to the version used during the build.
This version is not known in advance, and must be passed to
B<dpkg-gencontrol> via substitution variables.
B<dh_builtusing> searches the B<Built-Using> or B<Static-Built-Using>
fields of each binary I<package> in the source control file for
substitution of variables named B<dh-builtusing:>I<pattern>,
looks for I<pattern> in the B<Build-Depends> fields,
deduces the source package and version,
then defines the variable accordingly in B<debian/>I<package>B<.substvars>.
It is enabled when the B<Build-Depends> field, or a more specific
B<Build-Depends-Arch> or B<Build-Depends-Indep> variant, mentions the
B<dh-sequence-builtusing> virtual package.
=head1 OPTIONS
Common debhelper command line options and environment variables are
recognized.
In particular, B<dh_builtusing> only defines variables for the
packages selected by options like B<-a>, B<-I> and B<-p>.
=over 4
=item B<-c> I<control>
Read I<control> instead of B<debian/control>.
=item B<--logorrheic>
Intensively B<--verbose>.
=back
=head1 PATTERN SYNTAX
=head2 Character encoding
In order to ensure a one-to-one correspondence between dependency
names and substitution variables, the dot chararcter (B<.>) and the
plus character (B<+>) characters are respectively encoded as B<D> and
B<P>.
For example, the B<dh-builtusing:gPP> variable refers to the B<g++>
dependency.
=head2 Architecture suffix
The variable name may carry an architecture suffix, with the same
meaning as in B<Build-Depends>.
For example, the B<dh-builtusing:libc6:amd64> variable may be used to
disambiguate coinstallable variants.
=head2 Wildcards
It may not be convenient that the variable name in B<Built-Using>
duplicates the full name in B<Build-Depends>.
For example, when the name contains a version, the maintainer may not
want to manually update both fields.
For such situations, the B<S> character is allowed in I<pattern>, and
matches any sequence of characters in the name of a build-dependency,
like the star character (B<*>) in glob patterns or the B<.*> 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 B<dh-builtusing:gcc-S-source> variable may refer to
either B<gcc-12-source>, or B<gcc-13-source>, or both.
=head1 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,
B<dh_builtusing> sets the variable to
B<disabled-by-restriction (= 0)>.
For example, B<${dh-builtusing:libc6} [amd64]> expands as
B<libc6 (= >I<VERSION>B<) [amd64]>
when the host architecture matches, else as
B<disabled-by-restriction (= 0) [amd64]>.
=head1 DEBHELPER INTEGRATION
=head2 DH SEQUENCER
The details described here should rarely be needed.
The B<dh-sequence-builtusing> virtual package in the B<Build-Depends>
field (or a variant) is equivalent to the B<dh-builtusing> concrete
package, except that the B<--with=builtusing> option is implicitly
passed to B<dh>.
The B<--with=builtusing> option has the same effect than an
B<execute_before_dh_gencontrol> target invoking B<dh_builtusing>.
When debugging, it may be convenient to define an
B<override_dh_builtusing> target invoking B<dh_builtusing> with the
B<-v> option.
=head2 OTHER DEBHELPER TOOLS
This part is only of interest for writers of other debhelper tools.
Other debhelper tools define variables for the B<Built-Using> field,
that may refer to dependencies not explicitly listed in the
B<Build-Depends> field.
So that such tools may delegate the computation of the source version,
B<dh_builtusing>
=over 4
=item
reads B<debian/>I<package>B<.substvars> files, in addition to the main
control file.
=item
searches all installed packages when no explicit build dependency is
found.
=back
For example, B<dh_sphinxdoc> may define B<sphinxdoc:Built-Using> as
B<dh-builtusing:libjs-sphinxdoc>.
=head1 BUGS AND LIMITATIONS
Optional assignments in substvars files (B<?=>) are treated as normal
assignments.
When a B<Build-Depends> field contains an alternative (B<|>), both
options may match.
=head1 EXAMPLE
If B<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 B<dh-sequence-builtusing> has the same effect
than this construct in B<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)'
=head1 SEE ALSO
L<debhelper(7)>,
L<dh_gencontrol(1)>,
L<deb-substvars(5)>
=head1 AUTHOR
Nicolas Boulenguez <nicolas@debian.org>
|
