Where can I find the cpanfile format definition?

Question

We consider to use Minilla or Dist::Milla for our perl development. Declaring dependencies is done via cpanfile. I expected to find an exact definintion of what and how can be declared. But

• perldoc cpanfile : Shows only the principal usage. 'SEE ALSO' section does not help.

• perldoc Module::CPANfile: same as cpanfile.

• perldoc cpanfile-faq: no explanation of the exact syntax or a link to it, only

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.

• Web : I found ( but does not answer my question )
  • https://speakerdeck.com/miyagawa/cpanfile
  • http://weblog.bulknews.net/post/44963580392/what-is-cpanfile-and-why-do-i-want-to-use-it
  • http://blogs.perl.org/users/lestrrat/2013/03/the-main-problem-with-cpan-modules-on-github.html

Does anybody know where to find an exact description of the cpanfile syntax/format ?

Answer 1

I installed Module::CPANFile and perldoc cpanfile and perldoc cpanfile-faq were available.

The POD for cpanfile states:

[the] cpanfile specification (this document) is based on Ruby's
Gemfile http://gembundler.com/man/gemfile.5.html specification.

The link in the cpanfile manual page is broken. It should point to: http://bundler.io/v1.3/man/gemfile.5.html

cpanfile is designed to "backwards compatible" with Module::Install DSL syntax and is "convertible to CPAN::Meta::Prereqs" and inspired by CPAN::Meta Spec v.2 etc.

As I understand it cpanfile is somewhat of a "meta-format" and fits into a range of TIMTOWTDI approaches (see miyagawa's blog describing cpanfile), compatible with Module::Install and mostly self-documenting. For example if you run mymeta-cpanfile inside a directory with META files it will build a cpanfile for you; you can write a script that describes prerequisites from CPAN::Meta::Prereqs and then $file->save('cpanfile'); to write a cpanfile.

As for Dist::Milla, in the tutorial (see the POD included with Dist::Milla) miyagawa points out that "If you decide to manually construct [a] new cpanfile, the format is mostly compatible to Module::Install's requirement DSL". The tutorial also gives a short example.

I think it would be fair to ask miyagawa to clarify the status and use cases of the cpanfile specification/format in the documentation for the distribution. That and a few more examples would answer questions like yours. He has mostly done the work on this already - it is just not all in one place.