view release on metacpan or  search on metacpan

lib/Dist/Zilla/Starter.pm  view on Meta::CPAN

Executables to install have no strict convention but are usually put in F<bin/>
or F<script/>.

=back

You may see distributions with these important files in other places, usually
because they predate these conventions or for compatibility with old versions
of ExtUtils::MakeMaker that required F<.xs> files to be in the distribution
root. Other directories may be included in the CPAN distribution, but have no
specific meaning by default to the standard installers.

=head1 A BRIEF HISTORY OF AUTHORING

=head2 ExtUtils::MakeMaker

  $ perl Makefile.PL && make manifest && make disttest && make dist
  $ cpan-upload Some-Code-1.00.tar.gz

Originally, the same tool which allows end users to install the distribution
would also be used by the author to manage it and create a release.
L<ExtUtils::MakeMaker> contains author-side configuration and commands such as
C<make manifest> and C<make dist>. Indeed, many authors still use this as their
primary authoring tool, though its close-to-metal nature and extreme backcompat
requirements have led many to develop more author-friendly wrappers.

=head2 Module::Install

One such wrapper is L<Module::Install>. This differed from many attempts in
that it was designed to bundle itself with the distribution, so the end user
would install using the bundled code rather than relying on the interface of
their possibly outdated ExtUtils::MakeMaker. This was a revolutionary idea and
the wrapper interface was well liked, but it introduced other problems.

Due to being bundled with the release, it too became outdated when the author
did not regularly release new versions of the distribution, so bugs would
linger forever that the end user could not workaround by updating their own
toolchain. This was notably a significant issue when Perl 5.26 stopped loading
modules from the current working directory by default, a mechanism which the
Module::Install code bundled with hundreds of distributions relied upon to load
itself.

Additionally, it had a rudimentary plugin system but no way to formally declare
what plugins a distribution was using, meaning that given a
Module::Install-based Makefile.PL, the author or contributor would have to
guess what plugins needed to be installed or bundled for the end user to make
it work. On top of (or perhaps due to) these problems, it has become mostly
unmaintained and thus has fallen far behind the progress of the CPAN toolchain.

=head2 Module::Build

  $ perl Build.PL && perl Build && perl Build manifest && perl Build disttest && perl Build dist
  $ cpan-upload Some-Code-1.00.tar.gz

L<Module::Build> was created to provide a C<make>-free alternative to
L<ExtUtils::MakeMaker>, with the additional goal of being more modern and
easier to customize and add features to. Unfortunately this proved to be a
lofty goal, as due to widespread use it succumbed to the same stagnation as
ExtUtils::MakeMaker; it too has become extremely complex and obtuse, is no
longer driven to evolve by its primary author, and must maintain backcompat
religiously. This has weakened most of its benefits considerably, as
ExtUtils::MakeMaker still remains more compatible with ancient end-user Perls,
but Module::Build is still used by some who prefer its interface over
ExtUtils::MakeMaker, or who have complicated compilation requirements that are
easier to customize in Module::Build.

=head2 Module::Build::Tiny and Dist::Build

  $ mbtiny test --release
  $ mbtiny upload

More recently, L<Module::Build::Tiny> was created as an extremely simple
implementation of the F<Build.PL> spec pioneered by Module::Build. A
significant reason for its simplicity is that unlike the previously mentioned
tools, it is B<only> an install tool; it does not provide any authoring
features. A separate tool called L<mbtiny> provides these features in a minimal
package, or it works great with dedicated authoring tools like Dist::Zilla.

L<Dist::Build> is a more extensible and customizable install-only
implementation of the F<Build.PL> spec, and similarly leaves authoring features
up to tools like Dist::Zilla.

=head2 Dist::Zilla

  $ dzil release

Dist::Zilla came to be one of the first widespread author-side-only tools, and
as such it shed many of the limitations of its overworked predecessors.

=over

=item *

It does not have to concern itself with minimalism and compatibility, because
the end user does not need to install it; it can use everything that modern
CPAN has to offer, and rely on the generated install file to be lightweight and
compatible if needed.

=item *

The generated install file also has a simpler job, as it doesn't need to
generate the distribution's metadata aside from any dynamic prerequisites, or
implement any author-side commands for convenience, as Dist::Zilla does these
tasks itself.

=item *

Learning from the mistakes of Module::Install, it has a formal plugin
configuration system, and can deterministically find what plugins are needed to
build (assemble) the distribution, using the
L<C<dzil authordeps>|Dist::Zilla::App::Command::authordeps> command.

=back

=head1 DZIL AND BUNDLES

Dist::Zilla is a CPAN distribution authoring framework. At its core, it only
organizes tasks; it requires plugins to implement the specifics of assembling,
testing, and releasing the distribution. The author can manually specify in
F<dist.ini> the set of plugins that suits their needs, or even write new
plugins, but there are also ready-made tools built upon it that require very