From 90169463f86997737ed5b9c0ea2b311cd3b056b7 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Tue, 9 Apr 2024 14:53:53 +0200 Subject: Adding upstream version 13.15.3. Signed-off-by: Daniel Baumann --- dh_installexamples | 192 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100755 dh_installexamples (limited to 'dh_installexamples') diff --git a/dh_installexamples b/dh_installexamples new file mode 100755 index 0000000..ce970ac --- /dev/null +++ b/dh_installexamples @@ -0,0 +1,192 @@ +#!/usr/bin/perl + +=encoding UTF-8 + +=head1 NAME + +dh_installexamples - install example files into package build directories + +=cut + +use strict; +use warnings; +use Debian::Debhelper::Dh_Lib; + +our $VERSION = DH_BUILTIN_VERSION; + +=head1 SYNOPSIS + +B [S>] [B<-A>] [B<-X>I] [S ...>] + +=head1 DESCRIPTION + +B is a debhelper program that is responsible for +installing examples into F in package +build directories. + +From debhelper compatibility level 11 on, B will fall back to +looking in F for files, if it does not find them in the current +directory (or wherever you've told it to look using B<--sourcedir>). + +=head1 FILES + +=over 4 + +=item debian/I.examples + +Lists example files or directories to be installed. + +If upstream provides an F directory, you will often want to use B rather +than B in this file. The latter would create +F<< /usr/share/doc/I/examples/examples >>, which is rarely what you want. + +Supports substitution variables in compat 13 and later as +documented in L. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<-A>, B<--all> + +Install any files specified by command line parameters in ALL packages +acted on. + +=item B<--sourcedir=>I + +Look in the specified directory for files to be installed. This option +requires compat 11 or later (it is silently ignored in compat 10 or earlier). + +Note that this is not the same as the B<--sourcedirectory> option used +by the BI<*> commands. You rarely need to use this option, since +B automatically looks for files in F in debhelper +compatibility level 11 and above. + +=item B<--doc-main-package=>I + +Set the main package for a documentation package. This is used to +install the documentation of the documentation package in F<< +/usr/share/doc/I >> as recommended by the Debian policy +manual 3.9.7 in ยง12.3. + +In compat 11 (or later), this option is only useful if debhelper's +auto-detection of the main package is wrong. The option can also be +used to silence a warning from debhelper when the auto-detection fails +but the default happens to be correct. + +This option cannot be used when B is instructed to act +on multiple packages. If you need this option, you will generally +need to combine it with B<-p> to ensure exactly one package is acted +on. + +=item B<-X>I, B<--exclude=>I + +Exclude files that contain I anywhere in their filename from +being installed. + +=item I ... + +Install these files (or directories) as examples into the first package +acted on. (Or into all packages if B<-A> is specified.) + +=back + +=head1 NOTES + +Note that B will happily copy entire directory hierarchies +if you ask it to (similar to B). If it is asked to install a +directory, it will install the complete contents of the directory. + +=cut + +init(options => { + "sourcedir=s" => \$dh{SOURCEDIR}, + 'doc-main-package=s' => \$dh{DOC_MAIN_PACKAGE}, +}); + +# PROMISE: DH NOOP WITHOUT pkgfile-logged(examples) cli-options() + +my $pwd; +my $default_error_handler = compat(10) ? \&glob_expand_error_handler_reject_nomagic_warn_discard : \&glob_expand_error_handler_reject; +my $nodocs = is_build_profile_active('nodoc') || get_buildoption('nodoc') ? 1 : 0; +# We cannot assume documentation is built under nodoc, but if it is we must flag it as handled +# or dh_missing might make noise. +$default_error_handler = \&glob_expand_error_handler_silently_ignore if $nodocs; + +if (@{$dh{DOPACKAGES}} > 1 and $dh{DOC_MAIN_PACKAGE}) { + error('--doc-main-package should be used with -p'); +} +if ($dh{DOC_MAIN_PACKAGE}) { + assert_opt_is_known_package($dh{DOC_MAIN_PACKAGE}, '--doc-main-package'); +} + +foreach my $package (getpackages()) { + next if is_udeb($package); + + my $tmp=tmpdir($package); + my $file=pkgfile($package,"examples"); + my @search_dirs = ('.'); + my $skip_install = process_pkg($package) ? 0 : 1; + my $error_handler = $skip_install ? \&glob_expand_error_handler_silently_ignore : $default_error_handler; + @search_dirs = ($dh{SOURCEDIR} // '.', default_sourcedir($package)) if not compat(10); + + my @examples; + + if ($file) { + @examples = filearray($file, \@search_dirs, $error_handler) if $file; + } + + if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) { + push @examples, @ARGV; + } + + log_installed_files($package, @examples); + + next if $skip_install or $nodocs; + + if (@examples) { + my $target_package = compute_doc_main_package($package); + if (not defined($target_package)) { + warning("Cannot auto-detect main package for ${package}. If the default is wrong, please use --doc-main-package"); + $target_package = $package; + } + my $target_dir = "${tmp}/usr/share/doc/${target_package}/examples"; + install_dir($target_dir); + + my $exclude = ''; + if ($dh{EXCLUDE_FIND}) { + $exclude .= ' -and ! \( '.$dh{EXCLUDE_FIND}.' \)'; + } + + foreach my $example (@examples) { + next if excludefile($example); + if (-d $example && $exclude) { + my $basename = basename($example); + my $dir = ($basename eq '.') ? $example : "$example/.."; + chomp($pwd=`pwd`) if not defined($pwd); + # Gracefully handling tmpdir being absolute (-P/...) + my $destdir = $target_dir =~ m{^/} ? $target_dir : "${pwd}/${target_dir}"; + complex_doit("cd '$dir' && " . + "find '$basename' -type f$exclude -print0 | LC_ALL=C sort -z | " . + "xargs -0 -I {} cp --reflink=auto --parents -dp {} ${destdir}"); + } + else { + doit("cp", '--reflink=auto', "-a", $example, $target_dir); + } + } + } +} + +=head1 SEE ALSO + +L + +This program is a part of debhelper. + +=head1 AUTHOR + +Joey Hess + +=cut -- cgit v1.2.3