diff options
Diffstat (limited to 'dh_assistant')
| -rwxr-xr-x | dh_assistant | 576 |
1 files changed, 576 insertions, 0 deletions
diff --git a/dh_assistant b/dh_assistant new file mode 100755 index 0000000..27b8703 --- /dev/null +++ b/dh_assistant @@ -0,0 +1,576 @@ +#!/usr/bin/perl + +=head1 NAME + +dh_assistant - tool for supporting debhelper tools and provide introspection + +=cut + +use strict; +use warnings; +use Debian::Debhelper::Dh_Lib; +use JSON::PP (); + +=head1 SYNOPSIS + +B<dh_assistant> B<I<command>> [S<I<additional options>>] + +=head1 DESCRIPTION + +B<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). + +=head1 COMMANDS + +The B<dh_assistant> supports the following commands: + +=head2 active-compat-level (JSON) + +B<Synopsis>: B<dh_assistant> B<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: + +=over 4 + +=item active-compat-level + +The compat level that debhelper will be using. This is the same as B<DH_COMPAT> when present +or else B<declared-compat-level>. This can be B<null> when no compat level can be detected. + +=item declared-compat-level + +The compat level that the package declared as its default compat level. This can be B<null> +if the package does not declare any compat level at all. + +=item declared-compat-level-source + +Defines how the compat level was declared. This is null (for the same reason as +B<declared-compat-level>) or one of: + +=over 4 + +=item debian/compat + +The compatibility level was declared in the first line F<debian/compat> file. + +=item Build-Depends: debhelper-compat (= <C>) + +The compatibility was declared in the F<debian/control> via a build dependency on the +B<< debhelper-compat (= <C>) >> package in the B<Build-Depends> field. In the output, +the B<C> is replaced by the actual compatibility level. A full example value would be: + + Build-Depends: debhelper-compat (= 13) + +=back + +=back + +=head2 supported-compat-levels (JSON, CRFA) + +B<Synopsis>: B<dh_assistant> B<supported-compat-levels> + +Outputs information about which compat levels, this build of debhelper knows +about. + +This command accepts no options or arguments. + +=head2 which-build-system (JSON) + +B<Synopsis>: B<dh_assistant> B<which-build-system> [S<I<build step>>] [S<I<build system options>>] + +Output information about which build system would be used for a particular build step. The build step +must be one of B<configure>, B<build>, B<test>, B<install> or B<clean> and must be the first argument +after B<which-build-system> when provided. If omitted, it defaults to B<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 B<configure> step has not been run. + +Additionally, the B<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 B<configure> would detect. +This is generally a cosmetic issue as both build systems are all basically a glorified +B<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 B<dh_auto_*> commands plus (for the B<install> step) the B<--destdir> option. These options +affect the output and auto-detection in various ways. Passing B<-S> or B<--buildsystem> +overrides the auto-detection (as it does for B<dh_auto_*>) but it still provides introspection +into the chosen build system. + +Things that are useful to know about the output: + +=over 4 + +=item * + +The key B<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 B<-S> and B<--buildsystem> are omitted, this is the result of +debhelper's auto-detection logic. + +The value is valid as a parameter for the B<--buildsystem> option. + +The special value B<none> is used to denote that no build system would be used. This value +is not present in B<--list> parameter for the B<dh_auto_*> commands, but since debhelper/12.9 +the value is accepted for the B<--buildsystem> option. + +Note that auto-detection is subject to limitations in regards to third-party build systems. +While debhelper I<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 B<build-system> being B<none> in the output). + +=item * + +The B<build-directory> and B<buildpath> values serve different but related purposes. The +B<build-directory> generally mirrors the B<--builddirectory> option where as B<buildpath> +is the output directory that debhelper will use. Therefore the former will often be null +when B<--builddirectory> has not been passed while the latter will generally not be null +(except when B<build-system> is B<none>). + +=item * + +The B<dest-directory> (B<--destdir>) is undefined for all build steps except the B<install> build +step (will be output as null or absent). For the same reason, B<--destdir> should only be +passed for B<install> build step. + +Note that if not specified, this value is currently null by default. + +=item * + +The B<parallel> value is subject to B<DEB_BUILD_OPTIONS>. Notably, if that does not include +the B<parallel> keyword, then B<parallel> field in the output will always be 1. + +=item * + +Most fields in the output I<can> be null. Particular if there is no build system is detected +(or when B<--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. + +=back + +=head2 detect-hook-targets (JSON) + +B<Synopsis>: B<dh_assistant> B<detect-hook-targets> + +Detects possible override targets and hook targets that L<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 I<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: + +=over 4 + +=item commands-not-in-path + +This attribute lists all the commands related to hook targets, which B<dh_assistant> could B<not> +find in PATH. These are usually caused by either the command not being installed on the system +where B<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. + +=item hook-targets + +List over hook targets found along with additional information about them. + +=over 4 + +=item command + +Attribute that lists which command this hook target is related too. + +=item target-name + +The actual target name detected in the F<debian/rules> file. + +=item is-empty + +A boolean that determines whether L<dh(1)> will optimize the hook out at runtime (see "Completely empty targets" in +L<dh(1)>). Note that empty override targets will still cause L<dh(1)> to skip the original command. + +=item package-section-param + +This attribute defines what package selection parameter should be passed to B<dh_*> commands used +in the hook target. It can either be B<-a>, B<-i> or (if no parameter should be used) C<null>. + +=back + +=back + +This command accepts no options or arguments. + +=head2 log-installed-files + +B<Synopsis>: B<dh_assistant> B<< -pI<pkg> >> I<[--on-behalf-of-cmd=dh_foo]> B<path ...> + +Mark one or more paths as installed for a given package. This is useful for telling L<dh_missing(1)> that the +paths have been installed manually. + +The B<--on-behalf-of-cmd> option can be used by third-party tools to have B<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. B<dh_install>). + +Please keep in mind that: + +=over 4 + +=item * + +B<No> glob or substitution expansion is done by B<dh_assistant> on the provided paths. If you want to use globs, +have the shell perform the expansion first. + +=item * + +Paths must be given as relative to the source root directory (e.g., F<debian/tmp/...>) + +=item * + +You I<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". + +=item * + +Do not worry about providing the same filename twice in different invocations to B<dh_assistant> due to B<-arch> / +B<-indep> overrides. While it will be recorded multiple internally, L<dh_missing(1)> will deduplicate when it +parses the records. + +=back + +Note this command only I<marks> paths as installed. It does not actually install them - the caller should ensure +that the paths are in fact handled (or installed). + +=head1 COMMAND TAGS + +Most commands have one or more of the following "tags" associated with them. Their +meaning is defined here. + +=over 4 + +=item JSON + +The command provides JSON output. See L</JSON OUTPUT> for details. + +=item CRFA + +I<Mnemonic "Can be Run From Anywhere"> + +Most commands must be run inside a source package root directory (a directory +containing F<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. + +=back + +=head1 JSON OUTPUT + +Most commands uses JSON format as output. Consumers need to be aware that: + +=over 4 + +=item * + +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. + +=item * + +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). + +=back + +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 + +=cut + +my $JSON_ENCODER = JSON::PP->new->utf8; + +# Prettify if we think the user is reading this. +$JSON_ENCODER = $JSON_ENCODER->pretty->space_before(0)->canonical if -t STDOUT; + +# We never use the log file for this tool +inhibit_log(); + +my %COMMANDS = ( + 'help' => \&_do_help, + '-h' => \&_do_help, + '--help' => \&_do_help, + 'active-compat-level' => \&active_compat_level, + 'supported-compat-levels' => \&supported_compat_levels, + 'which-build-system' => \&which_build_system, + 'detect-hook-targets' => \&detect_hook_targets, + 'log-installed-files' => \&log_installed_files_cmd, +); + +my ($COMMAND) = shift(@ARGV); +for my $arg (@ARGV) { + if ($arg eq '--help' or $arg eq '-h') { + $COMMAND = 'help'; + last; + } +} + + +sub _do_help { + my $me = basename($0); + print <<"EOF"; +${me}: Tool for supporting debhelper tools and provide introspection + +Usage: ${me} <command> [... addition arguments or options ...] + +The following commands are available: + help Show this help + active-compat-level Output information about which compat level is declared/active (JSON) + supported-compat-levels Output information about supported compat levels (JSON, CRFA) + which-build-system Determine which build system will be used (JSON) + detect-hook-targets Detect and output possible override and hook targets (JSON) + log-installed-files Mark one or more paths as "installed" so dh_missing is aware (BLD) + +Command tags: + + * JSON The command provides JSON output. + * CRFA Command does not need to be run from a package source directory + (Mnemonic "Can be Run From Anywhere") + * 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 invocation to remove. + + +Its primary purpose is to provide support for third-party debhelper implementations +not using the debhelper script API or provide introspection for third-party tools +(e.g., linters). Unless stated otherwise, commands must be run inside a source +package root directory - that is, the directory containing "debian/control". + +Most commands use JSON output. When stdout is a TTY, the JSON will be prettified. +See the manpage if you want formatting in other cases. +EOF + return; +} + +sub _assert_debian_control_exists { + return if -f 'debian/control'; + require Cwd; + my $cwd = Cwd::getcwd(); + warning("$cwd does not look like a package source directory (expected $cwd/debian/control to exist and be a file)"); + error("$COMMAND must be run inside a package source directory"); + return; +} + +sub _output { + my ($kvpairs) = @_; + print $JSON_ENCODER->encode($kvpairs); + return; +} + +sub active_compat_level { + if (@ARGV) { + error("$COMMAND: No arguments supported (please remove everything after the command)"); + } + _assert_debian_control_exists(); + my ($active_compat, $declared_compat, $declared_compat_source) = Debian::Debhelper::Dh_Lib::get_compat_info(); + if (not defined($declared_compat_source)) { + $declared_compat = undef; + $active_compat = undef if not exists($ENV{DH_COMPAT}); + } + my %compat_info = ( + 'active-compat-level' => $active_compat, + 'declared-compat-level' => $declared_compat, + 'declared-compat-level-source' => $declared_compat_source, + ); + _output(\%compat_info); + return; +} + +sub supported_compat_levels { + if (@ARGV) { + error("$COMMAND: No arguments supported (please remove everything after the command)"); + } + my %compat_levels = ( + 'MIN_COMPAT_LEVEL' => Debian::Debhelper::Dh_Lib::MIN_COMPAT_LEVEL, + 'LOWEST_NON_DEPRECATED_COMPAT_LEVEL' => Debian::Debhelper::Dh_Lib::LOWEST_NON_DEPRECATED_COMPAT_LEVEL, + 'LOWEST_VIRTUAL_DEBHELPER_COMPAT_LEVEL' => Debian::Debhelper::Dh_Lib::LOWEST_VIRTUAL_DEBHELPER_COMPAT_LEVEL, + 'MAX_COMPAT_LEVEL' => Debian::Debhelper::Dh_Lib::MAX_COMPAT_LEVEL, + 'HIGHEST_STABLE_COMPAT_LEVEL' => Debian::Debhelper::Dh_Lib::HIGHEST_STABLE_COMPAT_LEVEL, + 'MIN_COMPAT_LEVEL_NOT_SCHEDULED_FOR_REMOVAL' => Debian::Debhelper::Dh_Lib::MIN_COMPAT_LEVEL_NOT_SCHEDULED_FOR_REMOVAL, + ); + _output(\%compat_levels); + return; +} + +sub which_build_system { + my ($opt_buildsys, $destdir); + my $first_argv = @ARGV ? $ARGV[0] : ''; + my %options = ( + # Emulate dh_auto_install's --destdir + "destdir=s" => \$destdir, + ); + _assert_debian_control_exists(); + # We never want the build system initialization to modify anything (e.g. create "HOME") + $dh{NO_ACT} = 1; + require Debian::Debhelper::Dh_Buildsystems; + Debian::Debhelper::Dh_Buildsystems::buildsystems_init(options => \%options); + my @non_options = grep { !m/^-/ } @ARGV; + my $step = @non_options ? $non_options[0] : 'configure'; + if (@non_options && $first_argv =~ m/^-/) { + error("$COMMAND: If the build step is provided, it must be before any options"); + } + if (@non_options > 1) { + error("$COMMAND: At most one positional argument is supported"); + } + if (defined($destdir) and $step ne 'install') { + warning("$COMMAND: --destdir is not defined for build step \"$step\". Ignoring option") + } + { + no warnings qw(once); + $opt_buildsys = $Debian::Debhelper::Dh_Buildsystems::opt_buildsys; + } + my $build_system = Debian::Debhelper::Dh_Buildsystems::load_buildsystem($opt_buildsys, $step); + my %result = ( + 'build-system' => defined($build_system) ? $build_system->NAME : 'none', + 'for-build-step' => $step, + 'source-directory' => defined($build_system) ? $build_system->get_sourcedir : undef, + 'build-directory' => defined($build_system) ? $build_system->get_builddir : undef, + 'dest-directory' => defined($build_system) ? $destdir : undef, + 'buildpath' => defined($build_system) ? $build_system->get_buildpath : undef, + 'parallel' => defined($build_system) ? $build_system->get_parallel : undef, + 'upstream-arguments' => $dh{U_PARAMS}, + ); + _output(\%result); + return; +} + +sub _in_path { + my ($cmd) = @_; + for my $dir (split(':', $ENV{PATH})) { + return 1 if -x "${dir}/${cmd}"; + } + return 0; +} + +sub detect_hook_targets { + if (@ARGV) { + error("$COMMAND: No arguments supported (please remove everything after the command)"); + } + _assert_debian_control_exists(); + require Debian::Debhelper::SequencerUtil; + Debian::Debhelper::SequencerUtil::rules_explicit_target('does-not-matter'); + my ($explicit_targets, %result, @targets, @unverifiable_commands, %seen_cmds); + { + no warnings qw(once); + $explicit_targets = \%Debian::Debhelper::SequencerUtil::EXPLICIT_TARGETS; + } + while (my ($target, $non_empty) = each(%{$explicit_targets})) { + next if $target !~ m{^(?:execute_before_|execute_after_|override_)(\S+?)(-indep|-arch)?$}; + my ($command, $archness) = ($1, $2); + my $param; + if ($archness) { + $param = ($archness eq '-arch') ? '-a' : '-i' ; + } + my $target_info = { + 'target-name' => $target, + 'command' => $command, + 'package-section-param' => $param, + 'is-empty' => $non_empty ? JSON::PP::false : JSON::PP::true, + }; + push(@targets, $target_info); + push(@unverifiable_commands, $command) if not exists($seen_cmds{$command}) and not _in_path($command); + $seen_cmds{$command} = 1; + } + $result{'hook-targets'} = \@targets; + $result{'commands-not-in-path'} = \@unverifiable_commands; + _output(\%result); +} + +sub log_installed_files_cmd { + my $on_behalf_of = 'manually-via-dh_assistant'; + init( + options => { + 'on-behalf-of-cmd=s' => \$on_behalf_of, + }, + inhibit_log => 1, + ); + if (index($on_behalf_of, '/') >= 0) { + error('The value for --on-behalf-of-cmd must not contain slashes'); + } + if (@{$dh{DOPACKAGES}} != 1) { + error('The log-installed-files command must act on exactly one package (use -p<pkg> to define which)'); + } + my $package = $dh{DOPACKAGES}[0]; + for my $arg (@ARGV) { + $arg =~ tr:/:/:s; + if (! -e $arg) { + warning("The path ${arg} does not exist - double check it is correct. Note: it will recorded anyway."); + } + } + log_installed_files({ + 'package' => $package, + 'tool_name' => $on_behalf_of, + }, @ARGV); +} + +if (not defined($COMMAND)) { + error('Usage: ' . basename($0) . ' <command>'); +} +my $handler = $COMMANDS{$COMMAND}; +if (not defined($handler)) { + warning("Arguments/options must not be the first argument (except for --help)") + if $COMMAND =~ m/^-/; + error("Unknown command: $COMMAND"); +} + +$handler->(); + +=head1 SEE ALSO + +L<debhelper(7)> + +This program is a part of debhelper. + +=cut + +1; |