What is the real purpose of the $VERSION variable in Perl?

Question

I've read that it's considered good practice to always include a $VERSION number in all of your Perl scripts, but I never fully understood the purpose.

What do you really gain by including a version number in your script?

Answer 1

You can specify a minimum version of a module in the use statement:

 use Foo 1.23;

When Perl loads that module, it looks at the $VERSION variable to check that it's equal to or greater than that number. That way you get the right set of features and fixes.

The CPAN clients use $VERSION to determine if you are up-to-date or if you should install the latest version of a module.

For programs or scripts, you typically don't need a $VERSION.

Answer 2

Only modules, and only those pushed to CPAN really benefit from specifying $VERSION. There's not much use for it in a script except to use a familiar name rather than inventing a new one if you want the script's version to be accessible.

Primary uses:

• CPAN uses it as the version of the distribution, allowing it to index different versions of the same distribution.

• cpan and cpanm uses it to check if an installed module is of sufficiently high level to meet the required minimum version of a dependency.

As brian d foy mentioned, it can also be checked by use Foo 1.23;, but most people avoid this in favour of specifying the required versions of dependencies in their distribution's META file. This allows cpan and cpanm to update the dependency if needed (where use using use Foo 1.23; would cause the installation to fail during testing). Due to the lack of use of the feature, it's hardly a primary use.