DH-MAKE-PERL(1p)

📦
version 0.133 · 7 versions
, in ubuntu stonking

💖 DH-MAKE-PERL(1p) — User Contributed Perl Documentation 💖

okay bestie, welcome to the group chat. this is dh-make-perl, section 1p of the user-contributed Perl docs, and it's literally the tool that turns your lil Perl module into a whole Debian source package. buckle up. 🎀

✨ 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...

like. look at those. so many entry points. main character energy fr. 👑

✨ DESCRIPTION ✨

so dh-make-perl will create all the files you need to build a debian source package out of a Perl module or a CPAN distribution. it works for most simple packages, and ngl it's also super useful for just getting started with packaging Perl modules in the first place.

you can name a module or distribution with the --cpan switch, and dh-make-perl will go download it for you from a CPAN mirror — or you can just point it at a directory that already has the unpacked sources sitting there. and if you give it neither --cpan nor a directory as an argument, it tries to create a Perl package from the data in the current directory. lowkey convenient.

you can build and install the debian binary package using the --build and --install command line switches. slay.

if dh-make-perl gets called as

cpan2deb <options...> Foo::Bar

it behaves like

dh-make-perl make <options...> --build --cpan Foo::Bar

and if it gets called as

cpan2dsc <options...> Foo::Bar

it behaves like

dh-make-perl make <options...> --build-source --cpan Foo::Bar
🫶 bestie. using this program is no excuse for not reading the debian developer documentation. that means the Debian policy, the Debian Perl policy, the packaging manual, and so on. read them. for real. no skimming.

🌸 COMMANDS 🌸

make

the default command when you don't give a command at all. it creates a "debianisation" from scratch. and it fails with an error if a debian/ directory already exists — so don't try it, it's not gonna work. 💀

refresh [directory]

for refreshing a package. directory defaults to the current working directory. it rebuilds debian/copyright and debian/rules using the current templates. and before anything gets changed in those files, a backup copy is made with a .bak suffix. safety first, we love that. 🫶

this is useful when debian/rules was created using older templates and doesn't contain much customization. but as always, you're strongly encouraged to verify whether debian/rules looks sane. read your own diff, bestie.

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. but 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>. glow up. ✨

this option lets you 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, and the arguments accumulate. 🎀

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's older than any Contents file. but — and this is the annoying part — 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 than the Contents files. periodt.

dump-config

causes the current config, including any default settings, to be printed to the standard output.

useful for populating a dh-make-perl.conf file. iykyk.

help

displays short usage information.

💅 OPTIONS 💅

  • --arch any | all — switches between arch-dependent and arch-independent packages. if --arch isn't used, dh-make-perl uses a relatively good-working algorithm to decide this all on its own. independent queen.
  • --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's 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. be careful bestie.
  • --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's 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 the specified script for building the binary package. the script is run in the working directory, where the 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's 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 it's 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 where dh-make-perl looks for its default rules.* templates. it's 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. no cap, full override. 🔥
  • --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 — okay so when --install is in the mix, this is the tool that actually does the installing. The default is apt. Mix and match as you please. ✨
  • --intrusive — when it's working out module dependencies and Module::Depends fails, it goes "bet" and tries again with Module::Depends::Intrusive. And bestie… M:D:I loads all the .pm files, intercepting the loading of other modules, which is effectively running untrusted code on your behalf. Use with caution. Like, for real, tread carefully here. 😭
  • --network — enables querying of Debian WNPP lists for ITP and similar bugs. It's on by default, so pass "--no-network" to switch it off. 🌈
  • --notest — girly… this option, the one for not running the automatic testing of the module as part of the build script, was removed in 0.54. So please put nocheck in the DEB_BUILD_OPTIONS environment variable if you want to skip the tests when building a package. That's the move now. 🚫💅
  • --config-dir DIRECTORY — where the configuration files are stored. This one takes 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 also has precedence over --home-dir.

Default: ~/.dh-make-perl (if present), $XDG_CACHE_HOME/dh-make-perl, ~/.cache/dh-make-perl

  • --home-dir DIRECTORY — the legacy option that specifies both the config and cache directories in one go. See --config-dir and --cache-dir. Lowkey the old way but it still works. 🎀
  • --packagename | -p PACKAGENAME — you get to manually specify the Package Name. Super useful when the module has dashes in its name and the vibes get confusing.
  • --pkg-perl — useful when you're 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), it sets up a Git remote pointing to the right place on salsa.debian.org.

  • --recursive — only valid in "make" mode with --cpan or directory arguments. It makes dh-make-perl try to create packaging (and maybe build and install the packages too, if --build and --install are also given) for any dependencies which are missing packages.

The way this works: when the 'main' package is constructed, any missing packages get dropped into a list, and then the "debianisation" procedure is run in turn on each of them, recursively. It's giving infinite loop but, like, the helpful kind. 🌀

  • --requiredeps — fail if a dependency Perl package was not found. No missing deps allowed, periodt. ❌
  • --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)". She's classic. 🌸
  • --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/latest — the initial branch containing upstream sources
  • debian/latest — the branch where packaging is done, forked off "upstream/latest" 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. Very main character of it. 👑

  • --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 it's 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, using libdpkg-perl. It will find your deps, trust. 🦋

🎀 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. Handy bestie behavior honestly. 💅

🌈 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 Brockschmidt <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>
  • Carnë 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 <mc@unistra.fr>
  • 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 :-/ 🙈

okay love u, that's the whole page!! 🫶 this one shipped as perl v5.40.1, dated 2026-05-08, and it lives at DH-MAKE-PERL(1p). go make some packages bestie, you got this 💜🌸✨

📦 where this page comes from