Perl Packaging Guidelines

Module package naming

See Packaging Guidelines: Naming: Perl modules.

License tag

See Licensing guidelines specific to Perl.

Directory Ownership

As specified in the general Packaging Guidelines, Perl packages are expected to share ownership of certain directories.

In general, a noarch Perl package must own:

# For noarch packages: vendorlib
%{perl_vendorlib}/*

…​and a arch-specific Perl package must own:

# For arch-specific packages: vendorarch
%{perl_vendorarch}/*
%exclude %dir %{perl_vendorarch}/auto/

Build Dependencies

As stated in Packaging Guidelines: Build-Time Dependencies (BuildRequires), a package must explicitly indicate its build dependencies (using BuildRequires:) outside of the minimal set required for RPM to build packages. This includes any dependency on Perl. While Perl may have been in the default buildroot at one time, this is not currently the case.

Below is a list of Perl-related build dependencies you may need.

  • perl-generators – Automatically generates run-time Requires and Provides for installed Perl files. Whenever you install a Perl script or a Perl module, you must include a build dependency on this package.

  • perl-interpreter – The Perl interpreter must be listed as a build dependency if it is called in any way, either explicitly via perl or %__perl, or as part of your package’s build system.

  • perl-devel - Provides Perl header files. If building architecture-specific code which links to libperl.so library (e.g. an XS Perl module), you must include BuildRequires: perl-devel.

If a specific Perl module is required at build time, use perl(MODULE) syntax as documented above. This applies to so called core modules as well, since they may move in and out of the base Perl package over time.

If you need to limit your package to a specific Perl version, use perl(:VERSION) dependency with desired version constraint (e.g. perl(:VERSION) >= 5.22). Do not use a comparison against the version of the perl package because it includes an epoch number, which makes version comparisons tricky.

Perl Requires and Provides

Perl packages use the virtual perl(Foo) naming to indicate a given Perl module. Packages should use this methodology, and not require the package name directly. For example, a package requiring the Perl module Readonly should not explicitly require perl-Readonly, but rather perl(Readonly), which the perl-Readonly package provides.

It is recommended to include explicit dependencies for core modules, because they can move between sub-packages or disappear from core Perl.

Versioned MODULE_COMPAT_ Requires or perl-libs

Packages with Perl modules installed in %{perl_vendorarch}, %{perl_vendorlib}, %{perl_privlib} or %{perl_archlib} will automatically gain dependency on perl-libs for pure Perl modules or a dependency on perl(:MODULE_COMPAT_<perl_version>) for libraries with compiled code. The dependency is handled by perl-generators.

Packages that require the Perl interpreter or libperl.so but do not install modules to the aforementioned directories or explicitly link to libperl.so.<perl_version> need to handle the dependency manually.

Filtering Requires and Provides

RPM’s dependency generator can often throw in additional dependencies and will often think packages provide functionality contrary to reality. To fix this, the dependency generator needs to be overridden so that the additional dependencies can be filtered out. Please see Packaging Guidelines: Automatic Filtering of Provides and Requires - Perl for information.

Manual Requires and Provides

Under some circumstances, RPM’s automatic dependency generator can miss dependencies that should be added. This is usually as a result of using language constructs that the dependency script wasn’t expecting. An example of this is in the perl-Class-Accessor-Chained package, where the following can be found:

use base 'Class::Accessor::Fast';
...
use base 'Class::Accessor';

A tell-tale sign of this particular construct is that the package contains a dependency on perl(base), but this is not the only situation in which dependencies can be missed. This package needed additional dependencies as follows:

Requires: perl(Class::Accessor), perl(Class::Accessor::Fast)

In general, it’s a good idea to look at the upstream package’s documentation for details of other dependencies.

Another similar example of missing requirements can be seen in perl-Spreadsheet-WriteExcel:

package Spreadsheet::WriteExcel::Utility;
...
use autouse 'Date::Calc'  => qw(Delta_DHMS Decode_Date_EU Decode_Date_US);
use autouse 'Date::Manip' => qw(ParseDate Date_Init);

Similarly, it possible to miss Provides:, as was the case in Bug #167797 , where the perl-DBD-Pg package failed to Provide: perl(DBD::Pg) due to the following construct in DBD::Pg version 1.43:

{ package DBD::Pg;

The usual way of writing this, and what’s expected by RPM, is:

{
package DBD::Pg;

So it’s wise to examine the Provides: of your packages to check that they are sane and complete. If something is missing, it can be fixed either by using manual Provides: entries, or by patching the source to use a format that RPM can parse correctly.

URL tag

For CPAN-based packages the URL tag should use a non-versioned metacpan.org URL. E.g., if one were packaging the module Net::XMPP, the URL would be:

URL: https://metacpan.org/release/Net-XMPP

Testing and Test Suites

Perl packages typically have a large, healthy test suite. It is policy to run as much of the test suite as possible, subject to the technical limitations of the build system. This means, at the least:

  • All modules required for tests should be listed as a BuildRequires

  • Any "optional" tests should be enabled

  • Any modules needed for the tests but not yet in Fedora that could be included in Fedora should also be submitted for review

When to not test

There are a couple caveats here:

  • Optional tests do not need to be enabled if they will cause circular build deps

  • Tests which require network or display access should be disabled for the build system, but with a method provided for local builds

  • Tests which do not test package functionality should still be invoked, but their exclusion not be considered a blocker (e.g. Test::Pod::Coverage, Test::Kwalitee and the like)

  • Author, "release candidate", or smoke tests do not need to be enabled e.g. tests using Perl::Critic.

Additionally, for "meta" packages that provide a common interface to a number of similar modules, it is not necessary to package all of the modules that the package supports so long as at least one module exists to allow the meta package to provide functionality. For instance, the package perl-JSON-Any (JSON::Any) provides a common interface to JSON, JSON::XS, JSON::PC, JSON::Syck and JSON::DWIM; JSON::PC and JSON::DWIM are not currently in Fedora and do not need to be packaged as, e.g. JSON::XS enables JSON::Any.

Conditionally enabling/disabling tests

One common way to disable a test for mock but enable it locally is to use a _with_foo macro test, e.g.,

%check
%{!?_with_network_tests: rm t/roster.t }
./Build test

With this construct, an offending test will be removed and not executed, unless --with network_tests is passed to rpmbuild or %_with_network_tests is defined somewhere, e.g. in a user’s $HOME/.rpmmacros. This approach preserves the test suite for local builds while working within the technical limitations of the build system.

Makefile.PL vs Build.PL

Perl modules typically utilize one of two different build systems:

  • ExtUtils::MakeMaker

  • Module::Build

The two different styles are easily recognizable: ExtUtils::MakeMaker employs the Makefile.PL build file, and is the "classical" approach; Module::Build is a newer approach, with support for things MakeMaker cannot do. While the ultimate choice of which system to employ is clearly in the hands of upstream, if Build.PL is present in a distribution the packager should employ that build framework unless there is a good reason to do otherwise.

See also PackagingTips/Perl#Makefile.PL_vs_Build.PL .

.h files in module packages

It is not uncommon for binary module packages to include .h files, see e.g. perl-DBI, perl-Glib, perl-Gtk2. For a variety of reasons these should not be split off into a -devel package.

Updates of packages

Summary of tools used for updates and helpful comments can be found here Perl/updates.

Useful tips

Some modules try to pull in modules from CPAN. Instead of patching makefile, you can easily add PERL5_CPANPLUS_IS_RUNNING=1 to avoid CPAN entirely.

Perl SIG

People around Perl, who are packaging, maintaining & reviewing packages. If you are interested in Perl, join the mailing list, where are discussed latest issues.

Want to help? Learn how to contribute to Fedora Docs ›