/usr/share/perl5/cpanfile-faq.pod is in libmodule-cpanfile-perl 1.1002-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 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
|