Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Creating Perl modules with Dist::Zilla

795 views

Published on

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

Published in: Technology, Art & Photos
  • Be the first to comment

Creating Perl modules with Dist::Zilla

  1. 1. Creating Perl modules with Dist::Zilla Mark Gardner mjgardner@cpan.org
  2. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 15. Thank you! http://dzil.org/ https://metacpan.org/module/Dist::Zilla https://github.com/rjbs/dist-zilla/ irc://irc.perl.org/distzilla

×