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...
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 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
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, debian/compat 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. It hooks quilt(1) into
debian/rules and creates debian/README.source
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 conains the given Perl
MODULE.
Example:
dh-make-perl locate IPC::Run3
- 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¶
- --apt-contents-dir dir
- Location of apt-file Contents directory. Default is
/var/cache/apt/apt-file
- --arch any | all
- This switches between arch-dependent and arch-independet
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 the string to be used for 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 the string to be used for the module's
build-dependencies for architecture-independent builds. Same notes as
those for the --depends and --bdepends options apply here.
Note that for --depends, --bdepends and --bdependsi you can also specify
that the field should not appear in debian/rules (if you really mean it,
of course ;-) ) by giving it an empty string as an argument.
- --build
- Builds the package after setting it 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.
- --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 the string to be used for 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 version. If "ver" is
>=7, generated debian/rules is minimalistic, using the auto-mode of
debhelper. Also, any additional documentation and examples are listed in
additional files under debian/, instead of being listed in debian/rules.
Since version 0.60, dh-make-perl only supports debhelper
compatibility levels =7>.
- --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 ;-) )
- --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
http://pkg-perl.alioth.debian.org
<http://pkg-perl.alioth.debian.org>.
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 git.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 debianisaion procedure is run in
turn on each of them, recursively.
- --requiredeps
- Fail if a dependency Perl package was not found (dependency
tracking requires the apt-file package installed and updated)
- --source-format format
- When creating or refreshing packaging, use the specified
source format. Defaults to "3.0 (quilt)".
- --sources-list FILE
- Instruct the "Contents" file parser to use this
file when determining if a given file should be parsed or not.
Contents files not matching any line in sources.list are not parsed
in order to save you time parsing old files from mirrors you no longer
use.
Default: apt's default.
- --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
git.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.
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.
- •
- rules.MakeMaker.noxs
A debian/rules makefile for modules that use ExtUtils::MakeMaker, but don't
have C/XS code.
- •
- rules.MakeMaker.xs
A debian/rules makefile for modules that use ExtUtils::MakerMaker and C/XS
code.
- •
- rules.Module-Build.noxs
A debian/rules makefile for modules that use Module::Build, but don't have
C/XS code.
- •
- rules.Module-Build.xs
A debian/rules makefile for modules that use Module::Build and C/XS
code.
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,
http://alioth.debian.org/projects/pkg-perl.
Patches from:
- Adam Sjoegren <asjo@koldfront.dk>
- Adrian Phillips <adrianp@powertech.no>
- Amos Shapira <amos.shapira@gmail.com>
- Ansgar Burchardt <ansgar@debian.org>
- Christian Kurz <shorty@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>
- Maximilian Gass <mxey@cloudconnected.org>
- Noel Maddy <noel@zhtwn.com>
- 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 :-/