.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Dist::Zilla::Tutorial 3pm" .TH Dist::Zilla::Tutorial 3pm "2020-11-04" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dist::Zilla::Tutorial \- how to use this "Dist::Zilla" thing .SH "VERSION" .IX Header "VERSION" version 6.017 .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fB\s-1BEFORE YOU GET STARTED\s0\fR: Maybe you should be looking at the web-based tutorial instead. It's more complete. .PP Dist::Zilla builds distributions to be uploaded to the \s-1CPAN.\s0 That means that the first thing you'll need is some code. .PP Once you've got that, you'll need to configure Dist::Zilla. Here's a simple \&\fIdist.ini\fR: .PP .Vb 5 \& name = Carbon\-Dating \& version = 0.003 \& author = Alan Smithee \& license = Perl_5 \& copyright_holder = Alan Smithee \& \& [@Basic] \& \& [Prereqs] \& App::Cmd = 0.013 \& Number::Nary = 0 \& Sub::Exporter = 0.981 .Ve .PP The topmost section configures Dist::Zilla itself. Here are some of the entries it expects: .PP .Vb 5 \& name \- (required) the name of the dist being built \& version \- (required) the version of the dist \& abstract \- (required) a short description of the dist \& author \- (optional) the dist author (you may have multiple entries for this) \& license \- (required) the dist license; must be a Software::License::* name \& \& copyright_holder \- (required) the entity holding copyright on the dist .Ve .PP Some of the required values above may actually be provided by means other than the top-level section of the config. For example, VersionProvider plugins can set the version, and a line like this in the \*(L"main module\*(R" of the dist will set the abstract: .PP .Vb 1 \& # ABSTRACT: a totally cool way to do totally great stuff .Ve .PP The main modules is the module that shares the same name as the dist, in general. .PP Named sections load plugins, with the following rules: .PP If a section name begins with an equals sign (\f(CW\*(C`=\*(C'\fR), the rest of the section name is left intact and not expanded. If the section name begins with an at sign (\f(CW\*(C`@\*(C'\fR), it is prepended with \f(CW\*(C`Dist::Zilla::PluginBundle::\*(C'\fR. Otherwise, it is prepended with \f(CW\*(C`Dist::Zilla::Plugin::\*(C'\fR. .PP The values inside a section are given as configuration to the plugin. Consult each plugin's documentation for more information. .PP The \*(L"Basic\*(R" bundle, seen above, builds a fairly normal distribution. It rewrites tests from \fI./xt\fR, adds some information to \s-1POD,\s0 and builds a \&\fIMakefile.PL\fR. For more information, you can look at the docs for \&\f(CW@Basic\fR and see the plugins it includes. .SH "BUILDING YOUR DIST" .IX Header "BUILDING YOUR DIST" Maybe we're getting ahead of ourselves, here. Configuring a bunch of plugins won't do you a lot of good unless you know how to use them to build your dist. .PP Dist::Zilla ships with a command called \fIdzil\fR that will get installed by default. While it can be extended to offer more commands, there are two really useful ones: .PP .Vb 1 \& $ dzil build .Ve .PP The \f(CW\*(C`build\*(C'\fR command will build the distribution. Say you're using the configuration in the \s-1SYNOPSIS\s0 above. You'll end up with a file called \&\fICarbon\-Dating\-0.004.tar.gz\fR. As long as you've done everything right, it will be suitable for uploading to the \s-1CPAN.\s0 .PP Of course, you should really test it out first. You can test the dist you'd be building by running another \fIdzil\fR command: .PP .Vb 1 \& $ dzil test .Ve .PP This will build a new copy of your distribution and run its tests, so you'll know whether the dist that \f(CW\*(C`build\*(C'\fR would build is worth releasing! .SH "HOW BUILDS GET BUILT" .IX Header "HOW BUILDS GET BUILT" This is really more of a sketchy overview than a spec. .PP First, all the plugins that perform the BeforeBuild perform their \f(CW\*(C`before_build\*(C'\fR tasks. .PP The build root (where the dist is being built) is made. .PP The FileGatherers gather and inject files into the distribution, then the FilePruners remove some of them. .PP All the FileMungers get a chance to muck about with each file, possibly changing its name, content, or installability. .PP Now that the distribution is basically set up, it needs an install tool, like a \&\fIMakefile.PL\fR. All the InstallTool\-performing plugins are used to do whatever is needed to make the dist installable. .PP Everything is just about done. The files are all written out to disk and the AfterBuild plugins do their thing. .SH "RELEASING YOUR DIST" .IX Header "RELEASING YOUR DIST" By running \f(CW\*(C`dzil release\*(C'\fR, you'll test your distribution, build a tarball of it, and upload it to the \s-1CPAN.\s0 Plugins are able to do things like check your version control system to make sure you're releasing a new version and that you tag the version you've just uploaded. It can also update your Changelog file, too, making sure that you don't need to know what your next version number will be before releasing. .PP The final \s-1CPAN\s0 release process is implemented by the UploadToCPAN plugin. However you can replace it by your own to match your own (company?) process. .SH "SEE ALSO" .IX Header "SEE ALSO" dzil .SH "AUTHOR" .IX Header "AUTHOR" Ricardo \s-1SIGNES\s0 😏 .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2020 by Ricardo \s-1SIGNES.\s0 .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.