From Fedora Project Wiki

m (moved Archives:PackagingDraft:Perl to Archive:PackagingDraft:Perl: Archive namespace is singular)
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{draft|Approved}}
== Changes from original draft ==
Removed section: Provides of binary vs. sub-package with separated binary -- This was deemed more generic than perl-only and also the advice is too simplistic.  Need something that explains when subpackages are preferred and when virtual provides are preferred.
Directory ownership -- wording clarifications
Filtering -- use the newly approved filtering update instead of the one based on the old perl guidelines
Restore the Makefile.PL vs Build.PL section.
Slightly reworded beginning of initial-cc sentence for clarity.
= DRAFT of Perl Packaging =
= DRAFT of Perl Packaging =


This document seeks to document the conventions and customs surrounding the proper packaging of perl modules in Fedora.  It does not intend to cover all situations, but to codify those practices which have served the Fedora perl community well.
This document seeks to document the conventions and customs surrounding the proper packaging of perl modules in Fedora.  It does not intend to cover all situations, but to codify those practices which have served the Fedora perl community well.


= Perl SIG =
People around Perl, who are packaging, maintaining & reviewing packages. If you are interested in Perl, join [https://lists.fedoraproject.org/mailman/listinfo/Perl-devel mailing list], where are discussed latest issues.


New Perl packages should set the [https://lists.fedoraproject.org/mailman/listinfo/Perl-devel Fedora perl SIG mailing list]  as a member of the initial-cc list for bugzilla.  This can be done by adding the user <code>perl-sig</code> to the initial CC list when creating the [[Package_SCM_admin_requests#New_Packages|New Package SCM Request]].


{{Anchor|licensetag}}
{{Anchor|licensetag}}
= License tag =
= License tag =


Line 20: Line 36:
= Directory Ownership =
= Directory Ownership =


As specified in the [[Packaging:Guidelines#File_and_Directory_Ownership | general Packaging Guidelines]], perl packages are permitted to share ownership of directories.
As specified in the [[Packaging:Guidelines#File_and_Directory_Ownership | general Packaging Guidelines]], perl packages are expected to share ownership of certain directories.
 
Since F-13 are paths shorter e.g. /usr/lib/perl5/vendor_perl/ instead of /usr/lib/perl5/vendor_perl/release_number/architecture_specification
 
As an example, assume that <code>perl-A-B</code> depends on <code>perl-A</code> and installs files into /usr/lib/perl5/vendor_perl/5.10.0/i386-linux-thread-multi/A/B. The base Perl package guarantees that it will own /usr/lib/perl5/vendor_perl/5.10.0/i386-linux-thread-multi for as long as it remains compatible with version 5.10.0, but a future upgrade of the <code>perl-A</code> package may install into (and thus own) /usr/lib/perl5/vendor_perl/5.11.0/i386-linux-thread-multi/A. So the <code>perl-A-B</code> package needs to own /usr/lib/perl5/vendor_perl/5.10.0/i386-linux-thread-multi/A as well as /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B in order to maintain proper ownership.


In general, a noarch Perl package should own:
In general, a noarch Perl package must own:


<pre>
<pre>
Line 33: Line 45:
</pre>
</pre>


...and a arch-specific Perl package should own:
...and a arch-specific Perl package must own:


<pre>
<pre>
Line 46: Line 58:


Perl packages use the virtual <code>perl(Foo)</code> 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 <code>perl-Readonly</code>, but rather <code>perl(Readonly)</code>, which the <code>perl-Readonly</code> package provides.
Perl packages use the virtual <code>perl(Foo)</code> 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 <code>perl-Readonly</code>, but rather <code>perl(Readonly)</code>, which the <code>perl-Readonly</code> package provides.
It is recommended to buildrequire core modules '''explicitly''', because they can move between sub-packages or disappear from core perl.


{{admon/caution|Do not explicitly buildrequire "perl-devel"|Explicitly requiring <code>perl-devel</code>, even when wrapped in a conditional construct, is strongly discouraged, and is generally considered a blocker at review and a packaging bug.  Instead, see the next section on requiring core modules -- making sure that these core modules are BR'ed when used will pull in the correct development perl packages.}}
{{admon/caution|Do not explicitly buildrequire "perl-devel"|Explicitly requiring <code>perl-devel</code>, even when wrapped in a conditional construct, is strongly discouraged, and is generally considered a blocker at review and a packaging bug.  Instead, see the next section on requiring core modules -- making sure that these core modules are BR'ed when used will pull in the correct development perl packages.}}
Line 51: Line 65:


{{Anchor|corebrs}}
{{Anchor|corebrs}}
== Core modules as buildrequires ==
It is recommended to buildrequire core modules '''explicitly''', because they can move between sub-packages or disappear from core perl.


== Versioned MODULE_COMPAT_ Requires ==
== Versioned MODULE_COMPAT_ Requires ==
Line 77: Line 88:
{{Anchor|depfiltering}}
{{Anchor|depfiltering}}


== Filtering Requires and Provides ==
== 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 overriden so that the additional dependencies can be filtered out. Please see [[https://fedoraproject.org/wiki/Packaging:AutoProvidesAndRequiresFiltering#Perl]] for information.


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 overriden so that the additional dependencies can be filtered out.  There are two main ways to do this:
{{admon/note| Updating deprecated methods|In the past, several other methods were given for doing this filtering. Those should be considered deprecated and packages should be updated to use the macros on [[https://fedoraproject.org/wiki/Packaging:AutoProvidesAndRequiresFiltering#Perl]] as time and the natural rebuild cycle permits.}}
 
Since F-11 it is possible to use RPM macros for filtering requires/provides; this methodology is both preferred and mandated by the Packaging Guidelines.  The perl package provides a specific filtering macro for use; this has the advantage of catching most common dep issues, as well as centralizing the logic in one, common location. The use of these macros should be conditionalized such that if someone tries to rebuild them on a system w/o the macros (e.g. RHEL/CentOS/AIX/etc) they will not cause the build to fail. See [[Packaging:AutoProvidesAndRequiresFiltering]] for more details.
 
=== General Case ===
 
The most common case, when there's no special need to filter anything in particular:
 
<pre>
%{?perl_default_filter}
</pre>
 
=== Filtering Errant Provides ===
<pre>
%{?filter_setup:
%filter_from_provides /perl(unwanted_provide)/d
%?perl_default_filter
}
</pre>
 
=== Duplicate Provides ===
 
Sometimes a package provides versioned and unversioned provides. The unversioned can be removed by:
 
<pre>
%{?filter_setup:
%filter_from_provides /^perl(unwanted_provide)$/d
%?perl_default_filter
}
</pre>


{{Anchor|manualdeps}}
{{Anchor|manualdeps}}
Line 143: Line 126:
So it's wise to examine the Provides: of your packages to check that they are sane and complete.
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.
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.
== Provides of binary vs. sub-package with separated binary ==
Some packages e.g. perl-Padre have binary, which should be install in yum by simple 'yum install padre'. This could be done by
defining the name of binary in provides
<pre>
Provides: padre
</pre>
or creating a sub-package.
<pre>
%package -n padre
Summary:        Padre binary
License:        GPL+ or Artistic
Group:          Development/Tools
Requires:      perl-Padre = %{version}-%{release}
%description -n padre
Some description here...
</pre>
Both solutions are correct. It depends on package maintainer, which of those two possibilities is chosen.


= URL tag =
= URL tag =
Line 202: Line 166:
With this construct, an offending test will be removed and not executed, unless "--with network_tests" is passed to <code>rpmbuild</code> or %_with_network_tests is defined somewhere, e.g. in a user's <code>$HOME/.rpmmacros</code>.  This approach preserves the test suite for local builds while working within the technical limitations of the buildsystem.
With this construct, an offending test will be removed and not executed, unless "--with network_tests" is passed to <code>rpmbuild</code> or %_with_network_tests is defined somewhere, e.g. in a user's <code>$HOME/.rpmmacros</code>.  This approach preserves the test suite for local builds while working within the technical limitations of the buildsystem.


= Makefile.PL vs Build.PL =
Perl modules typically utilize one of two different buildsystems:
* Ext<code></code>Utils::Make<code></code>Maker
* Module::Build
The two different styles are easily recognizable:  Ext<code></code>Utils::Make<code></code>Maker employs the Makefile.PL build file, and is the "classical" approach; Module::Build is a newer approach, with support for things Make<code></code>Maker 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 otherwise.


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


= .h files in module packages =
= .h files in module packages =
Line 208: Line 181:
It is not uncommon for binary module packages to include .h files, see e.g. <code>perl-DBI</code>, <code>perl-Glib</code>, <code>perl-Gtk2</code>.  For a variety of reasons these should not be split off into a -devel package.
It is not uncommon for binary module packages to include .h files, see e.g. <code>perl-DBI</code>, <code>perl-Glib</code>, <code>perl-Gtk2</code>.  For a variety of reasons these should not be split off into a -devel package.


= Set inital-cc to 'perl-sig' =


It's common practice to set the [https://lists.fedoraproject.org/mailman/listinfo/Perl-devel Fedora perl SIG mailing list]  as a member of the initial-cc list for bugzilla.  This can be done by adding the user <code>perl-sig</code> to the initial CC list when creating the [[CVSAdminProcedure#New_Packages|New Package CVS Request]].


= cpanspec =
= cpanspec =
Line 232: Line 203:


[[Category:Perl]]
[[Category:Perl]]
[[Category:Archived packaging guideline drafts]]

Latest revision as of 14:47, 16 November 2010

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page. Approved

Changes from original draft

Removed section: Provides of binary vs. sub-package with separated binary -- This was deemed more generic than perl-only and also the advice is too simplistic. Need something that explains when subpackages are preferred and when virtual provides are preferred.

Directory ownership -- wording clarifications

Filtering -- use the newly approved filtering update instead of the one based on the old perl guidelines

Restore the Makefile.PL vs Build.PL section.

Slightly reworded beginning of initial-cc sentence for clarity.

DRAFT of Perl Packaging

This document seeks to document the conventions and customs surrounding the proper packaging of perl modules in Fedora. It does not intend to cover all situations, but to codify those practices which have served the Fedora perl community well.

Perl SIG

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

New Perl packages should set the Fedora perl SIG mailing list as a member of the initial-cc list for bugzilla. This can be done by adding the user perl-sig to the initial CC list when creating the New Package SCM Request.

License tag

Perl itself is dual licensed, under both the GPL and Artistic licenses. Many perl modules follow this practice; when they do, the license tag should be filled out as "GPL+ or Artistic", not the other way around.

Note also that under the new license tag guidelines, it's important to specify "GPL+" not just "GPL" for those packages "licensed under the same terms as perl itself."

License:  GPL+ or Artistic

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/

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 buildrequire core modules explicitly, because they can move between sub-packages or disappear from core perl.

Do not explicitly buildrequire "perl-devel"
Explicitly requiring perl-devel, even when wrapped in a conditional construct, is strongly discouraged, and is generally considered a blocker at review and a packaging bug. Instead, see the next section on requiring core modules -- making sure that these core modules are BR'ed when used will pull in the correct development perl packages.


Versioned MODULE_COMPAT_ Requires

All perl modules must include the versioned MODULE_COMPAT Requires:

Requires:  perl(:MODULE_COMPAT_%(eval "`%{__perl} -V:version`"; echo $version))

This is to ensure that perl packages have a dependency on the particular version of Perl it was built against, or on a newer version of Perl that provides backward compatibility with it.

For example, perl-5.8.8 provided not only perl(:MODULE_COMPAT_5.8.8), but also perl(:MODULE_COMPAT_5.8.7), etc., because backward compatibility was guaranteed for Fedora Perl 5.8.x.

On the other hand, perl-5.10.1 implements some incompatible changes to module tree layout and libperl.so build options. Once the compatibility aids are removed, perl-5.10.1 and above will no longer provide perl(:MODULE_COMPAT_5.10.0).

In the future, it is possible that perl-5.12.2 will provide not only perl(:MODULE_COMPAT_5.12.[012]), but also perl(:MODULE_COMPAT_5.10.[123]), if the backward compatibility with all versions >= 5.10.1 is maintained.

Packages that link to libperl

Some packages link to libperl.so, usually to provide embedded perl functionality. All of these packages must also use the versioned MODULE_COMPAT Requires, because the automaticaly generated dependency on libperl.so does not include any interface version number.

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 overriden so that the additional dependencies can be filtered out. Please see [[1]] for information.

Updating deprecated methods
In the past, several other methods were given for doing this filtering. Those should be considered deprecated and packages should be updated to use the macros on [[2]] as time and the natural rebuild cycle permits.

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 search.cpan.org URL. E.g., if one were packaging the module Net::XMPP, the URL would be:

URL:            http://search.cpan.org/dist/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 buildsystem. 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 buildsystem, 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 buildsystem.

Makefile.PL vs Build.PL

Perl modules typically utilize one of two different buildsystems:

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


cpanspec

cpanspec is an excellent little tool to assist in creating Fedora-compliant packages from CPAN-based modules. Its use as a starting point is recommended (but certainly not mandated).

For more information, see: Perl/cpanspec

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.

%build
PERL5_CPANPLUS_IS_RUNNING=1 %{__perl} Makefile.PL INSTALLDIRS=vendor
make %{?_smp_mflags}