.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DH_ASSISTANT 1" .TH DH_ASSISTANT 1 "2022-11-26" "13.11.1~bpo11+1" "Debhelper" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" dh_assistant \- tool for supporting debhelper tools and provide introspection .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBdh_assistant\fR \fB\f(BIcommand\fB\fR [\fIadditional options\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBdh_assistant\fR 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 \s-1API\s0 (e.g., because they are not written in Perl). .SH "COMMANDS" .IX Header "COMMANDS" The \fBdh_assistant\fR supports the following commands: .SS "active-compat-level (\s-1JSON\s0)" .IX Subsection "active-compat-level (JSON)" \&\fBSynopsis\fR: \fBdh_assistant\fR \fBactive-compat-level\fR .PP Outputs information about which compat level the package is using. .PP For packages without valid debhelper compatibility information (whether missing, ambiguous, not supported or simply invalid), this command operates on a \*(L"best effort\*(R" basis and may abort when error instead of providing data. .PP The returned \s-1JSON\s0 dictionary contains the following key-value pairs: .IP "active-compat-level" 4 .IX Item "active-compat-level" The compat level that debhelper will be using. This is the same as \fB\s-1DH_COMPAT\s0\fR when present or else \fBdeclared-compat-level\fR. This can be \fBnull\fR when no compat level can be detected. .IP "declared-compat-level" 4 .IX Item "declared-compat-level" The compat level that the package declared as its default compat level. This can be \fBnull\fR if the package does not declare any compat level at all. .IP "declared-compat-level-source" 4 .IX Item "declared-compat-level-source" Defines how the compat level was declared. This is null (for the same reason as \&\fBdeclared-compat-level\fR) or one of: .RS 4 .IP "debian/compat" 4 .IX Item "debian/compat" The compatibility level was declared in the first line \fIdebian/compat\fR file. .IP "Build-Depends: debhelper-compat (= )" 4 .IX Item "Build-Depends: debhelper-compat (= )" The compatibility was declared in the \fIdebian/control\fR via a build dependency on the \&\fBdebhelper-compat (= )\fR package in the \fBBuild-Depends\fR field. In the output, the \fBC\fR is replaced by the actual compatibility level. A full example value would be: .Sp .Vb 1 \& Build\-Depends: debhelper\-compat (= 13) .Ve .RE .RS 4 .RE .SS "supported-compat-levels (\s-1JSON, CRFA\s0)" .IX Subsection "supported-compat-levels (JSON, CRFA)" \&\fBSynopsis\fR: \fBdh_assistant\fR \fBsupported-compat-levels\fR .PP Outputs information about which compat levels, this build of debhelper knows about. .PP This command accepts no options or arguments. .SS "which-build-system (\s-1JSON\s0)" .IX Subsection "which-build-system (JSON)" \&\fBSynopsis\fR: \fBdh_assistant\fR \fBwhich-build-system\fR [\fIbuild step\fR] [\fIbuild system options\fR] .PP Output information about which build system would be used for a particular build step. The build step must be one of \fBconfigure\fR, \fBbuild\fR, \fBtest\fR, \fBinstall\fR or \fBclean\fR and must be the first argument after \fBwhich-build-system\fR when provided. If omitted, it defaults to \fBconfigure\fR 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 \fBconfigure\fR step has not been run. .PP Additionally, the \fBclean\fR step can also provide \*(L"surprising\*(R" 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 \fBconfigure\fR would detect. This is generally a cosmetic issue as both build systems are all basically a glorified \&\fBrm \-fr builddir\fR and more precise detection is functionally irrelevant as far as debhelper is concerned. .PP The option accepts all debhelper build system arguments \- i.e., options you can pass to all of the \fBdh_auto_*\fR commands plus (for the \fBinstall\fR step) the \fB\-\-destdir\fR option. These options affect the output and auto-detection in various ways. Passing \fB\-S\fR or \fB\-\-buildsystem\fR overrides the auto-detection (as it does for \fBdh_auto_*\fR) but it still provides introspection into the chosen build system. .PP Things that are useful to know about the output: .IP "\(bu" 4 The key \fBbuild-system\fR 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 \fB\-S\fR and \fB\-\-buildsystem\fR are omitted, this is the result of debhelper's auto-detection logic. .Sp The value is valid as a parameter for the \fB\-\-buildsystem\fR option. .Sp The special value \fBnone\fR is used to denote that no build system would be used. This value is not present in \fB\-\-list\fR parameter for the \fBdh_auto_*\fR commands, but since debhelper/12.9 the value is accepted for the \fB\-\-buildsystem\fR option. .Sp Note that auto-detection is subject to limitations in regards to third-party build systems. While debhelper \fIdoes\fR 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 \fBbuild-system\fR being \fBnone\fR in the output). .IP "\(bu" 4 The \fBbuild-directory\fR and \fBbuildpath\fR values serve different but related purposes. The \&\fBbuild-directory\fR generally mirrors the \fB\-\-builddirectory\fR option where as \fBbuildpath\fR is the output directory that debhelper will use. Therefore the former will often be null when \fB\-\-builddirectory\fR has not been passed while the latter will generally not be null (except when \fBbuild-system\fR is \fBnone\fR). .IP "\(bu" 4 The \fBdest-directory\fR (\fB\-\-destdir\fR) is undefined for all build steps except the \fBinstall\fR build step (will be output as null or absent). For the same reason, \fB\-\-destdir\fR should only be passed for \fBinstall\fR build step. .Sp Note that if not specified, this value is currently null by default. .IP "\(bu" 4 The \fBparallel\fR value is subject to \fB\s-1DEB_BUILD_OPTIONS\s0\fR. Notably, if that does not include the \fBparallel\fR keyword, then \fBparallel\fR field in the output will always be 1. .IP "\(bu" 4 Most fields in the output \fIcan\fR be null. Particular if there is no build system is detected (or when \fB\-\-buildsystem=none\fR). 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. .SS "detect-hook-targets (\s-1JSON\s0)" .IX Subsection "detect-hook-targets (JSON)" \&\fBSynopsis\fR: \fBdh_assistant\fR \fBdetect-hook-targets\fR .PP Detects possible override targets and hook targets that \fBdh\fR\|(1) might use (provided that the relevant command is in the sequence). .PP The detection is based on scanning the rules file for any target that \fImight look\fR 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). .PP 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 \*(L"out of the box\*(R" behaviour will work well in most cases. .PP The output looks something like this: .PP .Vb 10 \& { \& "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" \& } \& ] \& } .Ve .PP In more details: .IP "commands-not-in-path" 4 .IX Item "commands-not-in-path" This attribute lists all the commands related to hook targets, which \fBdh_assistant\fR could \fBnot\fR find in \s-1PATH.\s0 These are usually caused by either the command not being installed on the system where \fBdh_assistant\fR is run or by the command not existing at all. .Sp If you are using this command to verify an hook target is present, please double check that the command is spelled correctly. .IP "hook-targets" 4 .IX Item "hook-targets" List over hook targets found along with additional information about them. .RS 4 .IP "command" 4 .IX Item "command" Attribute that lists which command this hook target is related too. .IP "target-name" 4 .IX Item "target-name" The actual target name detected in the \fIdebian/rules\fR file. .IP "is-empty" 4 .IX Item "is-empty" A boolean that determines whether \fBdh\fR\|(1) will optimize the hook out at runtime (see \*(L"Completely empty targets\*(R" in \&\fBdh\fR\|(1)). Note that empty override targets will still cause \fBdh\fR\|(1) to skip the original command. .IP "package-section-param" 4 .IX Item "package-section-param" This attribute defines what package selection parameter should be passed to \fBdh_*\fR commands used in the hook target. It can either be \fB\-a\fR, \fB\-i\fR or (if no parameter should be used) \f(CW\*(C`null\*(C'\fR. .RE .RS 4 .RE .PP This command accepts no options or arguments. .SS "log-installed-files" .IX Subsection "log-installed-files" \&\fBSynopsis\fR: \fBdh_assistant\fR \fB\-p\f(BIpkg\fB\fR \fI[\-\-on\-behalf\-of\-cmd=dh_foo]\fR \fBpath ...\fR .PP Mark one or more paths as installed for a given package. This is useful for telling \fBdh_missing\fR\|(1) that the paths have been installed manually. .PP The \fB\-\-on\-behalf\-of\-cmd\fR option can be used by third-party tools to have \fBdh_assistant\fR 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. \fBdh_install\fR). .PP Please keep in mind that: .IP "\(bu" 4 \&\fBNo\fR glob or substitution expansion is done by \fBdh_assistant\fR on the provided paths. If you want to use globs, have the shell perform the expansion first. .IP "\(bu" 4 Paths must be given as relative to the source root directory (e.g., \fIdebian/tmp/...\fR) .IP "\(bu" 4 You \fIcan\fR 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 \*(L"covered\*(R". .IP "\(bu" 4 Do not worry about providing the same filename twice in different invocations to \fBdh_assistant\fR due to \fB\-arch\fR / \&\fB\-indep\fR overrides. While it will be recorded multiple internally, \fBdh_missing\fR\|(1) will deduplicate when it parses the records. .PP Note this command only \fImarks\fR paths as installed. It does not actually install them \- the caller should ensure that the paths are in fact handled (or installed). .SH "COMMAND TAGS" .IX Header "COMMAND TAGS" Most commands have one or more of the following \*(L"tags\*(R" associated with them. Their meaning is defined here. .IP "\s-1JSON\s0" 4 .IX Item "JSON" The command provides \s-1JSON\s0 output. See \*(L"\s-1JSON OUTPUT\*(R"\s0 for details. .IP "\s-1CRFA\s0" 4 .IX Item "CRFA" \&\fIMnemonic \*(L"Can be Run From Anywhere\*(R"\fR .Sp Most commands must be run inside a source package root directory (a directory containing \fIdebian/control\fR) 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. .SH "JSON OUTPUT" .IX Header "JSON OUTPUT" Most commands uses \s-1JSON\s0 format as output. Consumers need to be aware that: .IP "\(bu" 4 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 \*(L"obvious\*(R" for that case. .IP "\(bu" 4 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). .PP 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 \s-1JSON\s0 formatter. An example of this: .PP .Vb 1 \& dh_assistant supported\-compat\-levels | json_pp | less .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBdebhelper\fR\|(7) .PP This program is a part of debhelper.