NAME

Dist::Zilla::PluginBundle::Starter - A minimal Dist::Zilla plugin bundle

SYNOPSIS

  ; dist.ini
  name    = My-Cool-Distribution
  author  = Example Jones <jones@example.com>
  license = Perl_5
  copyright_holder = Example Jones
  copyright_year   = 2017
  version = 0.001
  
  [@Starter]           ; all that is needed to start
  revision = 3         ; always defaults to revision 1
  
  ; configuring examples
  installer = ModuleBuildTiny
  -remove = GatherDir  ; to use [Git::GatherDir] instead, for example
  ExecDir.dir = script ; change the directory used by [ExecDir]
  managed_versions = 1 ; uses the main module version, and bumps module versions after release
  regenerate = LICENSE ; copy LICENSE to root after release or dzil regenerate

DESCRIPTION

The [@Starter] plugin bundle for Dist::Zilla is designed to do the minimal amount of work to release a complete distribution reliably. It is similar in purpose to [@Basic], but with additional features to stay up to date and allow greater customization. The selection of included plugins is intended to be unopinionated and unobtrusive, so that it is usable for any well-formed CPAN distribution. If you're just getting started with Dist::Zilla, check out the tutorials at http://dzil.org.

Migrating from [@Basic] is easy for most cases. Most of the bundle is the same, so just make sure to remove any extra plugins that [@Starter] already includes, and configure the included plugins if needed (see "CONFIGURING"). Migrating a more complex set of plugins, including some that interact with the additional generated files, may require more careful consideration.

[@Starter] composes the PluginRemover and Config::Slicer roles to make it easier to customize and extend. Also, it supports bundle revisions specified as an option, in order to incorporate future changes to distribution packaging and releasing practices. Existing revisions will not be changed to preserve backwards compatibility.

The FAKE_RELEASE environment variable is supported as in Dist::Milla and Minilla. It replaces the [UploadToCPAN] plugin with [FakeRelease], to test the release process (including any version bumping and commits!) without actually uploading to CPAN.

  $ FAKE_RELEASE=1 dzil release

For a detailed overview of how this plugin bundle works, see "PHASES".

For one-line initialization of a new [@Starter]-based distribution, try Dist::Zilla::MintingProfile::Starter.

For a variant of this bundle with built-in support for a git-based workflow, see [@Starter::Git].

Another simple way to use Dist::Zilla is with Dist::Milla, an opinionated bundle that requires no configuration and performs all of the tasks in "EXTENDING" by default.

OPTIONS

[@Starter] currently only has a few direct options; it can be further configured by the composed roles, as in "CONFIGURING".

revision

  [@Starter]
  revision = 2

Selects the revision to use, from "REVISIONS". Defaults to revision 1.

installer

Requires revision 2 or higher.

  [@Starter]
  revision = 2
  installer = ModuleBuildTiny

  [@Starter]
  revision = 2
  installer = MakeMaker::Awesome
  MakeMaker::Awesome.WriteMakefile_arg[0] = (clean => { FILES => 't/generated/*' })

The default installer is [MakeMaker], which works with no extra configuration for most cases. The installer option can be used to replace it with one of the following supported installers, which can then be configured in the same way as shown in "CONFIGURING".

[MakeMaker::Awesome] is useful if you need to customize the generated Makefile.PL.

[ModuleBuildTiny] will generate a simple Build.PL using Module::Build::Tiny, but this may not work correctly with old versions of the CPAN.pm installer or if you use features incompatible with Module::Build::Tiny.

[ModuleBuildTiny::Fallback] generates a more complex Build.PL that uses Module::Build::Tiny by default, but falls back to Module::Build on old versions of the CPAN.pm installer that don't understand configure dependencies.

When using a Module::Build::Tiny-based installer, the [ExecDir] plugin will be set to mark the script/ directory for executables instead of the default bin/.

managed_versions

Requires revision 3 or higher.

  [@Starter]
  revision = 3
  managed_versions = 1

