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:
- 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)
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 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.
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.
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).
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.
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
debhelper(7)
This program is a part of debhelper.