Provided by: dh-make-perl_0.122_all bug

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

           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.

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

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 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>
       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 :-/