Ubuntu Manpage: dh_assistant - tool for supporting debhelper tools and provide introspection

Provided by: debhelper_13.14.1ubuntu5_all

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 (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.

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 (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 (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).

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 (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).

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"
]
}
]
}

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).

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.

filename
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... ]
],
"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.

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.

--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, determine the full list of commands could be used by this source package
and for each command used, then attempt to guess which "config files" these commands are interested in.

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, 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"
}
],
"file-type": "pkgfile",
"pkgfile": "autoreconf.before"
},
{
"commands": [
{
"command": "dh_installgsettings"
}
],
"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).

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: dh_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.

COMMAND TAGS

       Most commands have one or more of the following "tags" associated with them.  Their meaning is defined
       here.

       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.

           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.

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

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

COMMAND TAGS

JSON OUTPUT

SEE ALSO