dh_assistant

DH_ASSISTANT(1)                    Debhelper                   DH_ASSISTANT(1)

NAME
       dh_assistant - tool for supporting debhelper tools and provide
       introspection

SYNOPSIS
       dh_assistant command [additionaloptions]

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-levels

       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 [buildstep]
       [buildsystemoptions]

       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:

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

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

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

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

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

   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:

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

       o   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 | python3 -m json.tool | less

SEE ALSO
       debhelper(7)

       This program is a part of debhelper.

13.6ubuntu1                       2022-02-07                   DH_ASSISTANT(1)