=head1 NAME

cpanfile-faq - cpanfile FAQ

=head1 QUESTIONS

=head2 Does cpanfile replace Makefile.PL/Build.PL or META.yml/json?

No, it doesn't. C<cpanfile> is a simpler way to declare CPAN
dependencies, mainly to I<your application> rather than CPAN
distributions. It can also be used as a format to manage and express
CPAN dependencies (prereqs) for your module upon authoring modules.

CPAN distributions do not need to B<switch> to C<cpanfile>, but
you can certainly manage the dependencies in C<cpanfile>, then
export them into C<META.json> files when shipping to CPAN, using
tools such as L<Dist::Milla> or L<Module::Install::CPANfile>

=head2 Why do we need yet another format?

Here are some of the reasons that motivates the new L<cpanfile>
format.

=over 4

=item Not everything is a CPAN distribution

First of all, it is annoying to write (a dummy) C<Makefile.PL> when
what you develop is not a CPAN distribution, just so that installation
like C<cpanm --installdeps .> would work.

It gets more painful when you develop a web application that you want
to deploy on a different environment using version control system
(such as cloud infrastructure), because it requires you to often
commit the META file or C<inc/> directory (or even worse, botu) to a
repository when your build script uses non-core modules such as
L<Module::Install> or L<File::Copy::Recursive>.

Many web application frameworks generate a boiler-plate C<Makefile.PL>
for dependency declaration and to let you install dependencies with
C<< cpanm --installdeps . >>, but that doesn't always mean they are
meant to be installed. Things can be often much simpler if you run the
application from the checkout directory.

With L<cpanfile>, dependencies can be installed either globally or
locally using supported tools such as L<cpanm> or L<Carton>. Because
C<cpanfile> lists all the dependencies of your entire application and
will be updated over time, it makes perfect sense to commit the file
to a version control system, and push the file for a deployment.

=item More control for the dependencies analysis

One of the limitation when I tried to implement a self-contained
L<local::lib> library path feature for cpanminus was that the
configuration phase runs the build file as a separate perl process,
i.e. C<< perl Makefile.PL >>.

This makes it so hard for the script to I<not> accidentally load any
modules installed in the local C<site_perl> directory when determining
the dynamic dependencies. With the recent evolution of CPAN installer
ecosystem such as L<local::lib> support, it makes things much easier
if installers figure out whether dependencies are installed, instead
of by build tools such as L<Module::Install>.

=item Familiar DSL syntax

This is a new file type, but the format and syntax isn't entirely
new. The metadata it can declare is exactly a subset of "Prereqs" in
L<CPAN Meta Spec|CPAN::Meta::Spec>.

The syntax borrows a lot from L<Module::Install>. Module::Install is a
great way to easily declare module metadata such as name, author and
dependencies. L<cpanfile> format is simply to extract the dependencies
into a separate file, which means most of the developers are familiar
with the syntax.

=item Complete CPAN Meta Spec v2 support

C<cpanfile> basically allows you to declare L<CPAN::Meta::Spec>
prerequisite specification using an easy Perl DSL syntax. This makes
it easy to declare per-phase dependencies and newer version 2 features
such as conflicts and version ranges.

=back

=head2 How can I start using C<cpanfile>?

First of all, most distributions on CPAN are not required to update to
this format.

If your application currently uses C<Makefile.PL> etc. for dependency
declaration because of the current toolchain implementation (e.g. C<<
cpanm --installdeps . >>), you can upgrade to C<cpanfile> while
keeping the build file based installation working for the backward
compatibility.

If you are an author of CPAN module and want to manage CPAN module
prerequisites using C<cpanfile> you can use one of the following
tools:

=over 4

=item Dist::Milla

L<Dist::Milla> is a profile for L<Dist::Zilla> that has a C<cpanfile>
support to declare dependendies for your module.

=item Dist::Zilla

L<Dist::Zilla::Plugin::Prereqs::FromCPANfile> provides a way to merge
dependencies declared in C<cpanfile> into META files as well as build
files. You can combine them using other prerequisite scanners like
C<AutoPrereqs>.

=item Module::Install

L<Module::Install::CPANfile> provides a C<cpanfile> DSL that reads
C<cpanfile> to merge prerequisites when dumping C<MYMETA> files upon
installation.

=item Module::Build

L<Module::Build::Pluggable::CPANfile> merges C<cpanfile> dependencies
from C<Build.PL> when dumping out MYMETA information.

=item ExtUtils::MakeMaker

L<ExtUtils::MakeMaker> has no direct support for cpanfile yet, but you
could use L<Module::CPANfile>'s C<merge_meta> method to update
C<MYMETA.json> files with the contents in C<cpanfile>

=back