Adding upstream version 13.15.3.upstream/13.15.3

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 192 insertions, 0 deletions

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<dh_installexamples> [S<I<debhelper options>>] [B<-A>] [B<-X>I<item>] [S<I<file> ...>]
+
+=head1 DESCRIPTION
+
+B<dh_installexamples> is a debhelper program that is responsible for
+installing examples into F<usr/share/doc/package/examples> in package
+build directories.
+
+From debhelper compatibility level 11 on, B<dh_install> will fall back to
+looking in F<debian/tmp> 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<package>.examples
+
+Lists example files or directories to be installed.
+
+If upstream provides an F<examples> directory, you will often want to use B<examples/*> rather
+than B<examples> in this file.  The latter would create
+F<< /usr/share/doc/I<package>/examples/examples >>, which is rarely what you want.
+
+Supports substitution variables in compat 13 and later as
+documented in L<debhelper(7)>.
+
+=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<dir>
+
+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 B<dh_auto_>I<*> commands. You rarely need to use this option, since
+B<dh_installexamples> automatically looks for files in F<debian/tmp> in debhelper
+compatibility level 11 and above.
+
+=item B<--doc-main-package=>I<main-package>
+
+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<main-package> >> 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<dh_installexamples> 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<item>, B<--exclude=>I<item>
+
+Exclude files that contain I<item> anywhere in their filename from
+being installed.
+
+=item I<file> ...
+
+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<dh_installexamples> will happily copy entire directory hierarchies
+if you ask it to (similar to B<cp -a>). 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<doc-pkg>');
+}
+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<debhelper(7)>
+
+This program is a part of debhelper.
+
+=head1 AUTHOR
+
+Joey Hess <joeyh@debian.org>
+
+=cut