blib/lib/Dist/Zilla/Tutorial.pm untested

filter: Statementstmt 0.0% 0 / 8 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 2 Podpod n/a totaltotal 0.0% 0 / 10 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
1 package Dist::Zilla::Tutorial 6.040;
2 # ABSTRACT: how to use this "Dist::Zilla" thing
3  
4 use Dist::Zilla::Pragmas;
5  
6 use Carp ();
7 Carp::confess "you're not meant to use the tutorial, just read it!";
8 1;
9  
10 #pod =head1 SYNOPSIS
11 #pod
12 #pod B<BEFORE YOU GET STARTED>: Maybe you should be looking at the web-based
13 #pod tutorial instead. It's more complete. L<https://dzil.org/tutorial/start.html>
14 #pod
15 #pod Dist::Zilla builds distributions to be uploaded to the CPAN. That means that
16 #pod the first thing you'll need is some code.
17 #pod
18 #pod Once you've got that, you'll need to configure Dist::Zilla. Here's a simple
19 #pod F<dist.ini>:
20 #pod
21 #pod name = Carbon-Dating
22 #pod version = 0.003
23 #pod author = Alan Smithee <asmithee@example.org>
24 #pod license = Perl_5
25 #pod copyright_holder = Alan Smithee
26 #pod
27 #pod [@Basic]
28 #pod ; options to @Basic could go here
29 #pod
30 #pod [Prereqs]
31 #pod App::Cmd = 0.013
32 #pod Number::Nary = 0
33 #pod Sub::Exporter = 0.981
34 #pod
35 #pod It's a plain old L<INI file|https://en.wikipedia.org/wiki/INI_file>, following
36 #pod the L<grammar in Config::INI|https://metacpan.org/pod/Config::INI#GRAMMAR>.
37 #pod
38 #pod The topmost section configures Dist::Zilla itself. Here are some of the
39 #pod entries it expects:
40 #pod
41 #pod name - (required) the name of the dist being built
42 #pod version - (required) the version of the dist
43 #pod abstract - (required) a short description of the dist
44 #pod author - (optional) the dist author (you may have multiple entries for this)
45 #pod license - (required) the dist license; must be a Software::License::* name
46 #pod
47 #pod copyright_holder - (required) the entity holding copyright on the dist
48 #pod
49 #pod Some of the required values above may actually be provided by means other than
50 #pod the top-level section of the config. For example,
51 #pod L<VersionProvider|Dist::Zilla::Role::VersionProvider> plugins can
52 #pod set the version, and a line like this in the "main module" of the dist will set
53 #pod the abstract:
54 #pod
55 #pod # ABSTRACT: a totally cool way to do totally great stuff
56 #pod
57 #pod The main modules is the module that shares the same name as the dist, in
58 #pod general.
59 #pod
60 #pod Named sections load plugins, with the following rules:
61 #pod
62 #pod If a section name begins with an equals sign (C<=>), the rest of the section
63 #pod name is left intact and not expanded. If the section name begins with an at
64 #pod sign (C<@>), it is prepended with C<Dist::Zilla::PluginBundle::>. Otherwise,
65 #pod it is prepended with C<Dist::Zilla::Plugin::>.
66 #pod
67 #pod The values inside a section are given as configuration to the plugin. Consult
68 #pod each plugin's documentation for more information.
69 #pod
70 #pod The "Basic" bundle, seen above, builds a fairly normal distribution. It
71 #pod rewrites tests from F<./xt>, adds some information to POD, and builds a
72 #pod F<Makefile.PL>. For more information, you can look at the docs for
73 #pod L<@Basic|Dist::Zilla::PluginBundle::Basic> and see the plugins it includes.
74 #pod
75 #pod =head1 BUILDING YOUR DIST
76 #pod
77 #pod Maybe we're getting ahead of ourselves, here. Configuring a bunch of plugins
78 #pod won't do you a lot of good unless you know how to use them to build your dist.
79 #pod
80 #pod Dist::Zilla ships with a command called F<dzil> that will get installed by
81 #pod default. While it can be extended to offer more commands, there are two really
82 #pod useful ones:
83 #pod
84 #pod $ dzil build
85 #pod
86 #pod The C<build> command will build the distribution. Say you're using the
87 #pod configuration in the SYNOPSIS above. You'll end up with a file called
88 #pod F<Carbon-Dating-0.004.tar.gz>. As long as you've done everything right, it
89 #pod will be suitable for uploading to the CPAN.
90 #pod
91 #pod Of course, you should really test it out first. You can test the dist you'd be
92 #pod building by running another F<dzil> command:
93 #pod
94 #pod $ dzil test
95 #pod
96 #pod This will build a new copy of your distribution and run its tests, so you'll
97 #pod know whether the dist that C<build> would build is worth releasing!
98 #pod
99 #pod =head1 HOW BUILDS GET BUILT
100 #pod
101 #pod This is really more of a sketchy overview than a spec.
102 #pod
103 #pod First, all the plugins that perform the
104 #pod L<BeforeBuild|Dist::Zilla::Role::BeforeBuild> perform their C<before_build>
105 #pod tasks.
106 #pod
107 #pod The build root (where the dist is being built) is made.
108 #pod
109 #pod The L<FileGatherer|Dist::Zilla::Role::FileGatherer>s gather and inject files
110 #pod into the distribution, then the L<FilePruner|Dist::Zilla::Role::FilePruner>s
111 #pod remove some of them.
112 #pod
113 #pod All the L<FileMunger|Dist::Zilla::Role::FileMunger>s get a chance to muck about
114 #pod with each file, possibly changing its name, content, or installability.
115 #pod
116 #pod Now that the distribution is basically set up, it needs an install tool, like a
117 #pod F<Makefile.PL>. All the
118 #pod L<InstallTool|Dist::Zilla::Role::InstallTool>-performing plugins are used to
119 #pod do whatever is needed to make the dist installable.
120 #pod
121 #pod Everything is just about done. The files are all written out to disk and the
122 #pod L<AfterBuild|Dist::Zilla::Role::AfterBuild> plugins do their thing.
123 #pod
124 #pod =head1 RELEASING YOUR DIST
125 #pod
126 #pod By running C<dzil release>, you'll test your
127 #pod distribution, build a tarball of it, and upload it to the CPAN. Plugins are
128 #pod able to do things like check your version control system to make sure you're
129 #pod releasing a new version and that you tag the version you've just uploaded. It
130 #pod can also update your Changelog file, too, making sure that you don't need to
131 #pod know what your next version number will be before releasing.
132 #pod
133 #pod The final CPAN release process is implemented by the
134 #pod L<UploadToCPAN|Dist::Zilla::Plugin::UploadToCPAN> plugin. However you can
135 #pod replace it by your own to match your own (company?) process.
136 #pod
137 #pod =head1 SEE ALSO
138 #pod
139 #pod L<dzil>
140 #pod
141 #pod =cut
142  
143 __END__