« Dist/Zilla/PluginBundle/Starter.pm
↑ Summary
auto/share/module/Dist-Zilla-MintingProfile-Starter/default/Module.pm »
| 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> |