diff options
Diffstat (limited to 'dh_installexamples')
| -rwxr-xr-x | dh_installexamples | 192 |
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 |