129 lines
4.4 KiB
Plaintext
129 lines
4.4 KiB
Plaintext
=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 for I<your application> rather than CPAN
|
|
distributions.
|
|
|
|
However, while CPAN distributions do not need to B<switch> to
|
|
C<cpanfile>, you can certainly I<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 PaaS/cloud infrastructure), because it requires you to often
|
|
commit the META file or C<inc/> directory (or even worse, both) to a
|
|
repository.
|
|
|
|
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 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 dependencies 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 Minilla
|
|
|
|
L<Minilla> is a yet another authoring tool that supports C<cpanfile>
|
|
as a way to describe dependencies for your CPAN module.
|
|
|
|
=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.
|
|
|
|
However you're recommended to switch to an authoring system that emits
|
|
C<Build.PL> with parsed CPANfile information, like L<Dist::Zilla>
|
|
mentioned above.
|
|
|
|
=item ExtUtils::MakeMaker
|
|
|
|
L<ExtUtils::MakeMaker::CPANfile> merges C<cpanfile> prerequisites
|
|
when dumping C<MYMETA> files upon installation.
|
|
|
|
However you're recommended to switch to an authoring system that emits
|
|
C<Makefile.PL> with parsed CPANfile information, like L<Dist::Zilla>
|
|
mentioned above.
|
|
|
|
=back
|