DH_ASSISTANT(1) Debhelper DH_ASSISTANT(1)
NAME
dh_assistant - tool for supporting debhelper tools and provide
introspection
SYNOPSIS
dh_assistant command [additional options]
DESCRIPTION
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).
COMMANDS
The dh_assistant supports the following commands:
active-compat-level (JSON)
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:
active-compat-level
The compat level that debhelper will be using. This is the same as
DH_COMPAT when present or else declared-compat-level. This can be
null when no compat level can be detected.
declared-compat-level
The compat level that the package declared as its default compat
level. This can be null if the package does not declare any compat
level at all.
declared-compat-level-source
Defines how the compat level was declared. This is null (for the
same reason as declared-compat-level) or one of:
debian/compat
The compatibility level was declared in the first line
debian/compat file.
Build-Depends: debhelper-compat (= <C>)
The compatibility was declared in the debian/control via a
build dependency on the debhelper-compat (= <C>) package in the
Build-Depends field. In the output, the C is replaced by the
actual compatibility level. A full example value would be:
Build-Depends: debhelper-compat (= 13)
supported-compat-levels (JSON, CRFA)
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.
which-build-system (JSON)
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 key build-system is the build system that would be used by
debhelper for the given step (with the given options, debhelper
compat level, environment variables and the given working
directory). When -S and --buildsystem are omitted, this is the
result of debhelper's auto-detection logic.
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).
• The build-directory and buildpath values serve different but
related purposes. The build-directory generally mirrors the
--builddirectory option where as buildpath is the output directory
that debhelper will use. Therefore the former will often be null
when --builddirectory has not been passed while the latter will
generally not be null (except when build-system is none).
• The dest-directory (--destdir) is undefined for all build steps
except the install build step (will be output as null or absent).
For the same reason, --destdir should only be passed for install
build step.
Note that if not specified, this value is currently null by
default.
• The parallel value is subject to DEB_BUILD_OPTIONS. Notably, if
that does not include the parallel keyword, then parallel field in
the output will always be 1.
• Most fields in the output can be null. Particular if there is no
build system is detected (or when --buildsystem=none).
Additionally, many of the fields can be null even if there is a
build system if the build system does not use/set/define that
variable.
detect-hook-targets (JSON)
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:
commands-not-in-path
This attribute lists all the commands related to hook targets,
which dh_assistant could not find in PATH. These are usually
caused by either the command not being installed on the system
where dh_assistant is run or by the command not existing at all.
If you are using this command to verify an hook target is present,
please double check that the command is spelled correctly.
hook-targets
List over hook targets found along with additional information
about them.
command
Attribute that lists which command this hook target is related
too.
target-name
The actual target name detected in the debian/rules file.
is-empty
A boolean that determines whether dh(1) will optimize the hook
out at runtime (see "Completely empty targets" in dh(1)). Note
that empty override targets will still cause dh(1) to skip the
original command.
package-section-param
This attribute defines what package selection parameter should
be passed to dh_* commands used in the hook target. It can
either be -a, -i or (if no parameter should be used) "null".
This command accepts no options or arguments.
log-installed-files
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:
• No glob or substitution expansion is done by dh_assistant on the
provided paths. If you want to use globs, have the shell perform
the expansion first.
• Paths must be given as relative to the source root directory (e.g.,
debian/tmp/...)
• You can provide a directory. If you do, the directory and anything
recursively below it will be considered as installed. Note that it
is fine to provide the directory even if paths inside of it has
been excluded as long as the directory is fully "covered".
• Do not worry about providing the same filename twice in different
invocations to dh_assistant due to -arch / -indep overrides. While
it will be recorded multiple internally, dh_missing(1) will
deduplicate when it parses the records.
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).
COMMAND TAGS
Most commands have one or more of the following "tags" associated with
them. Their meaning is defined here.
JSON
The command provides JSON output. See "JSON OUTPUT" for details.
CRFA
Mnemonic "Can be Run From Anywhere"
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.
JSON OUTPUT
Most commands uses JSON format as output. Consumers need to be aware
that:
• Additional keys may be added at any time. For backwards
compatibility, the absence of a key should in general be
interpreted as null unless another default is documented or would
be "obvious" for that case.
• Many keys can be null/undefined in special cases. As an example,
some information may be unavailable when this command is run
directly from the debhelper source (git repository).
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
SEE ALSO
debhelper(7)
This program is a part of debhelper.
13.11.4 2023-01-02 DH_ASSISTANT(1)
Generated by dwww version 1.15 on Thu Jun 20 14:08:26 CEST 2024.