DH_ASSISTANT(1) | Debhelper | DH_ASSISTANT(1) |
dh_assistant - tool for supporting debhelper tools and provide introspection
dh_assistant command [additional options]
dh_assistant is a debhelper program that provides introspection into the debhelper stack to assist third-party tools (e.g. linters) or third-party debhelper implementations not using the debhelper script API (e.g., because they are not written in Perl).
The dh_assistant supports the following commands:
Synopsis: dh_assistant active-compat-level
Outputs information about which compat level the package is using.
For packages without valid debhelper compatibility information (whether missing, ambiguous, not supported or simply invalid), this command operates on a "best effort" basis and may abort when error instead of providing data.
The returned JSON dictionary contains the following key-value pairs:
Build-Depends: debhelper-compat (= 13)
Synopsis: dh_assistant supported-compat-levels
Outputs information about which compat levels, this build of debhelper knows about.
This command accepts no options or arguments.
Synopsis: dh_assistant which-build-system [build step] [build system options]
Output information about which build system would be used for a particular build step. The build step must be one of configure, build, test, install or clean and must be the first argument after which-build-system when provided. If omitted, it defaults to configure as it is the most reliable step to use auto-detection on in a clean source directory. Note that build steps do not always agree when using auto-detection - particularly if the configure step has not been run.
Additionally, the clean step can also provide "surprising" results for builds that rely on a separate build directory. In such cases, debhelper will return the first build system that uses a separate build directory rather than the one build system that configure would detect. This is generally a cosmetic issue as both build systems are all basically a glorified rm -fr builddir and more precise detection is functionally irrelevant as far as debhelper is concerned.
The option accepts all debhelper build system arguments - i.e., options you can pass to all of the dh_auto_* commands plus (for the install step) the --destdir option. These options affect the output and auto-detection in various ways. Passing -S or --buildsystem overrides the auto-detection (as it does for dh_auto_*) but it still provides introspection into the chosen build system.
Things that are useful to know about the output:
The value is valid as a parameter for the --buildsystem option.
The special value none is used to denote that no build system would be used. This value is not present in --list parameter for the dh_auto_* commands, but since debhelper/12.9 the value is accepted for the --buildsystem option.
Note that auto-detection is subject to limitations in regards to third-party build systems. While debhelper does support auto-detecting some third-party build systems, they must be installed for the detection to work. If they are not installed, the detection logic silently skips that build system (often resulting in build-system being none in the output).
Note that if not specified, this value is currently null by default.
Synopsis: dh_assistant detect-hook-targets
Detects possible override targets and hook targets that dh(1) might use (provided that the relevant command is in the sequence).
The detection is based on scanning the rules file for any target that might look like a hook target and can therefore list targets that are in fact not hook targets (or are but will never be triggered for other reasons).
The detection uses a similar logic for scanning the rules file and is therefore subject to makefile conditionals (i.e., the truth value of makefile conditionals can change whether a hook target is visible in the output of this command). In theory, you would have to setup up the environment to look like it would during a build for getting the most accurate output. Though, a lot of packages will not have conditional hook targets, so the "out of the box" behaviour will work well in most cases.
The output looks something like this:
{ "commands-not-in-path": [ "dh_foo" ], "hook-targets": [ { "command": "dh_strip_nondeterminism", "is-empty": true, "package-section-param": null, "target-name": "override_dh_strip_nondeterminism" }, { "command": "dh_foo", "is-empty": false, "package-section-param": "-a", "target-name": "override_dh_foo-arch" } ] }
In more details:
If you are using this command to verify an hook target is present, please double check that the command is spelled correctly.
This command accepts no options or arguments.
Synopsis: dh_assistant -ppkg [--on-behalf-of-cmd=dh_foo] path ...
Mark one or more paths as installed for a given package. This is useful for telling dh_missing(1) that the paths have been installed manually.
The --on-behalf-of-cmd option can be used by third-party tools to have dh_assistant list them as the installer of the provided paths. The convention is to use the basename of the tool itself as its name (e.g. dh_install).
Please keep in mind that:
Note this command only marks paths as installed. It does not actually install them - the caller should ensure that the paths are in fact handled (or installed).
Most commands have one or more of the following "tags" associated with them. Their meaning is defined here.
Most commands must be run inside a source package root directory (a directory containing debian/control) because debhelper will need the package metadata to lookup the information. Any command with this tag are exempt from this requirement and is expected to work regardless of where they are run.
Most commands uses JSON format as output. Consumers need to be aware that:
The output will be prettified when stdout is detected as a terminal. If you need to pipe the output to a pager/file (etc.) and still want it prettified, please use an external JSON formatter. An example of this:
dh_assistant supported-compat-levels | json_pp | less
This program is a part of debhelper.
2023-01-02 | 13.11.4 |