Provided by: dh-make-perl_0.109_all 
NAME
dh-make-perl - Create debian source packages from Perl modules
SYNOPSIS
dh-make-perl [make] {SOURCE_DIR | --cpan MODULE|DIST} options...
dh-make-perl refresh {--only ...} [directory]
dh-make-perl locate Foo::Bar ...
dh-make-perl refresh-cache
dh-make-perl dump-config
dh-make-perl help
cpan2deb MODULE|DIST options...
cpan2dsc MODULE|DIST options...
DESCRIPTION
dh-make-perl will create the files required to build a debian source package out of a Perl module or CPAN
distribution. This works for most simple packages and is also useful for getting started with packaging
Perl modules.
You can specify a module or distribution name with the --cpan switch and dh-make-perl will download it
for you from a CPAN mirror, or you can specify the directory with the already unpacked sources. If
neither --cpan nor a directory is given as argument, dh-make-perl tries to create a Perl package from the
data in the current directory.
You can build and install the debian binary package using the "--build" and "--install" command line
switches.
If dh-make-perl is called as
cpan2deb <options...> Foo::Bar
it behaves like
dh-make-perl make <options...> --build --cpan Foo::Bar
If dh-make-perl is called as
cpan2dsc <options...> Foo::Bar
it behaves like
dh-make-perl make <options...> --build-source --cpan Foo::Bar
Using this program is no excuse for not reading the debian developer documentation, including the Debian
policy, the Debian Perl policy, the packaging manual and so on.
COMMANDS
make
Default command if no command is given. Creates debianisation from scratch. Fails with an error if
debian/ directory already exists.
refresh [directory]
For refreshing a package. "directory" defaults to the current working directory. Rebuilds
debian/copyright, debian/rules using the current templates. Before any changes are made to these
files, a backup copy is created with a .bak suffix.
This is useful when debian/rules was created using older templates and doesn't contain much
customisations. As always, you're strongly encouraged to verify if debian/rules looks sane.
"refresh" also tries to update dependency lists in debian/control from META.yml.
When updating debian/copyright dh-make-perl tries to be clever about remembering email addresses. It
gets the list of copyright holders and their emails for debian/* from the sign off lines in
debian/changelog. However to allow for email addresses changing, it looks for change lines of the
form
* Email change: Debbie Devlin -> devlin@debian.org
So now "Debbie Devlin <devlin@debian.org>" will be used in the copyright instead of "Debbie Devlin
<debbie@devlin.org>".
--only | -o control|copyright|docs|examples|rules
This option allows one to update only one or more file(s) in the debian/ directory when dh-make-perl
is run in "refresh" mode. Filenames are separated by a comma. The option can be given multiple times,
accumulating arguments.
locate MODULE ...
Tries to locate the package that contains the given Perl MODULEs.
Example:
dh-make-perl locate IPC::Run3 XML::Tidy
refresh-cache
dh-make-perl parses the Contents files, fetched by apt-file(1) and stores the result in a cache. The
cache is refreshed automatically if it is older than any Contents file. However, if you run
apt-file(1) in your nightly cron job, the first time you run dh-make-perl during the day, you shall
wait for the cache to be reconstructed. With this option, you can move the cache re-creation to the
cron job, right after "apt-file update".
Does nothing if the cache is newer that the Contents files.
dump-config
Causes the current config, including any default settings to be printed to the standard output.
Useful for populating dh-make-perl.conf file.
help
Displays short usage information.
OPTIONS
--arch any | all
This switches between arch-dependent and arch-independent packages. If --arch isn't used, dh-make-
perl uses a relatively good-working algorithms to decide this alone.
--backups | --no-backups
In "refresh" mode, create backups of debian/copyright and debian/rules before overwritting them. On
by default.
--basepkgs
Explicitly gives a comma-separated list of packages to consider "base" packages (i.e. packages that
should always be available in Debian systems). This option defaults to "perl,perl-base" - it is used
to check for module dependencies. If a needed module is in the "basepkgs", it won't be mentioned in
the "depends:" field of "debian/control".
If this option is specified, the above mentioned default packages will not be included (but will be
mentioned as explicit dependencies in the resulting package). You can, of course, mention your own
modules and explicitly specify the default values.
Note that this option should be used sparsingly and with care, as it might lead to packages not being
rebuildable because of unfulfilled dependencies.
--bdepends BUILD-DEPENDS
Manually specify a string to be addedd to the module's build-dependencies (that is, the packages and
their versions that have to be installed in order to successfully build the package). Keep in mind
that packages generated by dh-make-perl require debhelper to be specified as a build dependency. Same
note as for --depends applies here - use only when needed.
--bdependsi BUILD-DEPENDS-INDEP
Manually specify a string to be addedd to the module's build-dependencies for architecture-
independent builds. Same notes as those for the --depends and --bdepends options apply here.
--build
Builds the binary package (i.e. the .deb file) after setting the package directory up.
NB: This builds only a binary package (by calling "fakeroot debian/rules binary") and does not sign
the package. It is meant for a quick local install of a package, not for creating a package ready for
submission to the Debian archive.
--build-source
Builds the source package (i.e. the .dsc and .debian.tar.gz files) after setting the package
directory up.
NB: This builds only a source package (by calling "dpkg-source -b") and does not sign the package. It
is meant for a quick local install of a source package to be thrown into e.g. a pbuilder, not for
creating a source package ready for submission to the Debian archive.
--closes ITPBUG
Manually specify the ITP bug number that this package closes. If not given, dh-make-perl will try to
connect to bugs.debian.org to fetch the appropriate bug number, using WWW::Mechanize.
--core-ok
Allows building core Perl modules. By default, dh-make-perl will not allow building a module that is
shipped as part of the standard Perl library; by specifying this option, dh-make-perl will build them
anyway.
Note that, although it is not probable, this might break unrelated items in your system - if a newer
version of a core module breaks the API, all kinds of daemons might get upset ;-)
--cpan MODULE|DIST
Instructs dh-make-perl to fetch and extract the given CPAN module or distribution. Works both with
"Foo::Bar" and "Foo-Bar".
--cpan-mirror MIRROR
Specifies a CPAN site to use as mirror.
--data-dir DIRECTORY
Use another data directory, instead of the default, "/usr/share/dh-make-perl"
Data directory is were dh-make-perl looks for its default rules.* templates. It is similar to
--home-dir, but does not change the location of the APT Contents cache file. If both are given,
--home-dir takes precedence.
--depends DEPENDS
Manually specify a string to be addedd to the module's dependencies. This should be used when
building modules where dh-make-perl cannot guess the Perl dependencies (such as modules built using
Module::Install), or when the Perl code depends on non-Perl binaries or libraries. Usually, dh-make-
perl will figure out the dependencies by itself. If you need to pass dh-make-perl dependency
information, you must do it using the debian package format. i.e.
dh-make-perl --depends libtest-more-perl
--desc SHORT DESCRIPTION
Uses the argument to --desc as short description for the package.
--dh VERSION
Set desired debhelper compatibility level. The default is 12.
Since version 0.77, dh-make-perl only supports debhelper compatibility levels >=8.
See debhelper(1).
--dist DISTRIBUTION
Limit the distributions whose "Contents" files are parsed. The argument is a distribution name.
Default: empty, meaning no filtering.
Example:
dh-make-perl --dist etch
--email | -e EMAIL
Manually specify the Maintainer email address to use in debian/control and in debian/changelog.
--exclude | -i [REGEX]
This allows you to specify a PCRE to exclude some files from the search for docs and stuff like that.
If no argument is given (but the switch is specified - not specifying the switch will include
everything), it defaults to dpkg-source's default values.
--install
Installs the freshly built package. Specifying --install implies --build - The package will not be
installed unless it was built (obviously ;-) )
--install-deps
Install all dependencies for the module, as long as those dependencies are available as Debian
packages.
--install-build-deps
Install dependencies required for building the module, as long as those dependencies are available as
Debian packages.
--intrusive
When determining module dependencies, if Module::Depends fails, tries again with
Module::Depends::Intrusive. M:D:I loads all .pm files, intercepting loading of other modules,
effectively running untrusted code on your behalf. Use with caution.
--network
Enables querying of Debian WNPP lists for ITP and similar bugs. Enabled by default, use
"--no-network" to disable.
--notest
This option for not running the automatic testing of the module as part of the build script has been
removed in 0.54. Please put nocheck in the DEB_BUILD_OPTIONS environment variable if you want to skip
the tests when building a package.
--home-dir DIRECTORY
Where APT Contents and other caches are stored.
Default: ~/.dh-make-perl
--packagename | -p PACKAGENAME
Manually specify the Package Name, useful when the module has dashes in its name.
--pkg-perl
Useful when preparing a package for the Debian Perl Group <https://perl-team.pages.debian.net/>.
Sets "Maintainer", "Uploaders", "Vcs-Git" and "Vcs-Browser" fields in debian/control accordingly.
Also, when "--vcs git" is used (the default), sets up a Git remote pointing to the right place on
salsa.debian.org.
--recursive
Valid only in "make" mode with "--cpan" or directory arguments. Causes dh-make-perl to try to create
packaging (and possibly build and install the packages if "--build" and "--install" options are also
given) for any dependencies which are missing packages.
This works like this: when the 'main' package is constructed, any missing packages are put in a list,
and then the debianisation procedure is run in turn on each of them, recursively.
--requiredeps
Fail if a dependency Perl package was not found.
--revision REVISION
Specifies the debian revision of the resulting package.
Useful when you want to let dh-make-perl discover the ustream version, but still enforce a specific
debian revision, e.g. when backporting.
Overridden by --version.
--source-format format
When creating or refreshing packaging, use the specified source format. Defaults to "3.0 (quilt)".
--vcs VCS
In --pkg-perl mode, use the specified version control system in the generated Vcs-* fields. The
default is "git".
If VCS is "git", "dh-make-perl" will setup a Git repository with three branches:
upstream
The initial branch containing upstream sources
master
The branch where packaging is done, forked off "upstream" and with the contents of the "debian/"
directory added.
pristine-tar
A branch to keep pristine-tar(1) data.
If --pkg-perl is also given, an "origin" remote is added pointing to the repository on
salsa.debian.org.
--verbose | --no-verbose
Print additional information while processing.
--verbose is on by default in "make" mode, off otherwise.
--version VERSION
Specifies the version of the resulting package. Usually calculated correctly but --version can
override wrong guesses.
Note that this is not the upstream version. For a non-native package you need to include the Debian
revision here, e.g. for a new package of upstream's x.y release this would be x.y-1.
DEPENDENCY RESOLUTION
For mapping upstream build, test, and runtime requirements to build and runtime dependencies on Debian
packages, dh-make-perl can use APT's Contents files, if apt-file(1) is installed, and additionally
/var/lib/dpkg/available, if "libdpkg-parse-perl" is installed.
FILES
The following directories will be searched to find additional files required by dh-make-perl:
/usr/share/dh-make-perl/
$HOME/.dh-make-perl/
• dh-make-perl.conf
User configuration. The file is in YAML format. The keys are option names, as documented in "OPTIONS"
(without leading --).
See the output of "dh-make-perl --dump-config", which can also be used for population of
dh-make-perl.conf.
ENVIRONMENT
HOME - get user's home directory
DEBFULLNAME - get the real name of the maintainer
LOGNAME or USER - get the username
DEBEMAIL or EMAIL - get the email address of the user
BUGS
Several, let me know when you find them.
AUTHOR
Paolo Molaro <lupus@debian.org> (MIA)
Maintained for a time by Ivan Kohler <ivan-debian@420.am>.
Maintained for a time by Marc Brockschmdit <marc@dch-faq.de>.
Maintained for a time by Gunnar Wolf <gwolf@gwolf.org>.
Now team-maintained by the Debian Perl Group,
https://salsa.debian.org/perl-team/modules/packages/dh-make-perl
Patches from:
Adam Sjoegren <asjo@koldfront.dk>
Adrian Phillips <adrianp@powertech.no>
Amos Shapira <amos.shapira@gmail.com>
Ansgar Burchardt <ansgar@debian.org>
Axel Beckert <abe@debian.org>
Carnee Draug <carandraug+dev@gmail.com>
Christian Kurz <shorty@debian.org>
Christopher Hoskin <mans0954@debian.org>
Damyan Ivanov <divanov@creditreform.bg>
David Paleino <d.paleino@gmail.com>
David Pashley <david@davidpashley.com>
Dima Kogan <dima@secretsauce.net>
Edward Betts <edward@debian.org>
Fermin Galan <galan@dit.upm.es>
Geoff Richards <qef@ungwe.org>
Gergely Nagy <algernon@bonehunter.rulez.org>
gregor herrmann <gregoa@debian.org>
Hilko Bengen <bengen@debian.org>
Kees Cook <keex@outflux.net>
Jesper Krogh <jesper@krogh.cc>
Johnny Morano <jmorano@moretrix.com>
Juerd <juerd@ouranos.juerd.net>
Marc Chantreux (mail withheld)
Matt Hope <dopey@debian.org>
Matthew Gabeler-Lee <cheetah@fastcat.org>
Maximilian Gass <mxey@cloudconnected.org>
Noel Maddy <noel@zhtwn.com>
Oleg Gashev <oleg@gashev.net>
Oliver Gorwits <oliver.gorwits@oucs.ox.ac.uk>
Paul Fenwick <pjf@perltraining.com.au>
Peter Flanigan <Support@RoxSoft.co.uk>
Peter Moerch <mn3k66i02@sneakemail.com>
Peter Pentchev <roam@ringlet.net>
Ryan Niebur <ryanryan52@gmail.com>
Salvatore Bonaccorso <carnil@debian.org>
Stephen Oberholtzer <oliverklozoff@gmail.com>
Tim Retout <diocles@debian.org>
Ton Nijkes <tonn@wau.mis.ah.nl>
... And others who, sadly, we have forgot to add :-/