With managed_versions set, [@Starter] will use an additional set of plugins to manage your module versions when releasing, while leaving them in place in the source files.

[RewriteVersion] will read the distribution version from the main module, and set all other module versions to match in the build. [NextRelease] replaces {{$NEXT}} in your Changes file with a line containing the distribution version and build date/time. Finally, [BumpVersionAfterRelease] will bump the versions in your module files after a release.

When using this option, you must have the distribution version set in your main module in a form like our $VERSION = '1.234';, rather than in dist.ini. Other modules and scripts must also have similar version declarations to be updated appropriately. You can set your distribution's version manually by changing the version of your main module, or by setting the V environment variable when building or releasing. See the documentation for each plugin mentioned above for details on configuring them, which can be done in the usual config-slicing way as shown in "CONFIGURING".

This option also enables the inherit_version option for [MetaProvides::Package] since all module versions are matched to the main module in this configuration.

regenerate

Requires revision 3 or higher.

  [@Starter]
  revision = 3
  regenerate = INSTALL
  regenerate = README

The specified generated files will be copied to the root directory upon release using [CopyFilesFromRelease], and excluded from the [GatherDir] plugin in use. Note: if you remove the built-in [GatherDir] plugin to use one separately, you must exclude copied files from that plugin yourself. Additionally, [Regenerate::AfterReleasers] is applied to [CopyFilesFromRelease] to allow these files to be generated and copied on demand outside of a release using dzil regenerate.

REVISIONS

The [@Starter] plugin bundle supports the following revisions.

Revision 1

Revision 1 is the default and is equivalent to using the following plugins:

[GatherDir]
[MetaYAML]
[MetaJSON]
[License]
[ReadmeAnyFromPod]
[PodSyntaxTests]
[Test::ReportPrereqs]
[Test::Compile]
  xt_mode = 1
[MakeMaker]
[Manifest]
[PruneCruft]
[ManifestSkip]
[RunExtraTests]
[TestRelease]
[ConfirmRelease]
[UploadToCPAN]
[MetaConfig]
[MetaNoIndex]
  directory = t
  directory = xt
  directory = inc
  directory = share
  directory = eg
  directory = examples
[MetaProvides::Package]
[ShareDir]
[ExecDir]

This revision differs from [@Basic] as follows:

Revision 2

Revision 2 is similar to Revision 1, with these differences:

  • Sets the option "inherit_version" in [MetaProvides::Package] to 0 by default, so that provides metadata will use individual module versions if they differ from the distribution version.

  • [Pod2Readme] is used instead of [ReadmeAnyFromPod] to generate the plaintext README, as it is a simpler plugin for this purpose. It takes the same filename and source_filename options, but does not allow further configuration, and does not automatically use a .pod file as the source.

  • The "installer" option is now supported to change the installer plugin.

Revision 3

Revision 3 is similar to Revision 2, but additionally supports the "managed_versions" and "regenerate" options, and variant bundles like [@Starter::Git].

CONFIGURING

By using the PluginRemover or Config::Slicer role options, the [@Starter] bundle's included plugins can be customized as desired. Here are some examples:

GatherDir

If the distribution is using git source control, it is often helpful to replace the default [GatherDir] plugin with [Git::GatherDir]. (Note: The [@Starter::Git] variant of this bundle uses [Git::GatherDir] by default.)

  [Git::GatherDir]
  [@Starter]
  -remove = GatherDir

The included [GatherDir] plugin can alternatively be configured directly. (See "CONFIGURATION SYNTAX" in Config::MVP::Slicer for an explanation of the subscripts for slicing array attributes.)

  [@Starter]
  GatherDir.include_dotfiles = 1
  GatherDir.exclude_filename[0] = foo_bar.txt
  GatherDir.prune_directory[] = ^temp

Readme

