Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
cpanfile-faq(3)	      User Contributed Perl Documentation      cpanfile-faq(3)

       cpanfile-faq - cpanfile FAQ

   Does	cpanfile replace Makefile.PL/Build.PL or META.yml/json?
       No, it doesn't. "cpanfile" is a simpler way to declare CPAN
       dependencies, mainly for	your application rather	than CPAN

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

   Why do we need yet another format?
       Here are	some of	the reasons that motivates the new cpanfile format.

       Not everything is a CPAN	distribution
	   First of all, it is annoying	to write (a dummy) "Makefile.PL" when
	   what	you develop is not a CPAN distribution,	just so	that
	   installation	like "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 "inc/" directory (or even worse,
	   both) to a repository.

	   Many	web application	frameworks generate a boiler-plate
	   "Makefile.PL" for dependency	declaration and	to let you install
	   dependencies	with "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	cpanfile, dependencies can be installed	either globally	or
	   locally using supported tools such as cpanm or Carton. Because
	   "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

       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 CPAN Meta	Spec.

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

       Complete	CPAN Meta Spec v2 support
	   "cpanfile" basically	allows you to declare 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.

   How can I start using "cpanfile"?
       First of	all, most distributions	on CPAN	are not	required to update to
       this format.

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

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

	   Dist::Milla is a profile for	Dist::Zilla that has a "cpanfile"
	   support to declare dependencies for your module.

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

	   Minilla is a	yet another authoring tool that	supports "cpanfile" as
	   a way to describe dependencies for your CPAN	module.

	   Module::Install::CPANfile provides a	"cpanfile" DSL that reads
	   "cpanfile" to merge prerequisites when dumping "MYMETA" files upon

	   Module::Build::Pluggable::CPANfile merges "cpanfile"	dependencies
	   from	"Build.PL" when	dumping	out MYMETA information.

	   However you're recommended to switch	to an authoring	system that
	   emits "Build.PL" with parsed	CPANfile information, like Dist::Zilla
	   mentioned above.

	   ExtUtils::MakeMaker::CPANfile merges	"cpanfile" prerequisites when
	   dumping "MYMETA" files upon installation.

	   However you're recommended to switch	to an authoring	system that
	   emits "Makefile.PL" with parsed CPANfile information, like
	   Dist::Zilla mentioned above.

perl v5.32.1			  2018-04-26		       cpanfile-faq(3)


Want to link to this manual page? Use this URL:

home | help