Recently, I posted about some tools that are perhaps not as well known as they should be. I asked on Twitter (from @perlkiwi) for suggetsions and one was distzilla.
I didn't include it at the time in part because I knew I wanted to mint a new CPAN module and planned on using distzilla to do it, so this tale is going to cover how it works and how it helped me put a module together.
Dist::Zilla (aka distzilla aka dzil) is a command line tool to help you create and perhaps more importantly maintain packages you intend to share via CPAN.
It really does help ensure you create a good package and make it easy to maintain that module over time. Perl people know the importance of maintaining legacy code; so dzil is really valuable.
If you have never tried distzilla, then do pop over to the main website dzil.org which has a fabulous "Choose your own adventure" way of introducing you to the tool. I really like the site and LOVE a different approach to doing documentation.
In short... you start by typing something like
dzil new WebService::SmartRow, which will create a new directory for you with a dist.ini a base lib/WebService/SmartRow.pm file and a few other bits and pieces.
From here, I started a new repo on github and added the "remote" to the created directory (
git init then
git remote add origin email@example.com:lancew/WebService-SmartRow.git) after which I could happily
git add . then commit and push the changes.
The module I was writing is a small wrapper around a JSON API endpoint from https://smartrow.fit/. I just wanted to be able to access the workout data so I could munge the data in a few different ways and create some charts for myself.
The module itself is pretty simple. I used
Moo out of habit and
HTTP::Tiny for the network part and
Cpanel::JSON::XS for the JSON handling.
These are specified in the
dist.ini file as prerequisites:
[Prereqs] perl = v5.06.0 ; Cpanel::JSON::XS = 4.27 ; HTTP::Tiny = 0.080 ; Moo = 2.005004 ; namespace::clean = 0.27 ; [Prereqs / TestRequires] Test2::V0 = 0.000145 ;
You can see I have two sets of dependencies, one for the app itself and one for testing dependencies for installation. I use Test2::V0 so I pop it in there.
After having written the code and tests I wanted to upload to CPAN, this I can do with distzilla via the helpful
dzil release --trial command; which as I have already used dzil to upload modules before worked forst time. :-)
All you need to know is you pause credentials.
Having uploaded the package as trial, it was a good time to use distzilla to fine tune my module. This is super easy via the large array of plugins (and plugin bundles). The biggest problem is choosing them and dealing with the odd conflict.
A good one to start with is @TestingMania bundle includes a lot of really helpful tetsing tools. PerlTidy, PerlCritic, PodCoverage and more intricate ones to test your META info. WHich is important if the package is going to CPAN.
Add the bundle is easy, just add [@TestingMania] into your
dist.ini and run
dzil test. If the dependencies you need are not there distzilla will prompt you with the command you need which is
dzil authordeps --missing | cpanm.
I am using GitHub to host the code for this module, so I added a few plugins:
This plugin includes things like the repository url and issue tracker in the META for the package.
By inlcuding the plugin (and META infor), metacpan will know that the repo is on GitHub and present it in the UI. It also tells metacpan that I am using the issue tracker on GitHub and this prevents it from defaulting to RT.
The @Git bundle is helpful for ensuring a few Git related things are done correctly. I.e. that the repo is "clean" before you release. It also does a git tag automatically on release and pushes it to GitHub for me automatically.
This bundle did push me to update my
.gitignore file to ignore the
WebService-SmartRow-* files and directory that Dist::Zilla builds.
The last of the Git plugins is my favourite, thos one automatically bumps the version when I do a release which meant I could remove the
version = 0.001 from the dist.ini as the plugin increments based on the tags in the repo. It's cool, I like it.
I am terrible at updating teh Changes file in repositories, so I added these two plugins:
This plugin creates a
.t file that confirms you have content in the Changes file matching the next release.
This plugin is similar, in that it actually prevents you from releasing if you have not got content for the new release in the changes file.
I use both, as I like the warning early via
dzil test that the first plugin gives me and the second is there mainly in case I ever removethe first I suppose. Maybe I could should delete it?
The plugin bundles are awesome, with one exception for new dzil users. They can cause conflicts where the same plugin is referenced twice. This is not too scary once you have seen it a couple of times; but can be a stress when it hits you the first time. Just read the message and try and understand which two bundles are conflicting. You can (at least I could in @TestingMania) disable a plugin and that can solve the issue for you (I just added
disable = Test::Version ; for example immediately after the
[@TestingMania] in dist.ini; YMMV).
dzil is really helpful.
dzil test and
dzil test --release ensures my module is in a pretty good state.
dzil build (and
dzil clean) are handy for building the module so I can look at what will end up on CPAN.
dzil install installs the module like a normal cpan module; so I could use the module in a script elsewhere on my machine as if I had downloaded it from CPAN. Given this module is mainly about accessing a JSON API; this is a helpful feature to save uploading to cpan and then installing from cpan more than I need to.
Dist::Zilla can be a little overwhelming, but I find it pretty intuitive if you take small steps. I added each plugin one at a time as that helps keep the confusion to a minimum. Bundles are great; but can have conflicts. It is by it's own definition "maximum overkill"; but it's easy overkill so give it a try.
Let me know how you get on.
- Lance (perl.kiwi).