NEILB's Blog

If you release a module to CPAN, and are hopeful that other modules on CPAN might use it, then it's good practice to specify the minimum version of Perl required to run your module. The other way of thinking about it: what's the oldest version of Perl your module supports? Here I'll discuss why you should do this, and how.

Why bother?

When one Perl module relies on a bunch of CPAN modules, the versions of Perl supported by that module is the intersection of the versions of Perl supported by it and all the modules it relies on. This is illustrated by the following graphic:

Even if you've written your module to work on Perl 5.6, if one of the modules you rely on only supports 5.10+, then so do you.

So when picking modules to rely on, your should check to see whether versions of Perl they support, and what that matches your preference.

Specifying the minimum Perl version for your distribution is being considerate of others who might end up relying on your module, either directly or indirectly.

There are three ways you can specify the version of Perl your module supports:

1. In the documentation. This is the first place people are likely to look when considering using your module.
2. In the code. See below.
3. In the metadata for the distribution, also described below.

Min perl version in code

If you support Perl 5.8.1+, then at the top of each module you just add the following:

use 5.8.1;

or

use 5.008001;

When people are looking at your code, they can see the minimum version of Perl required. Also some build tools can use this line to fill in the distribution metadata as well, as outlined below.

You should also put the same line at the head of Makefile.PL or Build.PL, if you're using one or both of those, as it will let smoke testers know if the version of Perl being tested isn't supported.

Min perl version in metadata

To help the toolchain, and ad-hoc analytics, the minimum version of Perl supported should be specified in the META.json and/or META.yml included with your release.

This basically involves specifying 'perl' as a required prereq, but exactly how you do that depends on the dist builder you use.

Dist::Zilla

In Dist::Zilla, if you specify the min perl version in your code, then as long as your dist.ini is pulling in the AutoPrereqs plugin, the metadata version will be based on what your code says.

ExtUtils::MakeMaker

There are two ways you can do it with ExtUtils::MakeMaker. The first is to just specify the version of perl in the PREREQ hash:

PREREQ_PM      => {
    perl => '5.6.1',
    ...
},

The other, recommended, way is to use the MIN_PERL_VERSION key:

MIN_PERL_VERSION => '5.6.1',

The advantage of the second approach is that you can decide whether an earlier version of Perl should result in a warning or fatal error, using the PREREQ_FATAL key.

Module::Build

If you're using Module::Build in a Build.PL, then you just add perl to the requires hash:

my $build = Module::Build->new(
    module_name => 'Foo::Bar',
    requires => {
        'perl' => '5.6.1',
        ...
    },
);

Module::Install

If you're using Module::Install, you can either use the perl_version command:

perl_version '5.006

But better, you can add use 5.xxx; to your code and then can use the perl_version_from command instead:

perl_version_from 'lib/Foo/Bar.pm'

What version should you specify?

Well first off, you can't specify an older version than is required by any of the modules you rely on, unless they're optional dependencies.

You can run the perlver script on your code:

perlver lib/Foo/Bar.pm

It will tell you the minimum version required by your code. It doesn't recognise all features from recent Perl releases, but feel free to harrangue the current maintainer about that.

The other way to approach this is to do a release of your module that doesn't specify a minimum perl version, and see what kind of results you get from matrix.cpantesters.org.

Seen on CPAN

32.8% of CPAN distributions have minimum Perl version specified in the dist metadata. I was going to include a break-down of the different strings seen, but good grief what a mess. I'll provide more on this in a follow-up post.

The most common string is "5.006".

Thanks

Thank you to BINGOS, HAARG, KENTNL, and ETHER, who answered questions on IRC related to this post.