|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | COMMAND TAGS | JSON OUTPUT | SEE ALSO | COLOPHON |
|
|
|
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:
active-compat-level (AJSON)
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.
X-DH-Compat: <C>
The compatibility was declared in the debian/control via a
the X-DH-Compat field. In the output, the C is replaced by
the actual compatibility level. A full example value
would be:
X-DH-Compat: 15
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 (= 15)
supported-compat-levels (AJSON, 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 (AJSON)
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 (EXEC, AJSON)
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).
**UNSAFE**: This command relies on the output of make. Even it its
dry-run mode, make may execute commands from debian/rules. Avoid
using on packages from untrusted sources, where you have not
reviewed the packaging for backdoors.
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,
"filename": "debian/rules",
"target-name": "override_dh_strip_nondeterminism"
},
{
"command": "dh_foo",
"is-empty": false,
"package-section-param": "-a",
"filename": "debian/rules",
"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".
filename
This attribute reports which file the target was found it.
In most cases, this will always be "debian/rules" though
in case of include files, the target could appear in an
include file. Note this attribute is not super reliable
as make(1) only reports it for targets with a "recipe"
(targets with commands inside them). When make does not
provide the filename, dh_assistant blindly assumes the
filename is "debian/rules" (as overrides via includes is
not a commonly used feature).
Note this accuracy of this attribute is limited about what
data dh_assistant can read out from the following command:
LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null
This command accepts no options or arguments.
detect-unknown-hook-targets (EXEC, AJSON, LINT)
Synopsis: dh_assistant detect-unknown-hook-targets
[--output-format=json] [command-options]
Detects unknown and possibly misspelled override targets and hook
targets in debian/rules that will most likely not be used by
dh(1).
**UNSAFE**: This command relies on the output of make. Even it its
dry-run mode, make may execute commands from debian/rules. Avoid
using on packages from untrusted sources, where you have not
reviewed the packaging for backdoors.
This command differs from detect-hook-targets subtly in the scope.
The detect-hook-targets will list all targets that looks like hook
targets whether they are applicable or not. This command show all
hook targets, for which a command cannot be found in any sequence.
Accordingly, this command is better for linting purposes whereas
detect-hook-targets is better if you want to know which hook
targets are present. All the limitations listed in
detect-hook-targets about scanning the rules file apply equally to
this command.
This command will attempt will attempt to load any sequence add-on
listed via build-dependencies and therefore these must be
installed. Additional modules can be passed via --with like with
dh(1) as needed.
This command will also need one of the following perl modules to
be available: Text::Levenshtein, Text::LevenshteinXS,
Text::Levenshtein::XS. The first one can be installed via apt
install libtext-levenshtein-perl.
The text output is intended for human consumption and should be
self-explanatory. Since it is not stable, it will not be
documented. The JSON output looks something like this:
{
"unknown-hook-targets": [
{
"target-name": "execute_before_dh_instlal",
"filename": "debian/rules",
"candidates": [
"execute_before_dh_install"
]
}
],
"hook-targets-for-disabled-commands": [
{
"filename": "debian/rules",
"target-name": "override_dh_builddeb",
"removed-by": "zz-debputy"
}
],
}
In more details:
unknown-hook-targets
List of all the unknown hook targets found along with
additional information about them.
target-name
The actual target name detected in the file (usually
debian/rules).
filename
This attribute reports which file the target was found it.
In most cases, this will always be "debian/rules" though
in case of include files, the target could appear in an
include file. Note this attribute is not super reliable
as make(1) only reports it for targets with a "recipe"
(targets with commands inside them). When make does not
provide the filename, dh_assistant blindly assumes the
filename is "debian/rules" (as overrides via includes is
not a commonly used feature).
Note this accuracy of this attribute is limited about what
data dh_assistant can read out from the following command:
LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null
candidates
When not null and not empty, each element in this list are
names for likely candidates for the "correct" name of this
target.
hook-targets-for-disabled-commands
List of known hook targets found related to disabled commands
along with additional information about them.
target-name
The actual target name detected in the file (usually
debian/rules).
filename
This attribute reports which file the target was found it.
In most cases, this will always be "debian/rules" though
in case of include files, the target could appear in an
include file. Note this attribute is not super reliable
as make(1) only reports it for targets with a "recipe"
(targets with commands inside them). When make does not
provide the filename, dh_assistant blindly assumes the
filename is "debian/rules" (as overrides via includes is
not a commonly used feature).
Note this accuracy of this attribute is limited about what
data dh_assistant can read out from the following command:
LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null
removed-by
If present, this denotes the dh add-on that removed the
command from the sequence (thereby disabling this command
for that package).
Note this field is not present in all cases. As an
example, as obsolete commands (such as dh_gconf) are not
part of any sequence by the time they are marked as
obsolete.
If you (as a consumer) need to know whether a command is
obsolete or the particular reason why a command was
disabled, please file a feature request to get that data.
The absence of removed-by is not guaranteed to imply the
command is obsolete.
issues
If present, then it is a list of one or more reasons why this
output is definitely incomplete. Each element in the list is
an object with the following keys:
issue
A key defining the issue. Currently, it is always
load-addon, which signals that dh_assistant could not load
the add-on listed in the addon key.
Parsers should assume new issue types may appear in the
future.
addon
If present, it defines the name of a dh sequence add-on
that is related to the failure.
This command accepts the following options:
--output-format=FORMAT
Request a certain type of output format. Valid values are text
or json.
The text format is intended for human consumption and may
change between versions without any regard for machine
consumption. If you want to use this command for machine
consumption, please use the JSON format.
--no-linter-exit-code, --linter-exit-code
These options control whether the command should exit with the
linter exit code (2) or not (0) when an unknown target is
found. By default, it uses the linter exit code when an
unknown target is found.
--with addon, --without addon
These options behave the same as the dh(1) options with the
same name.
list-commands (RJSON)
Synopsis: dh_assistant list-commands [--output-format=json]
[command-options]
Load all dh sequence add-ons and extract a full list of all
commands that will be invoked across all sequences. The command
makes no attempt to filter out commands that will not be run due
to override targets or due to certain sequences not being run (by
dh or at all).
As the command will attempt to load all plugins, they must be
installed.
The text output is intended for human consumption and should be
self-explanatory. Since it is not stable, it will not be
documented. The JSON output looks something like this:
{
"commands": [
{
"command": "dh_auto_build"
},
{
"command": "dh_auto_clean"
},
[... more commands listed here... ]
],
"removed-commands": [
{
"command": "dh_gconf"
},
]
"issues": [
{
"issue": "load-addon",
"addon": "foo"
}
]
}
commands
The top level key containing the list of all commands. Each
element in the list are an object and can have the following
keys:
command
The name of the command.
While most commands are resolved via PATH, a sequence
add-on could register a command via a full path (by
passing the path search). If so, the command provided in
this output will also use the full path.
disabled-commands
The top level key containing the list of all known commands
that have been disabled. Each element in the list are an
object and can have the following keys:
command
The name of the command.
While most commands are resolved via PATH, a sequence
add-on could register a command via a full path (by
passing the path search). If so, the command provided in
this output will also use the full path.
removed-by
If present, this denotes the dh add-on that removed the
command from the sequence (thereby disabling this command
for that package).
Note this field is not present in all cases. As an
example, as obsolete commands (such as dh_gconf) are not
part of any sequence by the time they are marked as
obsolete.
If you (as a consumer) need to know whether a command is
obsolete or the particular reason why a command was
disabled, please file a feature request to get that data.
The absence of removed-by is not guaranteed to imply the
command is obsolete.
issues
If present, then it is a list of one or more reasons why this
output is definitely incomplete. Each element in the list is
an object with the following keys:
issue
A key defining the issue. Currently, it is always
load-addon, which signals that dh_assistant could not load
the add-on listed in the addon key.
Parsers should assume new issue types may appear in the
future.
addon
If present, it defines the name of a dh sequence add-on
that is related to the failure.
This command accepts the following options:
--output-format=FORMAT
Request a certain type of output format. Valid values are text
or json.
The text format is intended for human consumption and may
change between versions without any regard for machine
consumption. If you want to use this command for machine
consumption, please use the JSON format.
--with addon, --without addon
These options behave the same as the dh(1) options with the
same name.
list-guessed-dh-config-files (AJSON)
Synopsis: dh_assistant list-guessed-dh-config-files
[command-options]
Load all dh sequence add-ons declaratively depended on, determine
the full list of commands could be relevant for this source
package and for each command used, then attempt to guess which
"config files" these commands are interested in.
The command will include config files for commands that are not
active with current add-ons, since the commands might be run
manually from hook targets.
Note this command only guesses "per command config files".
Standard global config files such as debian/control, debian/rules,
and debian/compat are not included in this output.
As the command name implies, the resulting output is not a full
list (and will never be). The dh_assistant tool have to derive
this from optional metadata that commands can choose to provide
and dh_assistant has no means to validate that this metadata is up
to date.
As the command will attempt to load all plugins referenced by the
package, they must be installed.
The text output is intended for human consumption and should be
self-explanatory. Since it is not stable, it will not be
documented. The JSON output looks something like this:
{
"config-files": [
{
"commands": [
{
"command": "dh_autoreconf_clean"
"is-active": true
}
],
"file-type": "pkgfile",
"pkgfile": "autoreconf.before"
},
{
"commands": [
{
"command": "dh_installgsettings"
"is-active": true
}
],
"file-type": "pkgfile",
"pkgfile": "gsettings-override"
},
# [ ... more entries here ...]
],
"issues": [
{
"issue": "load-addon",
"addon": "foo"
}
]
}
config-files
The top level key containing the list of all config-files.
Each element in the list are an object and can have the
following keys:
file-type
The type of config file detected. At the time of writing,
this will always be pkgfile. However, other values may
appear in the future.
The pkgfile key means that the config file is a debhelper
pkgfile (named after the pkgfile sub in
Debian::Debhelper::Dh_Lib that locates the file).
pkgfile
When file-type is pkgfile, this key defines the name stem
of the pkgfile. An example, this will be install for
dh_install(1)'s config file and docs for
dh_installdocs(1)'s config file.
When file-type is not pkgfile, then this key will be
absent.
Typically names for these files are:
debian/PKGFILE
debian/PACKAGE.PKGFILE
However, there are more variants caused by --name plus
architecture specific suffixes.
internal
This key may exist and any value for it is not
standardized. Use at own peril.
It used for document certain specific implementation
details such as bug compatibility and may change as the
situation changes.
commands
This key will be a list with each element in it being an
object with the following keys:
command
Name of the command that is interested in this config
file. Multiple commands can be interested in the same
config file. An example of this would be
dh_installinit, dh_installsystemd and
dh_installtmpfiles, which all reacts to (the now)
deprecated tmpfile pkgfile. In the particular case,
only one command reacts to the file for a given compat
level (but that information is not available to
dh_assistant and therefore is not available in this
output either).
is-active
A boolean that determines whether the command is
active with the loaded sequences. When false, the
command is known to debhelper, but it is not run
automatically via dh. The command might be explicitly
removed by a sequence, marked as obsolete or possibly
known to debhelper a command that would activate in a
different command level (than the one currently
active).
Note that commands that are not "active" can often
still be invoked manually from debian/rules via hook
targets. Therefore, this reflects whether dh would
call the command directly or provide its standard hook
targets for the command.
removed-by
If present, this denotes the dh add-on that removed
the command from the sequence (thereby disabling this
command for that package).
Note this field is not present in all cases even when
is-active is true. As an example, as obsolete commands
(such as dh_gconf) are not part of any sequence by the
time they are marked as obsolete.
If you (as a consumer) need to know whether a command
is obsolete or the particular reason why a command was
disabled, please file a feature request to get that
data. The absence of removed-by plus is-active being
false is not guaranteed to imply the command is
obsolete.
issues
If present, then it is a list of one or more reasons why this
output is definitely incomplete. Each element in the list is
an object with the following keys:
issue
A key defining the issue. Currently, it is always
load-addon, which signals that dh_assistant could not load
the add-on listed in the addon key.
Parsers should assume new issue types may appear in the
future.
addon
If present, it defines the name of a dh sequence add-on
that is related to the failure.
This command accepts the following options:
--with addon, --without addon
These options behave the same as the dh(1) options with the
same name.
log-installed-files (BLD)
Synopsis: [1mdh_assistant log-installed-files -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).
restore-file-on-clean (BLD)
Synopsis: dh_assistant restore-file-on-clean FILE ...
This command will take a backup of listed files and tell
dh_clean(1) to restore them when it runs.
Note that generally you do not need to restore modified files on
clean. Often you can get away with just removing them if they are
regenerated anyway (which is the most common case for files being
modified during builds). Use this command when something taints a
file and the build does not cope with the file being removed.
The file is stored in debian/.debhelper. If you remove this
directory manually without calling dh_clean(1) then your
dh_assistant provided backup is gone permanently and the restore
will never occur. At this point, only a version control system or
another backup can restore the files.
The command has the following limitations:
No thread-safety - concurrency will corrupt the restore
The command relies on updating an internal index and
concurrent writes will cause it to be corrupt.
While most dh_* commands does not use the underlying function,
any of them could do so. Avoid running another dh_* command
while dh_assistant processes this command (especially running
multiple concurrent instances of dh_assistant
restore-file-on-clean is asking for corruption!).
Files only, not directories nor symlinks to files
This command will only restore files; not directories or
symlinks to files. It will reject any non-files.
Additionally, if the directory containing the file is removed,
the restore will fail (as debhelper does not track the
directory, it cannot restore it reliably). If this happens,
you can do a mkdir to restore the directory and run
dh_clean(1) again to get the files back. After that, consider
what went wrong and whether you are using the correct tool(s).
Strict file names
All filenames must be relative to the package root (without
using the ./ prefix). No hidden files (that is any file
starting with a period .) and no version control directories
(such as CVS). The checks are best effort.
These checks are here to ensure you do not accidentally trash
important data that would help you undo mistakes.
Heavy duty
The command takes a full copy of all files you pass it. This
is fine for a handful of small files, which is the intended
use-case. If you find yourself passing 10+ files or very large
files, you might be applying a sledgehammer where you needed a
different tool.
supports (CFFA)
Synopsis: dh_assistant supports COMMAND
This command is a scripting aid to programmatically determine
whether dh_assistant knows about a given subcommand. Pass the name
of a subcommand and this command will exit successfully if the
subcommand was known and unsuccessfully otherwise.
Most commands have one or more of the following "tags" associated
with them. Their meaning is defined here.
EXEC
This command will or may execute content from the package. Do
not run on untrusted packages.
Note: This tag only applies if the command will out of the box
be unsafe. As an example, commands that parse the output of
make is inherently unsafe, because it is trivial make to have
make run code even in --dry-run mode. As a counter example,
commands that only loads dh add-ons will be considered safe,
because PERL5LIB is assumed to be curated to only include
trusted plugins.
AJSON
The command always provides JSON output. See "JSON OUTPUT" for
details.
OJSON
The command *can* provide JSON output via
--output-format=json, but does not do so by default. See "JSON
OUTPUT" for details when using --output-format=json.
LINT
The command is or can be used for linting purposes. This
command will exit with code 2 when an important issue is
found. Be careful if the command is also tagged with EXEC.
When this happens, the command should only be used on trusted
content (see the EXEC tag for details).
Note that commands may have options that redefine what is
considered an "important" issue.
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.
BLD The command is intended to be used as a part of a package
build. It may leave artifacts behind that will need a
dh_clean(1) invocation to remove.
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.
This page is part of the debhelper (helper programs for
debian/rules) project. Information about the project can be found
at [unknown -- if you know, please contact man-pages@man7.org] If
you have a bug report for this manual page, send it to
submit@bugs.debian.org. This page was obtained from the project's
upstream Git repository
⟨https://salsa.debian.org/debian/debhelper.git⟩ on 2025-02-02.
(At that time, the date of the most recent commit that was found
in the repository was 2025-01-19.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
13.23 2025-01-02 DH_ASSISTANT(1)
Pages that refer to this page: dh(1), debhelper(7)
|
HTML rendering created 2025-02-02 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|