I’ve recently seen or heard a lot of discussion about how to make Perl and CPAN even better, but I feel strongly that we need a more a formal definition of packages, modules and distributions so that there is common language and understanding for the current semantics. Only then, do I think we can have meaningful discussions of potential changes.
With that in mind, here is my best understanding of the as-is state of Perl 5.
-
A package is a Perl namespace as specified using the package keyword. Packages may have (but are not required to have) a version number. The version number of a package is the value in the package variable $VERSION, which is set during runtime. $VERSION should not be altered once set. I will refer to a well-formed package as one which provides a $VERSION.
-
A module is a Perl file with a “.pm” extension. A module’s name is a Perl namespace that maps to a relative file-path to the module by replacing namespace separators (:: and ‘) with path separators and appending “.pm”. A module contains zero or more _package_s. Compiling the module should return a true value. The module must return a true value when loaded via use() or require(). (([Thank you, Ben])) __ A module’s version number is that which is parsed and returned from the file by MM->parse_version() as provided by ExtUtils::MakeMaker. I will refer to a well-formed module as one which contains a well-formed package with the same name as the module name and the same version as the module version.
-
A distribution is an archive file containing zero or more modules. A distribution file is uniquely identified by a file-path of the form AUTHOR/NAME-VERSION.SUFFIX (i.e. as exists on CPAN). A distribution’s name and version are parsed from the basename of the archive file. ((This requires substantial heuristics. See CPAN::DistnameInfo for a relatively canonical approach.)) I will refer to a well-formed distribution as one meeting the following criteria: (a) it contains a well-formed module, M; (b) replacing the namespace separators in module M’s name with dashes gives the distribution name; and (c) the distribution version is equal to module M’s version.
I plan to use these definitions going forward as I discuss the evolution of CPAN, so I would welcome any feedback on whether these definitions seem consistent with how Perl 5 and CPAN work today and whether the “well-formed” designations are clear and appropriate.