Dist::Zilla @Starter - Revision 2

I recently released revision 2 of the [@Starter] plugin bundle for Dist::Zilla. This revision brings small improvements to the default behavior, as well as the option to set a different installer plugin. In order to use the new revision, you must set the option "revision = 2" when using the bundle.

Revision 2 uses [Pod2Readme] instead of [ReadmeAnyFromPod] to generate the text README file. [ReadmeAnyFromPod] is a great and flexible plugin, but [Pod2Readme] is much simpler for the specific purpose of generating a text README. For any additional README files in other formats, I still recommend using [ReadmeAnyFromPod].

This revision also sets the option "inherit_version" in [MetaProvides::Package] to 0 by default. This makes no difference if your distribution contains uniform module versions, or for modules which have no version (they are still marked as having the distribution version unless you set "inherit_missing" to 0 as well), but if you have modules with different versions hardcoded, this will reflect that in the "provides" metadata.

The new "installer" option allows you to swap out the default [MakeMaker] installer plugin. The primary reason to do this is to use [MakeMaker::Awesome] when you need to customize portions of the generated "Makefile.PL". There is also the option to use [ModuleBuildTiny] or [ModuleBuildTiny::Fallback] if your distribution is simple enough to use Module::Build::Tiny as your installer.

I recommend upgrading to Revision 2 if you are currently using [@Starter] or [@Basic]. Check out the documentation for details, and come visit #distzilla on irc.perl.org if you have any questions or issues.


Well, the thing is, in tarballs, the POD dump is a supremely unuseful README. And the core Dist::Zilla [Readme] has the distinction of managing to be even more unuseful. Even the [Readme::Brief] output is not amazing… but it’s at least pointing in the general direction of useful.

Of course, for GitHub ’n’ such, the POD dump is useful, since GitHub doesn’t otherwise render the docs itself. But you don’t need to involve Dist::Zilla at all for that: GitHub knows how to render POD, and accepts it as a README format, so you can just symlink lib/Foo/Bar.pm (or wherever your main documentation lives) as README.pod at the root of your repository. Since POD ignores the start of the file up to the first POD command, Perl files are perfectly valid POD files. Obviously the POD as rendered by GitHub will be missing any boilerplate generated through Dist::Zilla (by Pod::Weaver or whatever); on the upside, changes to the docs will not require you to dzil build in order to propagate them into the README, nor will every change to the docs show up twice in its commit diff (once as a change to the source and once as a change to the generated README).

Now obviously the tarball shouldn’t contain both a [Readme::Brief] README as well as a README.pod containing the module source – that would be very silly. So you need to pass exclude_filename = README.pod to your [GatherDir] so that it won’t get picked up into the tarball.

That way, you get the module docs rendered on GitHub, up-to-date automatically, but also a reasonable README in the CPAN tarball.

You can see the sum total of such a setup at ap/Plack-App-Hostname.

Leave a comment

About Grinnz

user-pic I blog about Perl.