NAME

       dh_assistant - tool for supporting debhelper tools and provide introspection

SYNOPSIS

       dh_assistant command [additional options]

DESCRIPTION

       dh_assistant is a debhelper program that provides introspection into the debhelper stack
       to assist third-party tools (e.g. linters) or third-party debhelper implementations not
       using the debhelper script API (e.g., because they are not written in Perl).

COMMANDS

       The dh_assistant supports the following commands:

   active-compat-level (JSON)
       Synopsis: dh_assistant active-compat-level

       Outputs information about which compat level the package is using.

       For packages without valid debhelper compatibility information (whether missing,
       ambiguous, not supported or simply invalid), this command operates on a "best effort"
       basis and may abort when error instead of providing data.

       The returned JSON dictionary contains the following key-value pairs:

       active-compat-level
           The compat level that debhelper will be using.  This is the same as DH_COMPAT when
           present or else declared-compat-level.  This can be null when no compat level can be
           detected.

       declared-compat-level
           The compat level that the package declared as its default compat level.  This can be
           null if the package does not declare any compat level at all.

       declared-compat-level-source
           Defines how the compat level was declared.  This is null (for the same reason as
           declared-compat-level) or one of:

           debian/compat
               The compatibility level was declared in the first line debian/compat file.

           Build-Depends: debhelper-compat (= <C>)
               The compatibility was declared in the debian/control via a build dependency on the
               debhelper-compat (= <C>) package in the Build-Depends field.  In the output, the C
               is replaced by the actual compatibility level.  A full example value would be:

                  Build-Depends: debhelper-compat (= 13)

   supported-compat-levels (JSON, CRFA)
       Synopsis: dh_assistant supported-compat-levels

       Outputs information about which compat levels, this build of debhelper knows about.

       This command accepts no options or arguments.

   which-build-system (JSON)
       Synopsis: dh_assistant which-build-system [build step] [build system options]

       Output information about which build system would be used for a particular build step.
       The build step must be one of configure, build, test, install or clean and must be the
       first argument after which-build-system when provided.  If omitted, it defaults to
       configure as it is the most reliable step to use auto-detection on in a clean source
       directory.  Note that build steps do not always agree when using auto-detection -
       particularly if the configure step has not been run.

       Additionally, the clean step can also provide "surprising" results for builds that rely on
       a separate build directory.  In such cases, debhelper will return the first build system
       that uses a separate build directory rather than the one build system that configure would
       detect.  This is generally a cosmetic issue as both build systems are all basically a
       glorified rm -fr builddir and more precise detection is functionally irrelevant as far as
       debhelper is concerned.

       The option accepts all debhelper build system arguments - i.e., options you can pass to
       all of the dh_auto_* commands plus (for the install step) the --destdir option.  These
       options affect the output and auto-detection in various ways.  Passing -S or --buildsystem
       overrides the auto-detection (as it does for dh_auto_*) but it still provides
       introspection into the chosen build system.

       Things that are useful to know about the output:

       •   The key build-system is the build system that would be used by debhelper for the given
           step (with the given options, debhelper compat level, environment variables and the
           given working directory).  When -S and --buildsystem are omitted, this is the result
           of debhelper's auto-detection logic.

           The value is valid as a parameter for the --buildsystem option.

           The special value none is used to denote that no build system would be used.  This
           value is not present in --list parameter for the dh_auto_* commands, but since
           debhelper/12.9 the value is accepted for the --buildsystem option.

           Note that auto-detection is subject to limitations in regards to third-party build
           systems.  While debhelper does support auto-detecting some third-party build systems,
           they must be installed for the detection to work.  If they are not installed, the
           detection logic silently skips that build system (often resulting in build-system
           being none in the output).

       •   The build-directory and buildpath values serve different but related purposes.  The
           build-directory generally mirrors the --builddirectory option where as buildpath is
           the output directory that debhelper will use.  Therefore the former will often be null
           when --builddirectory has not been passed while the latter will generally not be null
           (except when build-system is none).

       •   The dest-directory (--destdir) is undefined for all build steps except the install
           build step (will be output as null or absent).  For the same reason, --destdir should
           only be passed for install build step.

           Note that if not specified, this value is currently null by default.

       •   The parallel value is subject to DEB_BUILD_OPTIONS.  Notably, if that does not include
           the parallel keyword, then parallel field in the output will always be 1.

       •   Most fields in the output can be null.  Particular if there is no build system is
           detected (or when --buildsystem=none).  Additionally, many of the fields can be null
           even if there is a build system if the build system does not use/set/define that
           variable.

   detect-hook-targets (JSON)
       Synopsis: dh_assistant detect-hook-targets

       Detects possible override targets and hook targets that dh(1) might use (provided that the
       relevant command is in the sequence).

       The detection is based on scanning the rules file for any target that might look like a
       hook target and can therefore list targets that are in fact not hook targets (or are but
       will never be triggered for other reasons).

       The detection uses a similar logic for scanning the rules file and is therefore subject to
       makefile conditionals (i.e., the truth value of makefile conditionals can change whether a
       hook target is visible in the output of this command).  In theory, you would have to setup
       up the environment to look like it would during a build for getting the most accurate
       output.  Though, a lot of packages will not have conditional hook targets, so the "out of
       the box" behaviour will work well in most cases.

       The output looks something like this:

           {
              "commands-not-in-path": [
                 "dh_foo"
              ],
              "hook-targets": [
                 {
                    "command": "dh_strip_nondeterminism",
                    "is-empty": true,
                    "package-section-param": null,
                    "target-name": "override_dh_strip_nondeterminism"
                 },
                 {
                    "command": "dh_foo",
                    "is-empty": false,
                    "package-section-param": "-a",
                    "target-name": "override_dh_foo-arch"
                 }
              ]
           }

       In more details:

       commands-not-in-path
           This attribute lists all the commands related to hook targets, which dh_assistant
           could not find in PATH.  These are usually caused by either the command not being
           installed on the system where dh_assistant is run or by the command not existing at
           all.

           If you are using this command to verify an hook target is present, please double check
           that the command is spelled correctly.

       hook-targets
           List over hook targets found along with additional information about them.

           command
               Attribute that lists which command this hook target is related too.

           target-name
               The actual target name detected in the debian/rules file.

           is-empty
               A boolean that determines whether dh(1) will optimize the hook out at runtime (see
               "Completely empty targets" in dh(1)). Note that empty override targets will still
               cause dh(1)  to skip the original command.

           package-section-param
               This attribute defines what package selection parameter should be passed to dh_*
               commands used in the hook target.  It can either be -a, -i or (if no parameter
               should be used) "null".

       This command accepts no options or arguments.

   log-installed-files
       Synopsis: dh_assistant -ppkg [--on-behalf-of-cmd=dh_foo] path ...

       Mark one or more paths as installed for a given package.  This is useful for telling
       dh_missing(1) that the paths have been installed manually.

       The --on-behalf-of-cmd option can be used by third-party tools to have dh_assistant list
       them as the installer of the provided paths.  The convention is to use the basename of the
       tool itself as its name (e.g. dh_install).

       Please keep in mind that:

       •   No glob or substitution expansion is done by dh_assistant on the provided paths.  If
           you want to use globs, have the shell perform the expansion first.

       •   Paths must be given as relative to the source root directory (e.g., debian/tmp/...)

       •   You can provide a directory.  If you do, the directory and anything recursively below
           it will be considered as installed.  Note that it is fine to provide the directory
           even if paths inside of it has been excluded as long as the directory is fully
           "covered".

       •   Do not worry about providing the same filename twice in different invocations to
           dh_assistant due to -arch / -indep overrides.  While it will be recorded multiple
           internally, dh_missing(1) will deduplicate when it parses the records.

       Note this command only marks paths as installed. It does not actually install them - the
       caller should ensure that the paths are in fact handled (or installed).

COMMAND TAGS

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

       JSON
           The command provides JSON output. See "JSON OUTPUT" for details.

       CRFA
           Mnemonic "Can be Run From Anywhere"

           Most commands must be run inside a source package root directory (a directory
           containing debian/control) because debhelper will need the package metadata to lookup
           the information.  Any command with this tag are exempt from this requirement and is
           expected to work regardless of where they are run.

JSON OUTPUT

       Most commands uses JSON format as output.  Consumers need to be aware that:

       •   Additional keys may be added at any time.  For backwards compatibility, the absence of
           a key should in general be interpreted as null unless another default is documented or
           would be "obvious" for that case.

       •   Many keys can be null/undefined in special cases.  As an example, some information may
           be unavailable when this command is run directly from the debhelper source (git
           repository).

       The output will be prettified when stdout is detected as a terminal.  If you need to pipe
       the output to a pager/file (etc.) and still want it prettified, please use an external
       JSON formatter. An example of this:

            dh_assistant supported-compat-levels | json_pp | less

SEE ALSO

       debhelper(7)

       This program is a part of debhelper.