The [Pod2Readme] or [ReadmeAnyFromPod] plugin (depending on bundle revision) generates a plaintext README from the POD text in the distribution's "main_module" in Dist::Zilla by default, but can be configured to look elsewhere. The standard README should always be plaintext, but in order to generate a non-plaintext README in addition, [ReadmeAnyFromPod] can simply be used separately. Note that POD-format READMEs should not be included in the distribution build because they will get indexed and installed due to an oddity in CPAN installation tools.

  [@Starter]
  revision = 2
  Pod2Readme.source_filename = bin/foobar
  
  [ReadmeAnyFromPod / Markdown_Readme]
  type = markdown
  filename = README.md
  
  [ReadmeAnyFromPod / Pod_Readme]
  type = pod
  location = root ; do not include pod readmes in the build!
  phase = release ; avoid changing files in the root with dzil build or dzil test
  [Regenerate::AfterReleasers] ; allows regenerating with dzil regenerate
  plugin = Pod_Readme

MetaNoIndex

The distribution may include additional files or directories that should not have their contents indexed as CPAN modules. (See "CONFIGURATION SYNTAX" in Config::MVP::Slicer for an explanation of the subscripts for slicing array attributes.)

  [@Starter]
  MetaNoIndex.file[0] = eggs/FooBar.pm
  MetaNoIndex.directory[a] = eggs
  MetaNoIndex.directory[b] = bacon

MetaProvides

The [MetaProvides::Package] plugin will use the distribution's version (as set in dist.ini or by a plugin) as the version of each module when populating the provides metadata by default. If the distribution does not have uniform module versions, the plugin can be configured to reflect each module's hardcoded version where available, by setting the inherit_version option to 0 (the default in bundle "Revision 2").

  [@Starter]
  MetaProvides::Package.inherit_version = 0 ; default in revision 2

With this option set to 0, it will use the main distribution version as a fallback for any module where a version is not found. This can also be overridden, so that if no version is found for a module, no version will be specified for it in metadata, by setting inherit_missing to 0 as well.

  [@Starter]
  MetaProvides::Package.inherit_version = 0
  MetaProvides::Package.inherit_missing = 0

ExecDir

Some distributions use the script/ directory instead of bin/ (the [ExecDir] default) for executable scripts.

  [@Starter]
  ExecDir.dir = script

Versions

When using the "managed_versions" option, the added plugins can be directly configured in various ways to suit your versioning needs.

  [@Starter]
  revision = 3
  managed_versions = 1
  
  ; configuration examples
  RewriteVersion.global = 1
  BumpVersionAfterRelease.munge_makefile_pl = 0
  NextRelease.filename = ChangeLog
  NextRelease.format = %-5v %{yyyy-MM-dd}d

PHASES

The plugins in this bundle, and any additional plugins you include in dist.ini, each execute code within one or more phases when a Dist::Zilla command such as dzil test is run. You can see a full listing of the phases used by the plugins in your dist.ini with the command dzil dumpphases.

BeforeBuild

The distribution build consists of several phases, starting with -BeforeBuild. No plugins in this bundle execute during this phase by default.

FileGatherer

In the -FileGatherer phase, many plugins add files to the distribution; in [@Starter] this includes the plugins [GatherDir], [MetaYAML], [MetaJSON], [License], [Pod2Readme], [PodSyntaxTests], [Test::ReportPrereqs], [Test::Compile], [MakeMaker] (or the configured installer plugin), and [Manifest].

EncodingProvider

In the -EncodingProvider phase, a plugin may set the encoding for gathered files. No plugins in this bundle execute during this phase by default.

FilePruner

In the -FilePruner phase, gathered files may be excluded from the distribution. In [@Starter] this is handled by the plugins [PruneCruft] and [ManifestSkip].

FileMunger

In the -FileMunger phase, files in the distribution may be modified. In [@Starter] the plugin [Test::Compile] runs during this phase in order to update its test file to test all gathered modules and scripts. When using the "managed_versions" option, the [RewriteVersion] and [NextRelease] plugins also operate during this phase.

PrereqSource

In the -PrereqSource phase, plugins can add prerequisites to the distribution. In [@Starter] the plugins [PodSyntaxTests], [Test::ReportPrereqs], [Test::Compile], and [MakeMaker] (or the configured installer plugin) add prereqs during this phase.

