Initial Commit

database/perl/lib/cpanfile-faq.pod

@@ -0,0 +1,128 @@
+=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