1=head1 NAME 2 3cpanfile-faq - cpanfile FAQ 4 5=head1 QUESTIONS 6 7=head2 Does cpanfile replace Makefile.PL/Build.PL or META.yml/json? 8 9No, it doesn't. C<cpanfile> is a simpler way to declare CPAN 10dependencies, mainly for I<your application> rather than CPAN 11distributions. 12 13However, while CPAN distributions do not need to B<switch> to 14C<cpanfile>, you can certainly I<manage> the dependencies in 15C<cpanfile>, then export them into C<META.json> files when shipping to 16CPAN, using tools such as L<Dist::Milla> or L<Module::Install::CPANfile> 17 18=head2 Why do we need yet another format? 19 20Here are some of the reasons that motivates the new L<cpanfile> 21format. 22 23=over 4 24 25=item Not everything is a CPAN distribution 26 27First of all, it is annoying to write (a dummy) C<Makefile.PL> when 28what you develop is not a CPAN distribution, just so that installation 29like C<cpanm --installdeps .> would work. 30 31It gets more painful when you develop a web application that you want 32to deploy on a different environment using version control system 33(such as PaaS/cloud infrastructure), because it requires you to often 34commit the META file or C<inc/> directory (or even worse, both) to a 35repository. 36 37Many web application frameworks generate a boiler-plate C<Makefile.PL> 38for dependency declaration and to let you install dependencies with 39C<< cpanm --installdeps . >>, but that doesn't always mean they are 40meant to be installed. Things can be often much simpler if you run the 41application from the checkout directory. 42 43With L<cpanfile>, dependencies can be installed either globally or 44locally using supported tools such as L<cpanm> or L<Carton>. Because 45C<cpanfile> lists all the dependencies of your entire application and 46will be updated over time, it makes perfect sense to commit the file 47to a version control system, and push the file for a deployment. 48 49=item Familiar DSL syntax 50 51This is a new file type, but the format and syntax isn't entirely 52new. The metadata it can declare is exactly a subset of "Prereqs" in 53L<CPAN Meta Spec|CPAN::Meta::Spec>. 54 55The syntax borrows a lot from L<Module::Install>. Module::Install is a 56great way to easily declare module metadata such as name, author and 57dependencies. L<cpanfile> format is simply to extract the dependencies 58into a separate file, which means most of the developers are familiar 59with the syntax. 60 61=item Complete CPAN Meta Spec v2 support 62 63C<cpanfile> basically allows you to declare L<CPAN::Meta::Spec> 64prerequisite specification using an easy Perl DSL syntax. This makes 65it easy to declare per-phase dependencies and newer version 2 features 66such as conflicts and version ranges. 67 68=back 69 70=head2 How can I start using C<cpanfile>? 71 72First of all, most distributions on CPAN are not required to update to 73this format. 74 75If your application currently uses C<Makefile.PL> etc. for dependency 76declaration because of the current toolchain implementation (e.g. C<< 77cpanm --installdeps . >>), you can upgrade to C<cpanfile> while 78keeping the build file based installation working for the backward 79compatibility. 80 81If you are an author of CPAN module and want to manage CPAN module 82prerequisites using C<cpanfile> you can use one of the following 83tools: 84 85=over 4 86 87=item Dist::Milla 88 89L<Dist::Milla> is a profile for L<Dist::Zilla> that has a C<cpanfile> 90support to declare dependencies for your module. 91 92=item Dist::Zilla 93 94L<Dist::Zilla::Plugin::Prereqs::FromCPANfile> provides a way to merge 95dependencies declared in C<cpanfile> into META files as well as build 96files. You can combine them using other prerequisite scanners like 97C<AutoPrereqs>. 98 99=item Minilla 100 101L<Minilla> is a yet another authoring tool that supports C<cpanfile> 102as a way to describe dependencies for your CPAN module. 103 104=item Module::Install 105 106L<Module::Install::CPANfile> provides a C<cpanfile> DSL that reads 107C<cpanfile> to merge prerequisites when dumping C<MYMETA> files upon 108installation. 109 110=item Module::Build 111 112L<Module::Build::Pluggable::CPANfile> merges C<cpanfile> dependencies 113from C<Build.PL> when dumping out MYMETA information. 114 115However you're recommended to switch to an authoring system that emits 116C<Build.PL> with parsed CPANfile information, like L<Dist::Zilla> 117mentioned above. 118 119=item ExtUtils::MakeMaker 120 121L<ExtUtils::MakeMaker::CPANfile> merges C<cpanfile> prerequisites 122when dumping C<MYMETA> files upon installation. 123 124However you're recommended to switch to an authoring system that emits 125C<Makefile.PL> with parsed CPANfile information, like L<Dist::Zilla> 126mentioned above. 127 128=back 129