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 supported-compat-levels (JSON, CRFA)
22 Synopsis: dh_assistant supported-compat-levels
23 Outputs information about which compat levels, this build of
25 debhelper knows about.
26 This command accepts no options or arguments.
28 which-build-system (JSON)
30 Synopsis: dh_assistant which-build-system [[build step]]
31 [build system options]
32 Output information about which build system would be used for a
34 particular build step. The build step must be one of configure,
35 build, test, install or clean and must be the first argument after
36 which-build-system when provided. If omitted, it defaults to
37 configure as it is the most reliable step to use auto-detection on
38 in a clean source directory. Note that build steps do not always
39 agree when using auto-detection - particularly if the configure
40 step has not been run.
41 Additionally, the clean step can also provide "surprising" results
43 for builds that rely on a separate build directory. In such cases,
44 debhelper will return the first build system that uses a separate
45 build directory rather than the one build system that configure
46 would detect. This is generally a cosmetic issue as both build
47 systems are all basically a glorified rm -fr builddir and more
48 precise detection is functionally irrelevant as far as debhelper is
49 concerned.
50 The option accepts all debhelper build system arguments - i.e.,
52 options you can pass to all of the dh_auto_* commands plus (for the
53 install step) the --destdir option. These options affect the
54 output and auto-detection in various ways. Passing -S or
55 --buildsystem overrides the auto-detection (as it does for
56 dh_auto_*) but it still provides introspection into the chosen
57 build system.
58 Things that are useful to know about the output:
60 • The key build-system is the build system that would be used by
62 debhelper for the given step (with the given options, debhelper
63 compat level, environment variables and the given working
64 directory). When -S and --buildsystem are omitted, this is the
65 result of debhelper's auto-detection logic.
66 The value is valid as a parameter for the --buildsystem option.
68 The special value none is used to denote that no build system
70 would be used. This value is not present in --list parameter
71 for the dh_auto_* commands, but since debhelper/12.9 the value
72 is accepted for the --buildsystem option.
73 Note that auto-detection is subject to limitations in regards
75 to third-party build systems. While debhelper does support
76 auto-detecting some third-party build systems, they must be
77 installed for the detection to work. If they are not
78 installed, the detection logic silently skips that build system
79 (often resulting in build-system being none in the output).
80 • The build-directory and buildpath values serve different but
82 related purposes. The build-directory generally mirrors the
83 --builddirectory option where as buildpath is the output
84 directory that debhelper will use. Therefore the former will
85 often be null when --builddirectory has not been passed while
86 the latter will generally not be null (except when build-system
87 is none).
88 • The dest-directory (--destdir) is undefined for all build steps
90 except the install build step (will be output as null or
91 absent). For the same reason, --destdir should only be passed
92 for install build step.
93 Note that if not specified, this value is current null by
95 default.
96 • The parallel value is subject to DEB_BUILD_OPTIONS. Notably,
98 if that does not include the parallel keyword, then parallel
99 field in the output will always be 1.
100 • Most fields in the output can be null. Particular if there is
102 no build system is detected (or when --buildsystem=none).
103 Additionally, many of the fields can be null even if there is a
104 build system if the build system does not use/set/define that
105 variable.
106 COMMAND TAGS
108 Most commands have one or more of the following "tags" associated with
109 them. Their meaning is defined here.
110 JSON
112 The command provides JSON output. See "JSON OUTPUT" for details.
113 CRFA
115 Mnemonic "Can be Run From Anywhere"
116 Most commands must be run inside a source package root directory (a
118 directory containing debian/control) because debhelper will need
119 the package metadata to lookup the information. Any command with
120 this tag are exempt from this requirement and is expected to work
121 regardless of where they are run.
122
124 Most commands uses JSON format as output. Consumers need to be aware
125 that:
126 • Additional keys may be added at any time. For backwards
128 compatibility, the absence of a key should in general be
129 interpreted as null unless another default is documented or would
130 be "obvious" for that case.
131 • Many keys can be null/undefined in special cases. As an example,
133 some information may be unavailable when this command is run
134 directly from the debhelper source (git repository).
135 The output will be prettified when stdout is detected as a terminal.
137 If you need to pipe the output to a pager/file (etc.) and still want it
138 prettified, please use an external JSON formatter. An example of this:
139 dh_assistant supported-compat-levels | python3 -m json.tool | less
141
143 debhelper(7)
144 This program is a part of debhelper.
14613.5.2 2021-11-02 DH_ASSISTANT(1)