14

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.

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

katastrophos
  • 521
  • 4
  • 17

1 Answers1

7

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.

G. Cito
  • 6,210
  • 3
  • 29
  • 42
  • 2
    What does it mean 'based on' ? Same syntax, same semantics, extended perl features ... ? I'd like to read the exact format/definition FOR PERL or that I have to read the ruby gem spec ;-) ! Btw. the link is broken. – katastrophos Jul 17 '13 at 18:25
  • 1
    @katastrophos: But you did not write an issue for the broken link — well, I did it. – Slaven Rezic Jul 18 '13 at 09:42
  • @SlavenRezic: you are right. Using that link you are redirected to http://bundler.io/man/gemfile.5.html which is a 'page not found' site. You have to go to the main page and start the search from there (which I did not). – katastrophos Jul 18 '13 at 11:07
  • 1
    @SlavenRezic and katastrophos - I fixed the link and added a a pull request upstream with the `cpanfile` github. Cheers – G. Cito Jul 18 '13 at 12:28
  • 1
    Thanks @G.Cito. It's interesting to see (like Module::Install's dependency hanling). Unfortunately it does not answer my question. I am curious about the outcome. Where do people know how to use cpanfile if there is no documentation ? – katastrophos Jul 18 '13 at 12:28
  • If you want a full on specification I believe you will still have to wait a while. It's been ~ 2 years+ but AFAIK @miyagawa still presents this as a "proposal". A pretty specific proposal but not fully described in some sort of RFC. – G. Cito Jul 18 '13 at 12:42
  • @katastrophos - tried to make this into an "answer" to the extent possible. I doubt `cpanfile` will change in radically backwards incompatible ways but it may not be "complete" just yet. Now is your chance not only to use it but to help with the documentation/testing etc. :-) – G. Cito Jul 18 '13 at 14:03
  • @G.Cito: Thanks for your effort. I will accept your answer and I agree with your opinion. I already contacted Miyagawa and we will see. If we select Minilla/Dist::Zilla we surely will write documentation about cpanfile. – katastrophos Jul 18 '13 at 15:41