Packages, modules and distributions

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