Integrating Module::Starter into Intermediate Perl, with fixes.
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.