Dist/Zilla/Starter.pm untested

filter: Statementstmt 0.0% 0 / 7 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 2 Podpod n/a totaltotal 0.0% 0 / 9 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
1 package Dist::Zilla::Starter;
2  
3 use strict;
4 use warnings;
5  
6 our $VERSION = 'v6.0.2';
7  
8 1;
9  
10 =encoding UTF-8
11  
12 =head1 NAME
13  
14 Dist::Zilla::Starter - Guide to getting started with Dist::Zilla
15  
16 =head1 DESCRIPTION
17  
18 This is a guide to the inner workings of L<Dist::Zilla> for managing and
19 releasing CPAN distributions effectively, in particular with the
20 L<[@Starter]|Dist::Zilla::PluginBundle::Starter> and
21 L<[@Starter::Git]|Dist::Zilla::PluginBundle::Starter::Git> bundles. See their
22 documentation for specific usage.
23  
24 =head1 OVERVIEW
25  
26 L<Dist::Zilla> is a CPAN distribution management tool, which itself just
27 defines a set of phases relevant to the distribution building, testing, and
28 releasing process, and relies on plugins and commands for specific behavior.
29  
30 The sections below will walk through all of the essentials for using
31 Dist::Zilla effectively. If you are already familiar with general CPAN
32 distribution authoring, skip ahead to L</"DZIL AND BUNDLES">.
33  
34 =over
35  
36 =item *
37  
38 L</"CPAN DISTRIBUTIONS"> - A modern CPAN distribution should have a basic
39 well-defined structure so its contents and attributes can be recognized by CPAN
40 infrastructure and tooling.
41  
42 =item *
43  
44 L</"A BRIEF HISTORY OF AUTHORING"> - The historical progression of CPAN
45 distribution authoring tools that led to the development of Dist::Zilla.
46  
47 =item *
48  
49 L</"DZIL AND BUNDLES"> - Dist::Zilla plugin bundles that can provide a starting
50 point or a ready-made complete distribution management tool.
51  
52 =item *
53  
54 L</"THE DZIL CORE"> - The infrastructure of Dist::Zilla provides the framework
55 for plugins and commands to define specific behavior in a configurable and
56 extensible way.
57  
58 =item *
59  
60 L</"CONFIGURATION"> - Configuring a Dist::Zilla project and the plugins for it
61 to use in F<dist.ini>.
62  
63 =item *
64  
65 L</"COMMANDS"> - Taking action with a configured Dist::Zilla project via
66 built-in and installable commands.
67  
68 =item *
69  
70 L</"MINTING"> - Dist::Zilla provides the ability to generate new distribution
71 skeletons using the same core infrastructure and a minting profile.
72  
73 =item *
74  
75 L</"PHASES"> - Commands execute a series of phases, which each execute any
76 actions registered by plugins for that phase. The known phases and their usage
77 are listed here.
78  
79 =back
80  
81 =head1 CPAN DISTRIBUTIONS
82  
83 Before getting into how Dist::Zilla manages CPAN distributions, it's important
84 to understand what a CPAN distribution is. If you are here, you probably know
85 that L<CPAN|https://www.cpan.org> is a repository of Perl modules that can
86 easily be downloaded, installed, and updated. But for all of that to work
87 smoothly, these modules must be uploaded with certain structure; one can't just
88 upload a tarball of a GitHub repository and expect the CPAN toolchain to
89 understand it.
90  
91 A typical CPAN distribution layout might look something like:
92  
93 lib/
94 Some/
95 Code.pm
96 Code.pod
97 script/
98 some-code
99 t/
100 tests.t
101 Changes
102 dist.ini
103 LICENSE # generated by dzil
104 Makefile.PL # generated by dzil
105 MANIFEST # generated by dzil or other tools
106 META.json # generated by dzil or other tools
107 META.yml # generated by dzil or other tools
108 README # generated by dzil
109  
110 =head2 Releases, Distributions, and Modules
111  
112 Each tarball uploaded to CPAN is a B<release> of a B<distribution> containing
113 one or more B<modules>. Modules are declared by the L<package|perlfunc/package>
114 statement, and loaded from the filesystem by the L<use|perlfunc/use> statement.
115 Package names don't necessarily need to match the name of the file, but for the
116 file and package to work together effectively as a module, they should match,
117 with the namespace separators (C<::>) represented by directory separators in
118 the filesystem, and the module file itself having the C<.pm> file extension.
119  
120 tarball: Some-Code-1.00.tar.gz
121 release: Some-Code-1.00
122 distribution: Some-Code
123 files in lib/: Some/Code.pm, Some/Code/Other.pm
124 modules: Some::Code, Some::Code::Other
125  
126 These module names are the basis of CPAN's module index, which is maintained by
127 a system called L<PAUSE|https://pause.perl.org>. When a new release is uploaded
128 to PAUSE, it discovers all packages declared in the distribution, and
129 determines whether they are intended to be indexed, whether the uploader
130 has permissions for each package name, and whether it has a newer version than
131 any currently indexed module of that name. If so, it indexes them, so that
132 future attempts to install any of those modules by name will install that
133 release of that distribution, until such time as a new release successfully
134 indexes those names. By this method, users are able to easily install and
135 update the latest version of any module, and CPAN installers are able to
136 satisfy a distribution's prerequisites on other modules.
137  
138 =head2 Install Scripts
139  
140 After downloading a certain release of a distribution for installation, the
141 CPAN installer will consult the contents of the distribution itself to do so.
142 In order to provide infinite flexibility to how distributions can be installed,
143 a file called F<Makefile.PL> consisting of regular Perl code is run, and is
144 expected to generate a F<Makefile> that dictates the later steps of building,
145 testing, and installing. (Note: this is user-side building, a separate task
146 from the author-side distribution assembling build that will be discussed
147 later.)
148  
149 While this is traditionally implemented by a module called
150 L<ExtUtils::MakeMaker>, a slightly different process was conceived using a
151 module called L<Module::Build> (and later L<Module::Build::Tiny> and
152 L<Dist::Build>), in which a F<Build.PL> is provided which generates a perl
153 script named F<Build> to perform these tasks instead.
154  
155 While both methods have been extended and improved using different modules, for
156 Dist::Zilla authors the details of user-side installation are largely
157 unimportant unless custom configuration or installation tasks are required. As
158 such, Dist::Zilla generates this install script itself via C<-InstallTool>
159 plugins such as L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker> or
160 L<[ModuleBuildTiny]|Dist::Zilla::Plugin::ModuleBuildTiny>.
161  
162 =head2 Metadata
163  
164 In addition to the install script, the other important component of a
165 well-formed CPAN distribution is the metadata. This was originally contained in
166 a file called F<META.yml>, which implemented the CPAN meta spec versions 1.0
167 through 1.4. When L<CPAN meta spec version 2|CPAN::Meta::Spec> was conceived,
168 it was implemented using a new file called F<META.json> that can coexist with
169 the legacy format. In either format, this metadata describes aspects of the
170 distribution as a whole such as name, author(s), prerequisites, repository and
171 bugtracking resources, and optionally the name and version of each included
172 package (which if provided will be trusted over PAUSE's own manual scan).
173  
174 Well-formed metadata is important to both ensuring the modules can be correctly
175 and painlessly installed, and to provide important ancillary information to
176 tools such as L<MetaCPAN|https://metacpan.org> when it displays the
177 distribution. Dist::Zilla generates these files as well via the
178 L<[MetaYAML]|Dist::Zilla::Plugin::MetaYAML> and
179 L<[MetaJSON]|Dist::Zilla::Plugin::MetaJSON> plugins.
180  
181 =head2 Other Files
182  
183 The meat of the CPAN distribution, the code, tests, and documentation, are
184 generally expected to be in a certain structure.
185  
186 =over
187  
188 =item *
189  
190 Modules (F<.pm>) and documentation (F<.pod>) are placed in the F<lib/>
191 directory, with a file path corresponding to the module name, as they will be
192 ultimately installed.
193  
194 =item *
195  
196 Tests (F<.t>) are placed in the F<t/> directory, and do not get installed.
197  
198 =item *
199  
200 Executables to install have no strict convention but are usually put in F<bin/>
201 or F<script/>.
202  
203 =back
204  
205 You may see distributions with these important files in other places, usually
206 because they predate these conventions or for compatibility with old versions
207 of ExtUtils::MakeMaker that required F<.xs> files to be in the distribution
208 root. Other directories may be included in the CPAN distribution, but have no
209 specific meaning by default to the standard installers.
210  
211 =head1 A BRIEF HISTORY OF AUTHORING
212  
213 =head2 ExtUtils::MakeMaker
214  
215 $ perl Makefile.PL && make manifest && make disttest && make dist
216 $ cpan-upload Some-Code-1.00.tar.gz
217  
218 Originally, the same tool which allows end users to install the distribution
219 would also be used by the author to manage it and create a release.
220 L<ExtUtils::MakeMaker> contains author-side configuration and commands such as
221 C<make manifest> and C<make dist>. Indeed, many authors still use this as their
222 primary authoring tool, though its close-to-metal nature and extreme backcompat
223 requirements have led many to develop more author-friendly wrappers.
224  
225 =head2 Module::Install
226  
227 One such wrapper is L<Module::Install>. This differed from many attempts in
228 that it was designed to bundle itself with the distribution, so the end user
229 would install using the bundled code rather than relying on the interface of
230 their possibly outdated ExtUtils::MakeMaker. This was a revolutionary idea and
231 the wrapper interface was well liked, but it introduced other problems.
232  
233 Due to being bundled with the release, it too became outdated when the author
234 did not regularly release new versions of the distribution, so bugs would
235 linger forever that the end user could not workaround by updating their own
236 toolchain. This was notably a significant issue when Perl 5.26 stopped loading
237 modules from the current working directory by default, a mechanism which the
238 Module::Install code bundled with hundreds of distributions relied upon to load
239 itself.
240  
241 Additionally, it had a rudimentary plugin system but no way to formally declare
242 what plugins a distribution was using, meaning that given a
243 Module::Install-based Makefile.PL, the author or contributor would have to
244 guess what plugins needed to be installed or bundled for the end user to make
245 it work. On top of (or perhaps due to) these problems, it has become mostly
246 unmaintained and thus has fallen far behind the progress of the CPAN toolchain.
247  
248 =head2 Module::Build
249  
250 $ perl Build.PL && perl Build && perl Build manifest && perl Build disttest && perl Build dist
251 $ cpan-upload Some-Code-1.00.tar.gz
252  
253 L<Module::Build> was created to provide a C<make>-free alternative to
254 L<ExtUtils::MakeMaker>, with the additional goal of being more modern and
255 easier to customize and add features to. Unfortunately this proved to be a
256 lofty goal, as due to widespread use it succumbed to the same stagnation as
257 ExtUtils::MakeMaker; it too has become extremely complex and obtuse, is no
258 longer driven to evolve by its primary author, and must maintain backcompat
259 religiously. This has weakened most of its benefits considerably, as
260 ExtUtils::MakeMaker still remains more compatible with ancient end-user Perls,
261 but Module::Build is still used by some who prefer its interface over
262 ExtUtils::MakeMaker, or who have complicated compilation requirements that are
263 easier to customize in Module::Build.
264  
265 =head2 Module::Build::Tiny and Dist::Build
266  
267 $ mbtiny test --release
268 $ mbtiny upload
269  
270 More recently, L<Module::Build::Tiny> was created as an extremely simple
271 implementation of the F<Build.PL> spec pioneered by Module::Build. A
272 significant reason for its simplicity is that unlike the previously mentioned
273 tools, it is B<only> an install tool; it does not provide any authoring
274 features. A separate tool called L<mbtiny> provides these features in a minimal
275 package, or it works great with dedicated authoring tools like Dist::Zilla.
276  
277 L<Dist::Build> is a more extensible and customizable install-only
278 implementation of the F<Build.PL> spec, and similarly leaves authoring features
279 up to tools like Dist::Zilla.
280  
281 =head2 Dist::Zilla
282  
283 $ dzil release
284  
285 Dist::Zilla came to be one of the first widespread author-side-only tools, and
286 as such it shed many of the limitations of its overworked predecessors.
287  
288 =over
289  
290 =item *
291  
292 It does not have to concern itself with minimalism and compatibility, because
293 the end user does not need to install it; it can use everything that modern
294 CPAN has to offer, and rely on the generated install file to be lightweight and
295 compatible if needed.
296  
297 =item *
298  
299 The generated install file also has a simpler job, as it doesn't need to
300 generate the distribution's metadata aside from any dynamic prerequisites, or
301 implement any author-side commands for convenience, as Dist::Zilla does these
302 tasks itself.
303  
304 =item *
305  
306 Learning from the mistakes of Module::Install, it has a formal plugin
307 configuration system, and can deterministically find what plugins are needed to
308 build (assemble) the distribution, using the
309 L<C<dzil authordeps>|Dist::Zilla::App::Command::authordeps> command.
310  
311 =back
312  
313 =head1 DZIL AND BUNDLES
314  
315 Dist::Zilla is a CPAN distribution authoring framework. At its core, it only
316 organizes tasks; it requires plugins to implement the specifics of assembling,
317 testing, and releasing the distribution. The author can manually specify in
318 F<dist.ini> the set of plugins that suits their needs, or even write new
319 plugins, but there are also ready-made tools built upon it that require very
320 little study to use effectively.
321  
322 =head2 [@Basic]
323  
324 The most basic of these is the core bundle
325 L<[@Basic]|Dist::Zilla::PluginBundle::Basic>. This bundle contains plugins to
326 perform the most common authoring tasks, and is used throughout most tutorials
327 including L<dzil.org|http://dzil.org>, but it has unfortunately become outdated
328 in practice and, as of this writing, cannot be fixed without breaking changes.
329  
330 =head2 Milla and Minilla
331  
332 The L<prolific creator|https://metacpan.org/author/MIYAGAWA> of L<cpanm>,
333 L<Carton>, L<cpanfile>, and other wonderful convenience tools created a
334 "convention over configuration" tool called L<Dist::Milla>. Dist::Milla is a
335 bundle, minting profile, and command-line wrapper of Dist::Zilla which provides
336 a complete opinionated authoring tool. It requires a certain modernized
337 structure, and in return removes all of the guesswork in managing and releasing
338 distributions.
339  
340 Its sister project L<Minilla> is also notable for being able to achieve almost
341 the same tasks without a dependency on Dist::Zilla, though as a result it
342 cannot be extended with arbitrary plugins from the Dist::Zilla ecosystem.
343  
344 =head2 [@Starter] and [@Starter::Git]
345  
346 The L<[@Starter]|Dist::Zilla::PluginBundle::Starter> bundle and minting profile
347 is a middle ground. The intention is to provide an unopinionated tool which can
348 be used effectively in almost any distribution similarly to C<[@Basic]>, but
349 that can be updated at the author's request to newer conventions, and can also
350 optionally provide further modern convenience with slightly stricter and more
351 opinionated structural requirements.
352  
353 The L<[@Starter::Git]|Dist::Zilla::PluginBundle::Starter::Git> bundle and
354 minting profile are variants that provide some extra functionality for a
355 git-based workflow.
356  
357 =head1 THE DZIL CORE
358  
359 Dist::Zilla relies almost entirely on its plugin and command system to provide
360 specific functionality, but these are tied together by a few core systems.
361  
362 =head2 Dist::Zilla
363  
364 The L<Dist::Zilla> object itself is at the basis of the whole operation. It
365 contains the basic properties of the distribution, such as name, version, and
366 the whole set of plugins that will be run. But it doesn't do anything itself;
367 it is up to other parts of the system to utilize this information.
368  
369 =head2 Dist::Zilla::Dist::Builder
370  
371 The L<Dist::Zilla::Dist::Builder> object is a subclass of the main Dist::Zilla
372 object that is able to B<build> (assemble) the distribution by executing all of
373 the relevant plugins. Additionally it can execute the appropriate plugins to
374 test, install, or release the built distribution. These functions are generally
375 accessed via L</COMMANDS>, and primarily work by executing L</PHASES> in a
376 certain order for each task.
377  
378 =head2 Dist::Zilla::Dist::Minter
379  
380 The L<Dist::Zilla::Dist::Minter> object is another subclass of the main
381 Dist::Zilla object, this time to implement the L</MINTING> of new distributions
382 using minting profiles. It is much simpler as it only does one thing: run all
383 of the plugins in the minting profile by executing a few L</PHASES>, and write
384 out the resulting build to the filesystem.
385  
386 =head2 Dist::Zilla::MVP::Assembler
387  
388 L<Dist::Zilla::MVP::Assembler> is a L<Config::MVP>-based configuration parser
389 that is the core of how Dist::Zilla's plugin L</CONFIGURATION> works. It reads
390 a F<dist.ini> (or F<profile.ini>) and constructs the requested set of plugins
391 and configuration, and stores them in the Dist::Zilla object.
392  
393 =head2 Dist::Zilla::App
394  
395 L<Dist::Zilla::App> is an L<App::Cmd>-based command system that allows the
396 L<dzil> script to load and execute any installed L</COMMANDS> in the
397 C<Dist::Zilla::App::Command> namespace, such as
398 L<< C<dzil test>|Dist::Zilla::App::Command::test >> or
399 L<< C<dzil regenerate>|Dist::Zilla::App::Command::regenerate >>.
400  
401 =head2 Test::DZil
402  
403 L<Test::DZil> is a framework that facilitates testing of Dist::Zilla builds and
404 minting profiles. It contains constructors for test-appropriate subclasses of
405 Dist::Zilla::Dist::Builder and Dist::Zilla::Dist::Minter, as well as for
406 generating simple F<dist.ini> text. This is primarily useful for plugin bundle
407 and minting profile authors, so is out of scope for this document.
408  
409 =head1 CONFIGURATION
410  
411 The Dist::Zilla configuration for a distribution is a standard INI-format file
412 called F<dist.ini> in the root of the distribution.
413  
414 name = Acme-Dist-Name ; comment
415 [MyPlugin]
416 configuration = for MyPlugin
417 ; line comment
418  
419 =over
420  
421 =item *
422  
423 Section names, which are lines in square brackets (C<[]>), indicate plugins to
424 be used.
425  
426 =item *
427  
428 Lines in the format C<name = value> specify configuration.
429  
430 =item *
431  
432 The "main section", meaning any configuration before the first section name,
433 configures the distribution as a whole, with directives such as C<name> and
434 C<version>.
435  
436 =item *
437  
438 Each following section both adds a plugin to be used, and allows configuration
439 to be passed to that plugin.
440  
441 =item *
442  
443 Comments start with a semicolon.
444  
445 =back
446  
447 There are a few conventions in section names that Dist::Zilla recognizes in
448 order to determine how plugins are loaded. The standard section name will
449 simply be appended to C<Dist::Zilla::Plugin::> to form the class name of the
450 plugin to load. If the section name ends in C</> followed by other text, that
451 will be the alias for that instance of the plugin; otherwise, the alias is the
452 same as the section name. This is important because each section in an INI file
453 is unique, and because plugins are looked up by this name, so to include the
454 same plugin twice, at least one of them must have an alias. Additionally, some
455 plugins use the alias to set configuration, but this is a bit overly magical.
456  
457 [MyPlugin / FirstPlugin]
458 [MyPlugin / SecondPlugin]
459  
460 If the section name is prefixed with C<@>, this indicates a plugin bundle,
461 which is prepended with C<Dist::Zilla::PluginBundle::> to be loaded. A plugin
462 bundle is essentially just a plugin that can only load other plugins, rather
463 than taking action in any build phases.
464  
465 [@MyBundle]
466 configuration = for the bundle
467  
468 Plugins loaded by the bundle will be given an alias in the form
469 C<@BundleName/PluginName> and so will not conflict if the same plugin is loaded
470 elsewhere.
471  
472 A similar convention with the prefix of C<-> indicates a role to be prefixed
473 with C<Dist::Zilla::Role::>, but these are not configured directly in
474 F<dist.ini>; roles implement both general interfaces of Dist::Zilla as well as
475 the L</PHASES> in which plugins take action.
476  
477 If the section name is prefixed with C<=>, the section name is used as the
478 plugin class name directly, without prepending C<Dist::Zilla::Plugin::>.
479  
480 [=Full::Plugin::Class::Name]
481  
482 The configuration for each section is generally passed directly to that plugin
483 or bundle to handle however it wishes, but a special configuration key
484 C<:version> is recognized in each section by Dist::Zilla itself. In the main
485 section, it will require at least that version of Dist::Zilla to build the
486 distribution; in a plugin or bundle section, it will require at least that
487 version of the plugin or bundle.
488  
489 :version = 6.0
490 [MyPlugin]
491 :version = 0.005
492  
493 Of additional note is that the C<[@Starter]> bundles (as well as L<Dist::Milla>)
494 compose the
495 L<-PluginBundle::PluginRemover|https://metacpan.org/pod/Dist::Zilla::Role::PluginBundle::PluginRemover>
496 and
497 L<-PluginBundle::Config::Slicer|https://metacpan.org/pod/Dist::Zilla::Role::PluginBundle::Config::Slicer>
498 roles, which allow plugins within a bundle to be configured directly in
499 F<dist.ini>.
500  
501 The PluginRemover role recognizes the C<-remove> option and omits those plugins
502 by name, and the Config::Slicer role recognizes options in the form of
503 C<PluginName.option> and passes through that option to the named plugin within
504 the bundle. This prevents having to add manual pass-through code to the bundle
505 for every possible option that the included plugins accept.
506  
507 But there is an oddity with options that can be specified multiple times, as
508 Config::Slicer does not know in advance which options allow this. See
509 L<Config::MVP::Slicer/"CONFIGURATION SYNTAX"> for full details on config
510 slicing.
511  
512 [@Starter]
513 regular = configuration
514 -remove = Test::Compile
515 GatherDir.exclude_filename[a] = foo
516 GatherDir.exclude_filename[b] = bar
517  
518 Occasionally you may need to specify an authordep (module required for using
519 the F<dist.ini> itself) that is not explicitly listed as a plugin. For this
520 purpose, authordeps can additionally be specified as comments.
521  
522 ; authordep Pod::Weaver::PluginBundle::DAGOLDEN
523  
524 =head1 COMMANDS
525  
526 After setting up the configuration, Dist::Zilla operations are executed by
527 running commands. Dist::Zilla has a pluggable command system with many core
528 commands and many more available from CPAN. There are only a few needed for the
529 basic operation of creating and releasing a distribution.
530  
531 =head2 Running Tests
532  
533 One of the most common commands is
534 L<< C<dzil test>|Dist::Zilla::App::Command::test >>, a wrapper of
535 L<Dist::Zilla::Dist::Builder/test>. This will assemble the distribution in a
536 temporary directory, and then run the configure, build, and test phases of the
537 L<CPAN::Meta::Spec/Phases>. It will also execute any other C<-TestRunner> phase
538 plugins such as L<[RunExtraTests]|Dist::Zilla::Plugin::RunExtraTests>, which
539 runs any author-side tests from the C<xt/> directory. The C<--release> option
540 can be passed to run release tests in addition to standard and author tests.
541  
542 =head2 Uploading a Release
543  
544 The second most important command is
545 L<< C<dzil release>|Dist::Zilla::App::Command::release >>, a wrapper of
546 L<Dist::Zilla::Dist::Builder/release>. This will assemble the distribution, run
547 standard/author/release tests, and then upload the archive to PAUSE with the
548 C<-Releaser> phase. The C<--trial> option will mark the upload as a trial
549 release, so it will not be indexed as stable.
550  
551 =head2 Installing Dependencies
552  
553 Two commands that are important when starting work on a Dist::Zilla
554 distribution for the first time are
555 L<< C<dzil authordeps>|Dist::Zilla::App::Command::authordeps >> and
556 L<< C<dzil listdeps>|Dist::Zilla::App::Command::listdeps >>. C<authordeps>
557 lists the Dist::Zilla plugins required by the F<dist.ini>, and C<listdeps>
558 lists the dependencies of the distribution itself. The output of each can be
559 piped into L<cpanm> to install any modules needed for working on the
560 distribution. Note that the C<authordeps> requirements must be installed for
561 most other C<dzil> commands to succeed, including C<listdeps>. The non-core
562 command L<< C<dzil installdeps>|Dist::Zilla::App::Command::installdeps >> wraps
563 this process into a single command.
564  
565 =head2 Other Commands
566  
567 =over
568  
569 =item *
570  
571 L<C<dzil build>|Dist::Zilla::App::Command::build> assembles the distribution
572 and stores the tarball and extracted directory locally.
573  
574 =item *
575  
576 L<C<dzil run>|Dist::Zilla::App::Command::run> builds the distribution
577 temporarily like C<dzil test> but runs the supplied command instead of running
578 tests.
579  
580 =item *
581  
582 L<C<dzil install>|Dist::Zilla::App::Command::install> assembles the
583 distribution temporarily and then installs it to the system with a CPAN
584 installer.
585  
586 =item *
587  
588 L<C<dzil clean>|Dist::Zilla::App::Command::clean> cleans up the Dist::Zilla
589 F<.build> directory and any built distribution directories or archives.
590  
591 =back
592  
593 =head2 Regenerating Files
594  
595 Another common task is to copy updated versions of generated files from the
596 distribution build to the source tree, such as generated F<README> files.
597 Often this is done whenever the distribution is built with
598 L<[CopyFilesFromBuild]|Dist::Zilla::Plugin::CopyFilesFromBuild>, but this can
599 be disruptive when trying to run tests or other operations. By using the
600 L<regenerate|Dist::Zilla::PluginBundle::Starter/regenerate> option for
601 C<[@Starter]>, or the L<[Regenerate]|Dist::Zilla::Plugin::Regenerate> or
602 L<[Regenerate::AfterReleasers]|Dist::Zilla::Plugin::Regenerate::AfterReleasers>
603 plugins, the L<< C<dzil regenerate>|Dist::Zilla::App::Command::regenerate >>
604 command can be used for this purpose instead, so the distribution can be built
605 without modifying the source tree, and the files can be regenerated as needed.
606  
607 =head1 MINTING
608  
609 Dist::Zilla is primarily a distribution management tool, but it leverages the
610 same command and plugin system to provide a minting tool. A minting profile
611 can be configured to automatically set up the basic framework for new
612 distributions. The L<Starter|Dist::Zilla::MintingProfile::Starter> and
613 L<Starter::Git|Dist::Zilla::MintingProfile::Starter::Git> minting profiles
614 provide a starting point and instructions for customizing profiles, as does
615 L<dzil.org|http://dzil.org/tutorial/minting-profile.html>.
616  
617 A minting profile primarily consists of a F<profile.ini> file, which uses the
618 same configuration format as F<dist.ini> described in L</"CONFIGURATION">. It
619 may include other files as needed by the profile, including a F<dist.ini>
620 plugins configuration template, module template, or a skeleton distribution
621 directory of templates.
622  
623 Some metadata such as author, license, and copyright is set from global
624 configuration by default for new distributions. This configuration is stored in
625 C<~/.dzil/config.ini>, which can be initialized using the
626 L<< C<dzil setup>|Dist::Zilla::App::Command::setup >> command.
627  
628 The process of minting a distribution primarily involves the
629 L<< C<dzil new>|Dist::Zilla::App::Command::new >> command, invoked with the
630 name of the module or distribution to create. By default, the local profile in
631 C<~/.dzil/profiles/default> will be used if present, and otherwise a default
632 C<[@Basic]> profile. The C<-p> option can be used to specify the profile name
633 to use, and the C<-P> option can specify an installed minting profile module as
634 the provider. The default profile or provider can be set in the
635 C<~/.dzil/config.ini> configuration as documented for C<dzil new>.
636  
637 =head1 PHASES
638  
639 Plugins included in F<dist.ini> are ordered, but they do not necessarily
640 execute in order. L<Dist::Zilla::Dist::Builder> or L<Dist::Zilla::Dist::Minter>
641 methods as invoked by L</COMMANDS> will run one or more B<phases>, which will
642 execute any code that plugins have registered for that phase, in the order
643 those plugins were used. The command
644 L<< C<dzil dumpphases>|Dist::Zilla::App::Command::dumpphases >> can be used to
645 see a full listing of the phases that the plugins in a F<dist.ini> will run in.
646  
647 A property of phases that many plugins find useful is that successive phases
648 will only run if previous phases completed successfully. For example, the
649 L</"BeforeRelease"> phase will only run if the distribution was successfully
650 built, the L</"Releaser"> phase will only run if the BeforeRelease checks and
651 release tests succeeded, and the L</"AfterRelease"> phase will only run if the
652 release was successful.
653  
654 =head2 BeforeBuild
655  
656 The distribution build consists of several phases, starting with
657 L<-BeforeBuild|Dist::Zilla::Role::BeforeBuild>, for any build preparation. No
658 plugins in C<[@Starter]> execute during this phase by default.
659  
660 =head2 BeforeMint
661  
662 The L<-BeforeMint|Dist::Zilla::Role::BeforeMint> phase is executed at the
663 beginning of the minting process for a new distribution source tree instead of
664 C<-BeforeBuild>.
665  
666 =head2 FileGatherer
667  
668 In the L<-FileGatherer|Dist::Zilla::Role::FileGatherer> phase, many plugins add
669 files to the distribution tree being assembled; in C<[@Starter]> this includes
670 the plugins L<[GatherDir]|Dist::Zilla::Plugin::GatherDir>
671 (L<[Git::GatherDir]|Dist::Zilla::Plugin::Git::GatherDir> in
672 C<[@Starter::Git]>), L<[MetaYAML]|Dist::Zilla::Plugin::MetaYAML>,
673 L<[MetaJSON]|Dist::Zilla::Plugin::MetaJSON>,
674 L<[License]|Dist::Zilla::Plugin::License>,
675 L<[Pod2Readme]|Dist::Zilla::Plugin::Pod2Readme>,
676 L<[PodSyntaxTests]|Dist::Zilla::Plugin::PodSyntaxTests>,
677 L<[Test::ReportPrereqs]|Dist::Zilla::Plugin::Test::ReportPrereqs>,
678 L<[Test::Compile]|Dist::Zilla::Plugin::Test::Compile>,
679 L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker> (or the configured installer
680 plugin), and L<[Manifest]|Dist::Zilla::Plugin::Manifest>. This phase is also
681 executed by the minting process to add files to a new distribution source tree.
682  
683 =head2 EncodingProvider
684  
685 In the L<-EncodingProvider|Dist::Zilla::Role::EncodingProvider> phase, a plugin
686 may set the encoding for gathered files. No plugins in C<[@Starter]> execute
687 during this phase by default. This phase is also executed by the minting
688 process.
689  
690 =head2 FilePruner
691  
692 In the L<-FilePruner|Dist::Zilla::Role::FilePruner> phase, gathered files may
693 be removed from the distribution. In C<[@Starter]> this is handled by the
694 plugins L<[PruneCruft]|Dist::Zilla::Plugin::PruneCruft>,
695 L<[PruneFiles]|Dist::Zilla::Plugin::PruneFiles>, and
696 L<[ManifestSkip]|Dist::Zilla::Plugin::ManifestSkip>. This phase is also
697 executed by the minting process.
698  
699 =head2 FileMunger
700  
701 In the L<-FileMunger|Dist::Zilla::Role::FileMunger> phase, files in the
702 distribution may be modified. In C<[@Starter]> the plugin
703 L<[Test::Compile]|Dist::Zilla::Plugin::Test::Compile> runs during this phase
704 in order to update its test file to test all gathered modules and scripts. With
705 the L<managed_versions|Dist::Zilla::PluginBundle::Starter/managed_versions>
706 option, the L<[RewriteVersion]|Dist::Zilla::Plugin::RewriteVersion> and
707 L<[NextRelease]|Dist::Zilla::Plugin::NextRelease> plugins also operate during
708 this phase. This phase is also executed by the minting process.
709  
710 =head2 AfterMint
711  
712 The L<-AfterMint|Dist::Zilla::Role::AfterMint> phase is executed to conclude
713 the minting process for a new distribution source tree. The build process
714 instead continues with several more phases.
715  
716 =head2 PrereqSource
717  
718 In the L<-PrereqSource|Dist::Zilla::Role::PrereqSource> phase, plugins can add
719 prerequisites to the distribution. In C<[@Starter]> the plugins
720 L<[PodSyntaxTests]|Dist::Zilla::Plugin::PodSyntaxTests>,
721 L<[Test::ReportPrereqs]|Dist::Zilla::Plugin::Test::ReportPrereqs>,
722 L<[Test::Compile]|Dist::Zilla::Plugin::Test::Compile>, and
723 L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker> (or the configured installer
724 plugin) add prereqs during this phase. Plugins used to configure the
725 distribution's prereqs such as L<[Prereqs]|Dist::Zilla::Plugin::Prereqs>,
726 L<[Prereqs::FromCPANfile]|Dist::Zilla::Plugin::Prereqs::FromCPANfile>,
727 L<[PrereqsFile]|Dist::Zilla::Plugin::PrereqsFile>, and
728 L<[AutoPrereqs]|Dist::Zilla::Plugin::AutoPrereqs> will normally run in this
729 phase.
730  
731 =head2 InstallTool
732  
733 In the L<-InstallTool|Dist::Zilla::Role::InstallTool> phase, the installer's
734 F<Makefile.PL> or F<Build.PL> is generated in the distribution. In
735 C<[@Starter]>, L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker> or the configured
736 installer plugin handles this phase.
737  
738 =head2 AfterBuild
739  
740 The L<-AfterBuild|Dist::Zilla::Role::AfterBuild> phase concludes the
741 distribution build, for any post-build cleanup. No plugins in C<[@Starter]>
742 execute during this phase by default.
743  
744 =head2 BuildRunner
745  
746 The L<-BuildRunner|Dist::Zilla::Role::BuildRunner> phase executes the configure
747 and build phases of the L<CPAN::Meta::Spec/Phases> (not to be confused with the
748 Dist::Zilla build that has assembled the distribution). This is primarily used
749 to prepare the distribution for testing or installing. In C<[@Starter]>,
750 L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker> or the configured installer
751 plugin handles this phase.
752  
753 =head2 TestRunner
754  
755 The L<-TestRunner|Dist::Zilla::Role::TestRunner> phase executes the test phase
756 of the L<CPAN::Meta::Spec/Phases> and runs any author-side testing. In
757 C<[@Starter]>, L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker> (or the configured
758 installer plugin) and L<[RunExtraTests]|Dist::Zilla::Plugin::RunExtraTests>
759 handle this phase.
760  
761 =head2 BeforeArchive
762  
763 The L<-BeforeArchive|Dist::Zilla::Role::BeforeArchive> phase is executed after
764 assembling the distribution and before packaging it into an archive, such as
765 for the L<< C<dzil build>|Dist::Zilla::App::Command::build >> command or before
766 releasing. No plugins in C<[@Starter]> execute during this phase by default.
767  
768 =head2 BeforeRelease
769  
770 The L<-BeforeRelease|Dist::Zilla::Role::BeforeRelease> phase prepares a built
771 distribution for release. In C<[@Starter]>, the plugins
772 L<[TestRelease]|Dist::Zilla::Plugin::TestRelease>,
773 L<[ConfirmRelease]|Dist::Zilla::Plugin::ConfirmRelease>, and
774 L<[UploadToCPAN]|Dist::Zilla::Plugin::UploadToCPAN> (to ensure PAUSE username
775 and password are available) execute during this phase. In C<[@Starter::Git]>,
776 the plugin L<[Git::Check]|Dist::Zilla::Plugin::Git::Check> executes during this
777 phase. Other pre-release checks like
778 L<[CheckChangesHasContent]|Dist::Zilla::Plugin::CheckChangesHasContent> also
779 execute in this phase.
780  
781 =head2 Releaser
782  
783 The L<-Releaser|Dist::Zilla::Role::Releaser> phase releases the distribution to
784 CPAN. In C<[@Starter]>, L<[UploadToCPAN]|Dist::Zilla::Plugin::UploadToCPAN> (or
785 L<[FakeRelease]|Dist::Zilla::Plugin::FakeRelease>) handles this phase.
786  
787 =head2 AfterRelease
788  
789 The L<-AfterRelease|Dist::Zilla::Role::AfterRelease> phase concludes the
790 distribution release process, performing any post-release cleanup or tagging.
791 No plugins in C<[@Starter]> execute during this phase by default. With the
792 L<managed_versions|Dist::Zilla::PluginBundle::Starter/managed_versions> option,
793 the L<[NextRelease]|Dist::Zilla::Plugin::NextRelease> and
794 L<[BumpVersionAfterRelease]|Dist::Zilla::Plugin::BumpVersionAfterRelease>
795 plugins execute during this phase. With the
796 L<regenerate|Dist::Zilla::PluginBundle::Starter/regenerate> option, the
797 L<[CopyFilesFromRelease]|Dist::Zilla::Plugin::CopyFilesFromRelease> plugin
798 executes during this phase. In C<[@Starter::Git]>, the plugins
799 L<[Git::Commit]|Dist::Zilla::Plugin::Git::Commit>,
800 L<[Git::Tag]|Dist::Zilla::Plugin::Git::Tag>, and
801 L<[Git::Push]|Dist::Zilla::Plugin::Git::Push> execute during this phase.
802  
803 =head2 NameProvider
804  
805 The L<-NameProvider|Dist::Zilla::Role::NameProvider> phase executes when
806 required rather than at a specific time, to determine the name of the
807 distribution. No plugins in C<[@Starter]> execute during this phase by default,
808 and the name can be provided directly by setting C<name> in F<dist.ini>. The
809 L<[NameFromDirectory]|Dist::Zilla::Plugin::NameFromDirectory> plugin can act as
810 a name provider.
811  
812 =head2 VersionProvider
813  
814 The L<-VersionProvider|Dist::Zilla::Role::VersionProvider> phase executes when
815 required rather than at a specific time, to determine the version of the
816 distribution. No plugins in C<[@Starter]> execute during this phase by default,
817 and the version can be provided directly by setting C<version> in F<dist.ini>.
818 With the
819 L<managed_versions|Dist::Zilla::PluginBundle::Starter/managed_versions> option,
820 the L<[RewriteVersion]|Dist::Zilla::Plugin::RewriteVersion> plugin acts as the
821 version provider.
822  
823 =head2 ReleaseStatusProvider
824  
825 The L<-ReleaseStatusProvider|Dist::Zilla::Role::ReleaseStatusProvider> phase
826 executes when required rather than at a specific time, to determine the
827 L<CPAN::Meta::Spec/release_status> of the distribution. No plugins in
828 C<[@Starter]> execute during this phase by default. It defaults to C<stable>
829 and is usually set to another value by passing the C<--trial> option to
830 L<< C<dzil release>|Dist::Zilla::App::Command::release >> or using a version
831 containing an underscore, but can also be set by a plugin in this phase.
832  
833 =head2 LicenseProvider
834  
835 The L<-LicenseProvider|Dist::Zilla::Role::LicenseProvider> phase executes when
836 required rather than at a specific time, to determine the license of the
837 distribution. No plugins in C<[@Starter]> execute during this phase by default,
838 and the license can be provided directly by setting C<license> in F<dist.ini>,
839 or otherwise guessed from the main module's POD.
840  
841 =head2 MetaProvider
842  
843 The L<-MetaProvider|Dist::Zilla::Role::MetaProvider> phase executes when
844 required rather than at a specific time, to generate the distribution's
845 L<CPAN metadata|CPAN::Meta::Spec>. In C<[@Starter]>, the
846 L<[MetaConfig]|Dist::Zilla::Plugin::MetaConfig>,
847 L<[MetaProvides::Package]|Dist::Zilla::Plugin::MetaProvides::Package>, and
848 L<[MetaNoIndex]|Dist::Zilla::Plugin::MetaNoIndex]> plugins provide metadata in
849 this phase. Other metadata providers like
850 L<[MetaResources]|Dist::Zilla::Plugin::MetaResources> also execute in this
851 phase.
852  
853 =head2 ShareDir
854  
855 The L<-ShareDir|Dist::Zilla::Role::ShareDir> phase executes when required
856 rather than at a specific time, to configure sharedirs for installation. In
857 C<[@Starter]>, the L<[ShareDir]|Dist::Zilla::Plugin::ShareDir> plugin
858 configures a distribution sharedir if present.
859  
860 =head2 ExecFiles
861  
862 The L<-ExecFiles|Dist::Zilla::Role::ExecFiles> phase executes when required
863 rather than at a specific time, to configure files for installation as
864 executables. In C<[@Starter]>, the L<[ExecDir]|Dist::Zilla::Plugin::ExecDir>
865 plugin marks a directory as containing executables, which may be used by
866 installer plugins such as L<[MakeMaker]|Dist::Zilla::Plugin::MakeMaker>.
867  
868 =head2 Regenerator
869  
870 The L<-Regenerator|Dist::Zilla::Role::Regenerator> phase is a non-core
871 extension which executes when
872 L<< C<dzil regenerate>|Dist::Zilla::App::Command::regenerate >> is run,
873 intended for generating files in the source tree outside of a standard
874 distribution build. With the
875 L<regenerate|Dist::Zilla::PluginBundle::Starter/regenerate> option for
876 C<[@Starter]>, the
877 L<[Regenerate::AfterReleasers]|Dist::Zilla::Plugin::Regenerate::AfterReleasers>
878 plugin promotes
879 L<[CopyFilesFromRelease]|Dist::Zilla::Plugin::CopyFilesFromRelease> to also
880 execute during this phase.
881  
882 =head1 AUTHOR
883  
884 Dan Book <dbook@cpan.org>
885  
886 =head1 COPYRIGHT AND LICENSE
887  
888 This software is Copyright (c) 2016 by Dan Book.
889  
890 This is free software, licensed under:
891  
892 The Artistic License 2.0 (GPL Compatible)
893  
894 =head1 SEE ALSO
895  
896 L<Dist::Zilla::PluginBundle::Starter>,
897 L<Dist::Zilla::PluginBundle::Starter::Git>,
898 L<Dist::Zilla::MintingProfile::Starter>,
899 L<Dist::Zilla::MintingProfile::Starter::Git>