NAME

debhelper - Version number cheatsheet


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.


RECOMMENDED DEBHELPER VERSIONS

For architecture-dependent packages (Architecture: any) require debhelper 9.20120312~ because of the support of hardening compiler flags.

If Module::Build::Tiny is used, also require debhelper 9.20140227~.

For anything else debhelper 8 is enough.

dh-make-perl(1) should be able to set the right debhelper dependency automatically.


Most Common Scenarios

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 AUTOMATED_TESTING, that will run these tests, however. You could enable this flag (and thus the tests) using:

override_dh_auto_test:
	AUTOMATED_TESTING=1 dh_auto_test

Sometimes tests need X server in order to run. In this case the xvfb(1) and the xauth(1) packages should be declared as Build-Depends. debhelper overrides should be:

override_dh_auto_test:
	xvfb-run -a dh_auto_test

dh --with bash-completion

To install bash_completion snippets you may use:

%:
	dh $@ --with bash-completion

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:

%:
	dh $@

Note that the latest version of dh-make-perl does this automatically.


Occasionally Useful

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 debian/rules file when there are some file operations involved.

PACKAGE = $(shell dh_listpackages)
TMP     = $(CURDIR)/debian/$(PACKAGE)

If the source package contains more than one binary packages dh_listpackages returns all of them, so you probably want to use:

PACKAGE = $(firstword $(shell dh_listpackages))
TMP     = $(CURDIR)/debian/$(PACKAGE)

Then any of your paths become pretty trivial, you can specify them as: $(TMP)/usr/share/path/to/file. Otherwise, you can accomplish the same thing with: $(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

ARCHLIB := $(shell perl -MConfig -e 'print $$Config{vendorarch}')

and later e.g. $(TMP)/$(ARCHLIB)/....

Removing Something

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:

override_dh_auto_install:
	dh_auto_install
	rm --verbose $(TMP)/usr/share/perl5/Data/Format/._HTML.pm

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.

override_dh_auto_install:
	dh_auto_install
	rmdir --ignore-fail-on-non-empty --parents --verbose $(TMP)/usr/lib/perl5

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.

override_dh_auto_install:
	dh_auto_install
	rm $(TMP)/usr/share/perl5/._HTML.pm
	rmdir --ignore-fail-on-non-empty --parents --verbose $(TMP)/usr/share/perl5

If you're really sure, you could also do:

override_dh_auto_install:
	dh_auto_install
	rm -rfv $(TMP)/usr/share/perl5

But this might be dangerous, so it's not recommended.

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:

override_dh_fixperms:
	dh_fixperms
	chmod 644 $(TMP)/usr/share/path/to/file

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 /usr/bin/perl:

override_dh_installexamples:
	dh_installexamples
	sed -i '1s|^#!perl|#!/usr/bin/perl|' $(TMP)/usr/share/doc/$(PACKAGE)/examples/*

Another elegant method for achieving substitution of the shebang from /usr/local/bin/perl to /usr/bin/perl would be:

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|'

Parallel building

Some upstream build systems are not parallel-build safe. debhelper's --max-parallel can be used to disable parallel building:

override_dh_auto_build:
	dh_auto_build --max-parallel=1

Note that debhelper does not enable parallel building automatically.

Running tests needing writable HOME

Sometimes tests need to have access to a writable $HOME.

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


Module::AutoInstall

Module::AutoInstall is a module designed to automatically install missing dependencies, and is often incorporated as part of packages built using Module::Install. It installs using the CPAN Shell or CPANPLUS.

Common Case

debhelper 7.2.13 knows how to handle Module::Install based packages in general.

Module::Install 0.85

Module::Install 0.85 ignores the --skipdeps option, which is why treatment of that case differs from the usual one.

For Module::Install version 0.85, anything that uses AutoInstall will cause the CPAN shell to be executed in order to check dependencies. This was fixed in newer versions of Module::Install, but nonetheless many modules are distributed with this buggy version of the installer in inc/.

Build servers should not have to execute CPAN or connect to the Internet in the course of building a package, so you have to disable this behaviour.

We can do this by tricking Module::Install into thinking that we're running under CPANPLUS, which prevents it from running the CPAN shell, as follows:

# Module::Install 0.85 has a bug causing CPAN to be launched
override_dh_auto_configure:
	PERL5_CPANPLUS_IS_RUNNING=1 dh_auto_configure

Remember to note (by way of a comment) that this fix is only needed for Module::Install 0.85, so that it can be removed if/when it is upgraded.


CONTRIBUTORS

The following people have contributed to the maintainership of this file:


LICENSE AND COPYRIGHT

Copyright (c) 2009-2014 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.