Brief introduction on why and how to use the Dist::Zilla suite of tools to create, build, test and release Perl software

1. Creating Perl modules
with Dist::Zilla
Mark Gardner
mjgardner@cpan.org

2. What is this about?
• Perl modules are a set of related functions in a file.
• They’re designed to be reusable by other modules or programs.
• Therefore useful to you:
• Collect useful functions in one place, stop copying and pasting code
• And useful to others:
• You too can be a CPAN author!
• There are many many ways to create modules; this is how I do it.
• Dist::Zilla makes it really easy.
• If you want to do it a different way go ahead – TIMTOWTDI

3. How easy is this?
• One-time setup:
cpan -i Dist::Zilla or ppm install Dist-Zilla
installs many (160) prerequisites
dzil setup
• Make a new module:
dzil new My::Module
cd My-Module
dzil build

4. What does Dist::Zilla do?
• Builds scaffolding and boilerplate for a CPAN-ready Perl module
distribution
• README, LICENSE, MANIFEST, META.yml and/or META.json,
Makefile.PL or Build.PL, lib/, bin/, t/ …
• Manages the building, testing, installation and release of distributions
during development
• Extensible through plugins and plugin bundles to handle other repetitive
tasks
• Prerequsites
• Version numbers
• Documentation
• Testing
• Saves you (the developer) time and stress

5. What doesn’t Dist::Zilla do?
• It’s not a system for users to install released or published code.
• It doesn’t make you write object (or any other kind of) oriented code.
• It doesn’t make you change existing code if you don’t want to.

6. Put your modules in lib/
• In lib/My/Module.pm:
use strict;
use warnings;
package My::Module;
# your code goes here
1;
• Scripts go in bin/ if you have them.

7. The dist.ini file
name = My-Module
author = Mark Gardner <mjgardner@cpan.org>
license = Perl_5
copyright_holder = Aria Systems, Inc.
copyright_year = 2013
version = 0.001
[@Basic]

8. The Basic plugin bundle
• Does not change your code
• Generates MANIFEST, Makefile.PL, META.yml, README
• Allows easy release to CPAN
• If you want to do more, add/change plugins in dist.ini
• perldoc Dist::Zilla::PluginBundle::Basic for more

9. Handling prerequisites in dist.ini
• Manually:
[Prereqs]
Sub::Exporter = 0.979
Acme::ProgressBar = 0
• Automatically:
[AutoPrereqs]
• Use both if AutoPrereqs doesn’t do what you want.

10. Handling documentation with
Pod::Weaver
• In dist.ini:
[PodWeaver]
• Makes Pod sections for
NAME, VERSION, AUTHOR, COPYRIGHT
AND LICENSE
• Gathers things like methods into a
METHODS section
• In your code:
use strict;
use warnings;
package My::Module;
# ABSTRACT: my cool module
=head1 SYNOPSIS
use My::Module;
=method foo
=cut
# your code goes here
1;

11. Managing version numbers (several
plugins)
• Putting them in the right places
• [PkgVersion] and [OurPkgVersion]
• [NextRelease]
• [Git::Tag]
• Automatically manage numbering
• [AutoVersion]
• [VersionFromModule]
• [Git::NextVersion]

12. Testing
• prove -lr t
• Runs all tests in t/ using libraries in lib/
• Does not take advantage of Dist::Zilla changes to your code
• But it’s fast!
• dzil test
• Builds a temporary copy and runs its tests
• Should do exactly what end-user testing will do
• Can be slower since it’s building the distribution first

13. Releasing to CPAN
[TestRelease]
[ConfirmRelease]
[UploadToCPAN]
• PAUSE credentials in either ~/.pause or ~/.dzil/config.ini
dzil release
• For trial (not for automatic update) releases:
dzil release --trial

14. Many many more techniques and plugins
• Custom profiles for multiple dist.ini and directory layouts
• Pod::Weaver plugins for custom sections, encodings, etc.
• Integration with Git, GitHub, Twitter, TravisCI, etc.
• Automatic generation of web services clients
• Building for other package managers like RPM amd Dpkg
• Commands and tests for Perl::Tidy, Devel::Cover, Perl::Critic, etc.
• Dist::Zilla users often become Dist::Zilla extenders

15. Thank you!
http://dzil.org/
https://metacpan.org/module/Dist::Zilla
https://github.com/rjbs/dist-zilla/
irc://irc.perl.org/distzilla