dh-make-perl - Create debian source packages from Perl modules
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 customizations. 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 overwriting 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 sparingly 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 added 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 added 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-script
path
- Use specified script for building the binary package. The script is run in
the working directory, where debian/ directory is, with no
arguments. The result of the build process is expected to appear in the
parent directory.
- --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 --config-dir, but
does not change the location of the APT Contents cache file. If both are
given, --config-dir takes precedence.
- --depends
DEPENDS
- Manually specify a string to be added 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
If you need to override the detection and specify the full
dependency list by hand, use --force-depends.
- --desc SHORT
DESCRIPTION
- Uses the argument to --desc as short description for the package.
- --dh
VERSION
- Set desired debhelper compatibility level. The default is 13.
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.
- --force-depends
STRING
- Completely override detected run-time dependencies, replacing them with
the given STRING.
- --guess-nocheck |
--no-guess-nocheck
- This adds <!nocheck> to the build-time dependencies where
appropriate. Uses a hardcoded list with exceptions so it is not turned on
by default.
Default: --no-guess-nocheck
- --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.
- --install-with
apt|apt-get|aptitude|dpkg
- Change the tool that is used to install the package when --install
is given.
Default is apt.
- --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.
- --config-dir
DIRECTORY
- Where the configuration files are stored. This option has precedence over
--home-dir.
Default: ~/.dh-make-perl (if present),
$XDG_CONFIG_HOME/dh-make-perl,
~/.config/dh-make-perl
- --cache-dir
DIRECTORY
- Where APT Contents and other caches are stored. This option has precedence
over --home-dir.
Default: ~/.dh-make-perl (if present),
$XDG_CACHE_HOME/dh-make-perl,
~/.cache/dh-make-perl
- --home-dir
DIRECTORY
- Legacy option to specify both the config and cache directories. See
--config-dir and --cache-dir.
- --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:
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 upstream version of the resulting package. Usually
calculated correctly but --version can override wrong guesses.
Note that this is just the upstream version and is also
used for the tag in the "upstream"
branch. If you need to also specify the Debian revision, use
--revision.
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.
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.
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
Several, let me know when you find them.