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-levels
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 COMMAND TAGS
142 Most commands have one or more of the following "tags" associated with
143 them. Their meaning is defined here.
144 JSON
146 The command provides JSON output. See "JSON OUTPUT" for details.
147 CRFA
149 Mnemonic "Can be Run From Anywhere"
150 Most commands must be run inside a source package root directory (a
152 directory containing debian/control) because debhelper will need
153 the package metadata to lookup the information. Any command with
154 this tag are exempt from this requirement and is expected to work
155 regardless of where they are run.
156
158 Most commands uses JSON format as output. Consumers need to be aware
159 that:
160 • Additional keys may be added at any time. For backwards
162 compatibility, the absence of a key should in general be
163 interpreted as null unless another default is documented or would
164 be "obvious" for that case.
165 • Many keys can be null/undefined in special cases. As an example,
167 some information may be unavailable when this command is run
168 directly from the debhelper source (git repository).
169 The output will be prettified when stdout is detected as a terminal.
171 If you need to pipe the output to a pager/file (etc.) and still want it
172 prettified, please use an external JSON formatter. An example of this:
173 dh_assistant supported-compat-levels | python3 -m json.tool | less
175
177 debhelper(7)
178 This program is a part of debhelper.
18013.7.1 2022-04-22 DH_ASSISTANT(1)