Tatsuhiko Miyagawa's Blog

What is cpanfile and why do I want to use it

March 09, 2013

So there seems to be a couple of blog posts and even conference talks about cpanfile. It’s great, but just to make sure everyone gets what it is and why they want to (or don’t want to) use it for their stuff, here’s some clarification from the author.

tl;dr for japanesethis slide deck at Hokkaido.pm has a great intro for what cpanfile is.

cpanfile is made specifically to address the two following use cases, while the second one is kinda accidental.

1) “I have an app (web app, command line script) and want to manage its CPAN module dependencies somehow. I created a fake Makefile.PL to describe them, even though I don’t have a plan to release it to CPAN.”

2) “I have a Perl module on my git repository and want my contributors to be able to install from the repo, but they keep saying they can’t load inc/Module/Install.pm, and I don’t want to bump META.yml every time or include inc/ in the repo.

cpanfile is a Module::Install-like DSL to describe CPAN module dependencies. It comes with a module to parse out that file, but isn’t tied to any specific builder nor installers.

It is useful for Perl application developers who want to describe CPAN dependencies, and being able to install them with carton install or cpanm — installdeps .

For CPAN module authors, cpanfile is not something you really need to switch to, although you will (soon) have a benefit of easier installation from git repository if you have one. The reason i wrote “soon” is that cpanm 1.6 as of this writing doesn’t have the ability to bootstrap modules with M::I from git repo — it’s a known issue and I am trying to address that in the sane way before cpanm 1.7. (There’s a workaround out there to specify Module::Install in configure_requires but that is wrong because that’s not necessary once shipped to CPAN)

Standard CPAN installers (CPAN.pm, CPANPLUS, cpanm) work with META files (and then MYMETA after configuration) to detect dependencies. It’s a standard, and cpanfile doesn’t intend to replace them or anything at all. If you decide to use cpanfile to describe deps for your CPAN modules however, you should use Module::Install::CPANfile or Module::Build::Pluggable::CPANfile so that it will transparently work with MYMETA protocol.


I am a CPAN author and keep META.yml in the repo. Should I switch to cpanfile?

If your configuration is static and you have no problem remembering to bump META.yml in the repo, that’s just fine. However, putting “Module::Install” (for example) into your configure_requires doesn’t sound right since it’s not necessary once it’s shipped to CPAN. Committing the whole inc/ is another way to go, but it feels like an unnecessary work to me.

I have a web app and want to use cpanfile to deploy to the cloud. Which provider supports cpanfile?

Most PaaS providers (dotcloud, heroku through buildpack, etc.) uses cpanm — installdeps . to install dependencies. Once they upgrade cpanm to 1.6 or later, it will automatically figure out the dependencies out of cpanfile. If they don’t have 1.6 yet, why not requesting them to upgrade it?

I use dzil for my CPAN modules and am not sure what you are talking about.

Great, Forget about this post.

However, contributors to your module may have hard time installing dzil first and then remembering what command to run to test/install because it’s different from other CPAN module convention. cpanfile may be able to help that, but i’m still trying to figure out.

So which phase should I put Module::Install into in cpanfile?

It should most likely be develop, and cpanm will detect the “development environment” i.e not from CPAN tarball, but that’s still being ironed out.