dh_assistant(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | COMMAND TAGS | JSON OUTPUT | SEE ALSO | COLOPHON

DH_ASSISTANT(1)                 Debhelper                DH_ASSISTANT(1)

NAME         top

       dh_assistant - tool for supporting debhelper tools and provide
       introspection

SYNOPSIS         top

       dh_assistant command [additional options]

DESCRIPTION         top

       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         top

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

       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.

           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.

           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, 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         top

       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.

JSON OUTPUT         top

       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         top

       debhelper(7)

       This program is a part of debhelper.

COLOPHON         top

       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-
       [email protected]] If you have a bug report for this manual page,
       send it to [email protected].  This page was obtained from
       the project's upstream Git repository
       ⟨https://salsa.debian.org/debian/debhelper.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-09.)  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
       [email protected]

13.15.3                        2024-06-13                DH_ASSISTANT(1)

Pages that refer to this page: dh(1)debhelper(7)