NEILB's Blog

A recent change to PAUSE means that examples included in a CPAN release are no longer scanned for package names to index, and aren't checked for permissions. This simplifies the rules about indexing and permissions, and also helps us resolve some historical permissions conflicts. In this post I'll present the problem(s), explain what has changed, and what this means for CPAN authors.

What happens when you upload a distribution?

When you upload a tarball to PAUSE, the following things happen:

• It is put into your CPAN author directory on the CPAN master. If your PAUSE id were ZAPHOD, then your author directory would be authors/id/Z/ZA/ZAPHOD. Author directories are copied onto all CPAN mirrors.
• PAUSE unpacks your tarball and looks for package statements in .pm files. A module called Foobar will usually (but not always) be in lib/Foobar.pm, and somewhere near the start you'll find the line package Foobar, but it may have additional cuckoo packages defined in the same file.
• PAUSE checks whether you have permission for each of the packages it found, and if you do (this step might involve giving you ownership of the package, if this was the first-ever upload), then each package will appear in the CPAN Index.

There are a bunch of other things that might happen; you can read about some of them here: what happens when you upload to CPAN?

Skipping parts of a distribution

When looking for .pm files, PAUSE was already skipping the following directories in a distribution:

• t and xt: libraries in test directories are just used when running tests, and aren't installed.
• inc is the conventional directory where you put modules needed by your module builder / installer, particularly Module::Install.
• similarly, local, perl5, and fatlib are all used by some part of the toolchain, and any modules in there aren't installed.

So from this, you can see that the general rule should really be: if a module isn't going to be installed, then it shouldn't be considered for indexing.

Problem 1: example modules being indexed

Many distributions include example modules and scripts, to illustrate how to use the public module(s) in the distribution (ie those that are installed). For example, Chris Prather's XML-Toolkit distribution contains a lot of public modules, but also many example modules, such as XML::AIML::Li. Because example modules were being indexed, this latter module was appearing in the CPAN Index:

XML::AIML::Li  undef  P/PE/PERIGRIN/XML-Toolkit-0.15.tar.gz

This meant you could try and install it with a CPAN client:

cpan XML::AIML::Li

The cpan client would find XML::AIML::Li in the index, notice that it hasn't been installed, map it to the release shown above, and install that. But because example modules aren't installed, XML::AIML::Li wasn't installed. If you run that cpan command again, it will see that the module still hasn't been installed, so will install XML-Toolkit again. Oops.

Problem 2: permissions for example modules

Because example modules were being indexed, they were first being checked for permissions. Unsurprisingly people often use similar names for example modules, like Example1.pm, or Testclass.pm. If you were the first person to use that name, then you'd get ownership, and your module would be listed in the index. Anyone else using the same example package name would get an email from PAUSE telling them they didn't have permission for that package (the rest of their distribution would probably be indexed ok).

In the past someone else might have included an example called example1.pm (note the difference in case), and because PAUSE used to treat package names case sensitively, those were treated separately for permissions and the index. Now they're treated as the same namespace for permissions, resulting in a conflict. That's what led me here: I'm working on resolving all such conflicts in PAUSE permissions.

But really there's no need to enforce permissions on example modules, as we've already established, because they're not installed.

PAUSE no longer indexes example modules

When looking for packages to index (and thus check for permissions), PAUSE now no longer considers example modules. Specifically, it ignores .pm files in the following directories:

• examples
• example
• ex
• eg
• demo

In most cases you don't need to do anything as a result of this change, and if you have a conflict case, then I'll be getting in touch with you eventually anyway.

There are other directories we should be ignoring as well, to make sure that what gets indexed is aligned with what gets installed. That's now on my long-term todo list to loop back around on, but first I need to finish working on the permissions conflicts.

If you want to include example modules in your distribution, please use one of the directory names listed above. I use examples, as I think that's clearest.