brian d foy

Working on a book about something is one of the best ways to discover issues with interfaces. When I have to explain some process and think about all the ways that things can go wrong so I can make the explanation as bulletproof as possible, all sorts of issues pop up.

I'm working on the distributions part of the next edition of Intermediate Perl. All of the h2xs stuff is being shoved into a couple of paragraphs and everything else now uses Module::Starter. I'm not a particular fan of the module (I have my own: Distribution::Cooker), but I do think it's the best thing to use if you don't know what you want to use.

I also want to integrate distributions more widely into the discussion of everything else, and take a very mild, test-driven development like approach. That way, distributions isn't some afterthought chapter at the end of the book like it is now. Part of that means that as we build up a distribution, I need to use Module::Starter to add a new module to an existing distribution.

Module::Starter::Smart can handle this mostly. It uses the Module::Starter templates to create the new module file and fix up the other files. Most of it works quite nicely. The problem shows up because Module::Starter::Smart relies on Module::Starter::Simple to handle recreating MANIFEST. In its create_MANIFEST, it takes in a list of files that it thinks it created and uses that to make MANIFEST.

For a working distribution, this doesn't quite work. I might have added files or excluded files with MANIFEST.SKIP. Since create_MANIFEST only considers the files that Module::Starter creates, it recreates MANIFEST with only the files it thnks it created. If I used a Module::Starter plug-in that changed the build file template so it changed the manifest target, none of that happens.

I could just re-build the MANIFEST, but I know to do that because I already know how all this works. For the readers of Intermediate Perl just beginning their education about Perl distributions, it's another step to explain and a lot to explain at that.

The real fix for any system like this is to never make more files than you need to create yourself. Once any build system gets to the point where it can generate files, like MANIFEST or META.yml, it's time to trust the system to make them for you.

This isn't a big deal. I've filed RT ticket 53330 for the problem and people are working on it.

In the meantime, I've created Module::Starter::AddModule as a Module::Starter::Smart subclass to provide a proper create_MANIFEST. I don't intend for Module::Starter::AddModule to stick around, but its create_MANIFEST can work its way upstream if people like. Until then, it's what I'm using for Intermediate Perl.