=head1 NAME debhelper - Version number cheatsheet and more =head1 INTRODUCTION This is a guide detailing some common packaging scenarios, and the version of debhelper required for them. Contributions are welcomed, especially for any packaging scenarios not already discussed here. =head1 RECOMMENDED DEBHELPER VERSIONS tl;dr: Use debhelper C<10>. Depending on how far back packages should be backportable, different versions of debhelper make sense. With C<10> I is covered, with C<11> I and anything newer are fine. L should be able to set the right debhelper dependency automatically. =head1 Most Common Scenarios =head2 Forcing Special Tests Often, Perl packages will have special tests designated for certain environments only. It is often quite beneficial for us to run these tests during build-time, so we prefer to add the tests (if packaged) to Build-Depends-Indep. Usually there is an environment variable, like C, that will run these tests, however. You could enable this flag (and thus the tests) using: =begin html 
override_dh_auto_test:
	AUTOMATED_TESTING=1 dh_auto_test
=end html Sometimes tests need X server in order to run. In this case the L and the L packages should be declared as C. debhelper overrides should be: =begin html 
override_dh_auto_test:
	xvfb-run -a dh_auto_test
=end html =head2 dh --with bash-completion To install C snippets you may use: =begin html 
%:
	dh $@ --with bash-completion
=end html =head2 Short debian/rules Format Older versions of the rules file were pretty long and repetitive. To get most of the same features by default, all you have to do is: =begin html 
%:
	dh $@
=end html Note that the latest version of dh-make-perl does this automatically. =head1 Occasionally Useful =head2 Note on Paths In order to save on typing, be a bit lazy and improve a little bit on maintainability and readability of the file, the following variables are typically placed at the top of your F file when there are some file operations involved. =begin html 
PACKAGE = $(shell dh_listpackages)
TMP     = $(CURDIR)/debian/$(PACKAGE)
=end html If the source package contains more than one binary packages C returns all of them, so you probably want to use: =begin html 
PACKAGE = $(firstword $(shell dh_listpackages))
TMP     = $(CURDIR)/debian/$(PACKAGE)
=end html Then any of your paths become pretty trivial, you can specify them as: B<$(TMP)/usr/share/path/to/file>. Otherwise, you can accomplish the same thing with: B<$(CURDIR)/debian/package-name/usr/share/path/to/file> If you need the perl library path, which is variable since 5.20, you can use =begin html 
ARCHLIB := $(shell perl -MConfig -e 'print $$Config{vendorarch}')
=end html and later e.g. B<$(TMP)/$(ARCHLIB)/...>. =head2 Removing Something =head3 A File If for some reason you're not able to distribute a file, then you'll need to repack it. But if it's just causing issues like warnings with lintian or you otherwise don't want it installed, then you can remove it during build time by adding this override: =begin html 
override_dh_auto_install:
	dh_auto_install
	$(RM) --verbose $(TMP)/usr/share/perl5/Data/Format/._HTML.pm
=end html =head3 A Directory Sometimes you want to remove an entire directory post-install. You can do that too, but it usually helps to have some extra tests so that the 'rm' operation doesn't make too much noise. =begin html 
override_dh_auto_install:
	dh_auto_install
	rmdir --ignore-fail-on-non-empty --parents --verbose $(TMP)/$(ARCHLIB)
=end html This removes empty directories, ensuring you don't accidentally destroy things that should be installed. If the package is installing files that you don't need, remove the files first before removing the empty directory. =begin html 
override_dh_auto_install:
	dh_auto_install
	$(RM) --verbose $(TMP)/usr/share/perl5/._HTML.pm
	rmdir --ignore-fail-on-non-empty --parents --verbose $(TMP)/usr/share/perl5
=end html If you're really sure, you could also do: =begin html 
override_dh_auto_install:
	dh_auto_install
	$(RM) -rv $(TMP)/usr/share/perl5
=end html But this might be dangerous, so it's not recommended. =head2 Fixing Permissions Sometimes debhelper's fix permissions stage (dh_fixperms) sets the wrong permissions for a given file. You can use an override to fix this, like so: =begin html 
override_dh_fixperms:
	dh_fixperms
	chmod 644 $(TMP)/usr/share/path/to/file
=end html =head2 Fixing Interpreter Shebang Lines Sometimes examples are Perl scripts that do not use the absolute path of the Perl interpreter in the shebang line. In these cases, they should be rewritten to F: =begin html 
override_dh_installexamples:
	dh_installexamples
	sed -i '1s|^#!perl|#!/usr/bin/perl|' $(TMP)/usr/share/doc/$(PACKAGE)/examples/*
=end html Another elegant method for achieving substitution of the shebang from F to F would be: =begin html 
override_dh_installexamples:
	dh_installexamples
	find $(TMP)/usr/share/doc/$(PACKAGE)/examples -type f -print0 | \
		xargs -r0 sed -i -e '1s|^#!/usr/local/bin/perl|#!/usr/bin/perl|'
=end html =head2 Parallel building Some upstream build systems are not parallel-build safe. To disable parallel building, use debhelper's C<--no-parallel> option: =begin html 
override_dh_auto_build:
	dh_auto_build --no-parallel
=end html Note that debhelper does B enable parallel building automatically before compat level 10. =head2 Skipping tests Sometimes we want to skip a specific test, i.e. when it needs internet access. An option to do this is: =begin html 
TEST_FILES = $(filter-out t/foo.t t/bar.t,$(shell echo t/*.t))

override_dh_auto_test:
	#for EUMM:
	dh_auto_test -- TEST_FILES="$(TEST_FILES)"
	#for M::B:
	dh_auto_test -- --test_files "$(TEST_FILES)"
=end html For skipping the same tests during build as during B you can set I this way: =begin html 
SKIP_TESTS=$(shell cat debian/tests/pkg-perl/smoke-skip)
TEST_FILES=$(filter-out $(SKIP_TESTS), $(wildcard t/*.t))
=end html =head2 Running tests needing writable HOME Sometimes tests need to have access to a writable C<$HOME>. =begin html 
BUILDHOME = $(CURDIR)/debian/build

%:
	dh $@

override_dh_clean:
	dh_clean
	rm -rf $(BUILDHOME)

override_dh_auto_test:
	mkdir -p $(BUILDHOME)
	HOME=$(BUILDHOME) dh_auto_test
=end html PS: If C<$HOME> is set during build, it should normally be set for B as well, e.g. by putting C into F. =head1 CONTRIBUTORS The following people have contributed to the maintainership of this file: =over =item * Jonathan Yu L<< Ejawnsy@cpan.orgE >> =item * Tim Retout L<< Etim@retout.co.ukE >> =item * gregor herrmann L<< Egregoa@debian.orgE >> =item * Damyan Ivanov L<< Edmn@debian.orgE >> =back =head1 LICENSE AND COPYRIGHT Copyright (c) 2009-2018 by the individual contributors noted above. This document is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Perl is distributed under your choice of the GNU General Public License or the Artistic License. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL' and the Artistic License in `/usr/share/common-licenses/Artistic'. Any decisions that need to be made regarding the licensing, copyright and distribution of this file shall be determined by majority vote between the current members of the Debian Perl Team, with one vote for all members, and an additional vote granted to Debian Developers. =cut