1DH_ASSISTANT(1)                    Debhelper                   DH_ASSISTANT(1)
2
3
4

NAME

6       dh_assistant - tool for supporting debhelper tools and provide
7       introspection
8

SYNOPSIS

10       dh_assistant command [additional options]
11

DESCRIPTION

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

COMMANDS

19       The dh_assistant supports the following commands:
20
21   active-compat-level (JSON)
22       Synopsis: dh_assistant active-compat-level
23
24       Outputs information about which compat level the package is using.
25
26       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
31       The returned JSON dictionary contains the following key-value pairs:
32
33       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
38       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
43       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
47           debian/compat
48               The compatibility level was declared in the first line
49               debian/compat file.
50
51           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
57                  Build-Depends: debhelper-compat (= 13)
58
59   supported-compat-levels (JSON, CRFA)
60       Synopsis: dh_assistant supported-compat-levels
61
62       Outputs information about which compat levels, this build of debhelper
63       knows about.
64
65       This command accepts no options or arguments.
66
67   which-build-system (JSON)
68       Synopsis: dh_assistant which-build-system [build step]
69       [build system options]
70
71       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
79       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
87       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
94       Things that are useful to know about the output:
95
96       •   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
102           The value is valid as a parameter for the --buildsystem option.
103
104           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
109           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
116       •   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
123       •   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
128           Note that if not specified, this value is currently null by
129           default.
130
131       •   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
135       •   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
141   detect-hook-targets (JSON)
142       Synopsis: dh_assistant detect-hook-targets
143
144       Detects possible override targets and hook targets that dh(1) might use
145       (provided that the relevant command is in the sequence).
146
147       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
152       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
161       The output looks something like this:
162
163           {
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
183       In more details:
184
185       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
191           If you are using this command to verify an hook target is present,
192           please double check that the command is spelled correctly.
193
194       hook-targets
195           List over hook targets found along with additional information
196           about them.
197
198           command
199               Attribute that lists which command this hook target is related
200               too.
201
202           target-name
203               The actual target name detected in the debian/rules file.
204
205           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
211           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
216       This command accepts no options or arguments.
217
218   log-installed-files
219       Synopsis: dh_assistant -ppkg [--on-behalf-of-cmd=dh_foo] path ...
220
221       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
225       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
230       Please keep in mind that:
231
232No 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
236       •   Paths must be given as relative to the source root directory (e.g.,
237           debian/tmp/...)
238
239       •   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
244       •   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
249       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

COMMAND TAGS

254       Most commands have one or more of the following "tags" associated with
255       them.  Their meaning is defined here.
256
257       JSON
258           The command provides JSON output. See "JSON OUTPUT" for details.
259
260       CRFA
261           Mnemonic "Can be Run From Anywhere"
262
263           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

JSON OUTPUT

270       Most commands uses JSON format as output.  Consumers need to be aware
271       that:
272
273       •   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
278       •   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
282       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
286            dh_assistant supported-compat-levels | json_pp | less
287

SEE ALSO

289       debhelper(7)
290
291       This program is a part of debhelper.
292
293
294
29513.11.4                           2023-01-22                   DH_ASSISTANT(1)
Impressum