InstallTool

In the -InstallTool phase, the installer's Makefile.PL or Build.PL is generated in the distribution. In [@Starter], [MakeMaker] or the configured installer plugin handles this phase.

AfterBuild

The -AfterBuild phase concludes the distribution build. No plugins in this bundle execute during this phase by default.

BuildRunner

The -BuildRunner phase executes the configure and build phases of the "Phases" in CPAN::Meta::Spec in a built distribution. In [@Starter], [MakeMaker] or the configured installer plugin handles this phase.

TestRunner

The -TestRunner phase executes the test phase of the "Phases" in CPAN::Meta::Spec. In [@Starter], [MakeMaker] (or the configured installer plugin) and [RunExtraTests] handle this phase.

BeforeRelease

The -BeforeRelease phase prepares a built distribution for release. In [@Starter], the plugins [TestRelease], [ConfirmRelease], and [UploadToCPAN] (to ensure PAUSE username and password are available) execute during this phase. In [@Starter::Git], the plugin [Git::Check] executes during this phase.

Releaser

The -Releaser phase releases the distribution to CPAN. In [@Starter], [UploadToCPAN] (or [FakeRelease]) handles this phase.

AfterRelease

The -AfterRelease phase concludes the distribution release process. No plugins in this bundle execute during this phase by default. When using the "managed_versions" option, the [NextRelease] and [BumpVersionAfterRelease] plugins execute during this phase. When using the "regenerate" option, the [CopyFilesFromRelease] plugin executes during this phase. In [@Starter::Git], the plugins [Git::Commit], [Git::Tag], and [Git::Push] execute during this phase.

MetaProvider

The -MetaProvider phase executes when required rather than at a specific time. In [@Starter], the [MetaConfig], [MetaProvides::Package], and [MetaNoIndex] plugins provide metadata in this phase.

VersionProvider

The -VersionProvider phase executes when required rather than at a specific time. No plugins in this bundle execute during this phase by default. When using the "managed_versions" option, the [RewriteVersion] plugin acts as version provider.

ShareDir

The -ShareDir phase executes when required rather than at a specific time. In [@Starter], the [ShareDir] plugin handles this phase.

Regenerator

The -Regenerator phase is a quasi-phase which executes when dzil regenerate is run. When using the "regenerate" option, the [Regenerate::AfterReleasers] plugin promotes [CopyFilesFromRelease] to also execute during this phase.

Other

The operation of some plugins may not neatly fit into a particular phase. In [@Starter], the [ExecDir] plugin marks a directory as containing executables, which can be used by installer plugins such as [MakeMaker].

EXTENDING

This bundle includes a basic set of plugins for releasing a distribution, but there are many more common non-intrusive tasks that Dist::Zilla can help with simply by using additional plugins in the dist.ini. You can install all plugins required by a dist.ini by running dzil authordeps --missing | cpanm or with dzil installdeps.

Name

To automatically set the distribution name from the current directory, use [NameFromDirectory].

To extract the license and copyright information from the main module, and optionally set the author as well, use [LicenseFromModule].

Changelog

To automatically add the new release version to the distribution changelog, use [NextRelease]. To ensure the release has changelog entries, use [CheckChangesHasContent].

Git

To better integrate with a git workflow, use the plugins from [@Git], as the [@Starter::Git] variant of this bundle does. To automatically add contributors to metadata from git commits, use [Git::Contributors].

Resources

To automatically set resource metadata from an associated GitHub repository, use [GithubMeta]. To set resource metadata manually, use [MetaResources].

Prereqs

To automatically set distribution prereqs from a cpanfile, use [Prereqs::FromCPANfile]. To specify prereqs manually, use [Prereqs].

BUGS

Report any issues on the public bugtracker.

AUTHOR

Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Dan Book.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

SEE ALSO

Dist::Zilla, Dist::Zilla::PluginBundle::Basic, Dist::Zilla::PluginBundle::Starter::Git, Dist::Milla, Dist::Zilla::MintingProfile::Starter