1DH_ASSISTANT(1) Debhelper DH_ASSISTANT(1)
2
6 dh_assistant - tool for supporting debhelper tools and provide
7 introspection
8
10 dh_assistant command [additional options]
11
13 dh_assistant is a debhelper program that provides introspection into
14 the debhelper stack to assist third-party tools (e.g. linters) or
15 third-party debhelper implementations not using the debhelper script
16 API (e.g., because they are not written in Perl).
17
19 The dh_assistant supports the following commands:
20 active-compat-level (JSON)
22 Synopsis: dh_assistant active-compat-level
23 Outputs information about which compat level the package is using.
25 For packages without valid debhelper compatibility information (whether
27 missing, ambiguous, not supported or simply invalid), this command
28 operates on a "best effort" basis and may abort when error instead of
29 providing data.
30 The returned JSON dictionary contains the following key-value pairs:
32 active-compat-level
34 The compat level that debhelper will be using. This is the same as
35 DH_COMPAT when present or else declared-compat-level. This can be
36 null when no compat level can be detected.
37 declared-compat-level
39 The compat level that the package declared as its default compat
40 level. This can be null if the package does not declare any compat
41 level at all.
42 declared-compat-level-source
44 Defines how the compat level was declared. This is null (for the
45 same reason as declared-compat-level) or one of:
46 debian/compat
48 The compatibility level was declared in the first line
49 debian/compat file.
50 Build-Depends: debhelper-compat (= <C>)
52 The compatibility was declared in the debian/control via a
53 build dependency on the debhelper-compat (= <C>) package in the
54 Build-Depends field. In the output, the C is replaced by the
55 actual compatibility level. A full example value would be:
56 Build-Depends: debhelper-compat (= 13)
58 supported-compat-levels (JSON, CRFA)
60 Synopsis: dh_assistant supported-compat-levels
61 Outputs information about which compat levels, this build of debhelper
63 knows about.
64 This command accepts no options or arguments.
66 which-build-system (JSON)
68 Synopsis: dh_assistant which-build-system [build step]
69 [build system options]
70 Output information about which build system would be used for a
72 particular build step. The build step must be one of configure, build,
73 test, install or clean and must be the first argument after which-
74 build-system when provided. If omitted, it defaults to configure as it
75 is the most reliable step to use auto-detection on in a clean source
76 directory. Note that build steps do not always agree when using auto-
77 detection - particularly if the configure step has not been run.
78 Additionally, the clean step can also provide "surprising" results for
80 builds that rely on a separate build directory. In such cases,
81 debhelper will return the first build system that uses a separate build
82 directory rather than the one build system that configure would detect.
83 This is generally a cosmetic issue as both build systems are all
84 basically a glorified rm -fr builddir and more precise detection is
85 functionally irrelevant as far as debhelper is concerned.
86 The option accepts all debhelper build system arguments - i.e., options
88 you can pass to all of the dh_auto_* commands plus (for the install
89 step) the --destdir option. These options affect the output and auto-
90 detection in various ways. Passing -S or --buildsystem overrides the
91 auto-detection (as it does for dh_auto_*) but it still provides
92 introspection into the chosen build system.
93 Things that are useful to know about the output:
95 • The key build-system is the build system that would be used by
97 debhelper for the given step (with the given options, debhelper
98 compat level, environment variables and the given working
99 directory). When -S and --buildsystem are omitted, this is the
100 result of debhelper's auto-detection logic.
101 The value is valid as a parameter for the --buildsystem option.
103 The special value none is used to denote that no build system would
105 be used. This value is not present in --list parameter for the
106 dh_auto_* commands, but since debhelper/12.9 the value is accepted
107 for the --buildsystem option.
108 Note that auto-detection is subject to limitations in regards to
110 third-party build systems. While debhelper does support auto-
111 detecting some third-party build systems, they must be installed
112 for the detection to work. If they are not installed, the
113 detection logic silently skips that build system (often resulting
114 in build-system being none in the output).
115 • The build-directory and buildpath values serve different but
117 related purposes. The build-directory generally mirrors the
118 --builddirectory option where as buildpath is the output directory
119 that debhelper will use. Therefore the former will often be null
120 when --builddirectory has not been passed while the latter will
121 generally not be null (except when build-system is none).
122 • The dest-directory (--destdir) is undefined for all build steps
124 except the install build step (will be output as null or absent).
125 For the same reason, --destdir should only be passed for install
126 build step.
127 Note that if not specified, this value is currently null by
129 default.
130 • The parallel value is subject to DEB_BUILD_OPTIONS. Notably, if
132 that does not include the parallel keyword, then parallel field in
133 the output will always be 1.
134 • Most fields in the output can be null. Particular if there is no
136 build system is detected (or when --buildsystem=none).
137 Additionally, many of the fields can be null even if there is a
138 build system if the build system does not use/set/define that
139 variable.
140 detect-hook-targets (JSON)
142 Synopsis: dh_assistant detect-hook-targets
143 Detects possible override targets and hook targets that dh(1) might use
145 (provided that the relevant command is in the sequence).
146 The detection is based on scanning the rules file for any target that
148 might look like a hook target and can therefore list targets that are
149 in fact not hook targets (or are but will never be triggered for other
150 reasons).
151 The detection uses a similar logic for scanning the rules file and is
153 therefore subject to makefile conditionals (i.e., the truth value of
154 makefile conditionals can change whether a hook target is visible in
155 the output of this command). In theory, you would have to setup up the
156 environment to look like it would during a build for getting the most
157 accurate output. Though, a lot of packages will not have conditional
158 hook targets, so the "out of the box" behaviour will work well in most
159 cases.
160 The output looks something like this:
162 {
164 "commands-not-in-path": [
165 "dh_foo"
166 ],
167 "hook-targets": [
168 {
169 "command": "dh_strip_nondeterminism",
170 "is-empty": true,
171 "package-section-param": null,
172 "target-name": "override_dh_strip_nondeterminism"
173 },
174 {
175 "command": "dh_foo",
176 "is-empty": false,
177 "package-section-param": "-a",
178 "target-name": "override_dh_foo-arch"
179 }
180 ]
181 }
182 In more details:
184 commands-not-in-path
186 This attribute lists all the commands related to hook targets,
187 which dh_assistant could not find in PATH. These are usually
188 caused by either the command not being installed on the system
189 where dh_assistant is run or by the command not existing at all.
190 If you are using this command to verify an hook target is present,
192 please double check that the command is spelled correctly.
193 hook-targets
195 List over hook targets found along with additional information
196 about them.
197 command
199 Attribute that lists which command this hook target is related
200 too.
201 target-name
203 The actual target name detected in the debian/rules file.
204 is-empty
206 A boolean that determines whether dh(1) will optimize the hook
207 out at runtime (see "Completely empty targets" in dh(1)). Note
208 that empty override targets will still cause dh(1) to skip the
209 original command.
210 package-section-param
212 This attribute defines what package selection parameter should
213 be passed to dh_* commands used in the hook target. It can
214 either be -a, -i or (if no parameter should be used) "null".
215 This command accepts no options or arguments.
217 log-installed-files
219 Synopsis: dh_assistant -ppkg [--on-behalf-of-cmd=dh_foo] path ...
220 Mark one or more paths as installed for a given package. This is
222 useful for telling dh_missing(1) that the paths have been installed
223 manually.
224 The --on-behalf-of-cmd option can be used by third-party tools to have
226 dh_assistant list them as the installer of the provided paths. The
227 convention is to use the basename of the tool itself as its name (e.g.
228 dh_install).
229 Please keep in mind that:
231 • No glob or substitution expansion is done by dh_assistant on the
233 provided paths. If you want to use globs, have the shell perform
234 the expansion first.
235 • Paths must be given as relative to the source root directory (e.g.,
237 debian/tmp/...)
238 • You can provide a directory. If you do, the directory and anything
240 recursively below it will be considered as installed. Note that it
241 is fine to provide the directory even if paths inside of it has
242 been excluded as long as the directory is fully "covered".
243 • Do not worry about providing the same filename twice in different
245 invocations to dh_assistant due to -arch / -indep overrides. While
246 it will be recorded multiple internally, dh_missing(1) will
247 deduplicate when it parses the records.
248 Note this command only marks paths as installed. It does not actually
250 install them - the caller should ensure that the paths are in fact
251 handled (or installed).
252
254 Most commands have one or more of the following "tags" associated with
255 them. Their meaning is defined here.
256 JSON
258 The command provides JSON output. See "JSON OUTPUT" for details.
259 CRFA
261 Mnemonic "Can be Run From Anywhere"
262 Most commands must be run inside a source package root directory (a
264 directory containing debian/control) because debhelper will need
265 the package metadata to lookup the information. Any command with
266 this tag are exempt from this requirement and is expected to work
267 regardless of where they are run.
268
270 Most commands uses JSON format as output. Consumers need to be aware
271 that:
272 • Additional keys may be added at any time. For backwards
274 compatibility, the absence of a key should in general be
275 interpreted as null unless another default is documented or would
276 be "obvious" for that case.
277 • Many keys can be null/undefined in special cases. As an example,
279 some information may be unavailable when this command is run
280 directly from the debhelper source (git repository).
281 The output will be prettified when stdout is detected as a terminal.
283 If you need to pipe the output to a pager/file (etc.) and still want it
284 prettified, please use an external JSON formatter. An example of this:
285 dh_assistant supported-compat-levels | json_pp | less
287
289 debhelper(7)
290 This program is a part of debhelper.
29213.11.4 2023-01-22 DH_ASSISTANT(1)