What is the correct way to add a utility module to a CPAN distribution?

Question

I would like to factor out some of the stuff in Crypt::SSLeay's Makefile.PL into a couple of separate classes. These classes would only be used by Makefile.PL. As such, I do want them

1. not to be indexed by the PAUSE indexer
2. not to be installed as part of the module.

Should I just put them in inc the way Module::Install does? What else should I pay attention to?

Answer 1

PAUSE looks for a no_index parameter in the META.yml file (specifications: v1.4, v2). The default META.yml that ExtUtils::MakeMaker makes contains

no_index:
    directory:
        - t
        - inc

but you can add more data to it if you'd like

    package:
        - Some::Package::Used::For::Building::But::Not::To::Be::Installed
    file:
        - a-file/with/a/package/statement/that-should-be/ignored.pm

Answer 2

There are really two issues here. One is to prevent PAUSE from indexing the extra modules in your distribution so they don't show up in the 02packages, and how not to fool a user into installing them.

The PAUSE answer is a combination of the proper fix, the no_index stuff, and the old folklore of faking out mldistwatch. PAUSE wants to discover which packages are in your distro. It looks for the package on the same line as a namespace. If it's not on the same line, PAUSE passes over it. So, you'll see in some older "hidden" modules lines like:

 package # separate lines get past PAUSE
      Some::Helper::Module;

If you like looking behind the curtain, the relevant code is in PAUSE::mldistwatch::filter_pms() in (the PAUSE github repo).

The other problem is to not install extra things that are in the distro. Indexing has nothing to do with that. Build files move a lot of stuff into blib (the build library) to prepare them for installation. Anything ending up in there gets installed. The trick is to not let the builder put your helper modules in there. That's usually not a problem as long as you don't put them at the top level of your distro or in the lib directory.