cpanfile(3)

🎀 cpanfile(3) — the cpanfile manual, bestie edition 🎀

okay so this is cpanfile(3), a User Contributed Perl Documentation page, and it’s literally about giving your CPAN dependencies a whole organized personality. we’re gonna keep every single detail, no cap. 💅

---

🌸 NAME 🌸

cpanfile — A format for describing CPAN dependencies for Perl applications.

---

✨ SYNOPSIS ✨

bestie, the whole vibe starts like this:

requires 'Plack', '1.0'; # 1.0 or newer
requires 'JSON', '>= 2.00, < 2.80';

recommends 'JSON::XS', '2.0';
conflicts 'JSON', '< 1.0';

on 'test' => sub {
  requires 'Test::More', '>= 0.96, < 2.0';
  recommends 'Test::TCP', '1.12';
};

on 'develop' => sub {
  recommends 'Devel::NYTProf';
};

feature 'sqlite', 'SQLite support' => sub {
  recommends 'DBD::SQLite';
};

---

🌈 VERSION 🌈

This document describes cpanfile format version 1.0. periodt. 🫶

---

💖 DESCRIPTION 💖

cpanfile describes CPAN dependencies required to execute associated Perl code. it’s giving “dependency list but make it a whole little format.” ✨

---

🛠️ SYNTAX 🛠️

🧚 requires, recommends, suggests, conflicts 🧚

requires $module, $version_requirement;

Describes the requirement for a module. See CPAN::Meta::Spec for the meanings of each requirement type.

When version requirement is omitted, it is assumed that 0 is passed, meaning any version of the module would satisfy the requirement.

Version requirement can either be a version number or a string that satisfies "Version Ranges" in CPAN::Meta::Spec, such as >= 1.0, != 1.1.

Note that, per CPAN::Meta::Spec, when a plain version number is given, it means the version or newer is required. If you want a specific version for a module, use the specific range syntax, i.e. " == 2.1 ". 👑

🌀 on 🌀

on $phase => sub { ... };

Describe requirements for a specific phase. Available phases are "configure", "build", "test", "runtime" and "develop".

🎀 feature 🎀

feature $identifier, $description => sub { ... };

Group requirements with features. Description can be omitted, when it is assumed to be the same as identifier. See "optional_features" in CPAN::Meta::Spec for more details.

🦋 configure_requires, build_requires, test_requires, author_requires 🦋

configure_requires $module, $version;
# on 'configure' => sub { requires $module, $version }

build_requires $module, $version;
# on 'build' => sub { requires $module, $version };

test_requires $module, $version;
# on 'test' => sub { requires $module, $version };

author_requires $module, $version;
# on 'develop' => sub { requires $module, $version };

Shortcut for "requires" in specific phase. This is mainly provided for compatibilities with Module::Install DSL.

---

🫶 USAGE 🫶

cpanfile is a format to describe dependencies. How to use this file is dependent on the tools reading/writing it.

Usually, you’re expected to place the cpanfile in the root of the directory containing the associated code.

Tools supporting cpanfile format (e.g. cpanm and carton) will automatically detect the file and install dependencies for the code to run.

There are also tools to support converting cpanfile to CPAN toolchain compatible formats, such as Module::CPANfile, Dist::Zilla::Plugin::Prereqs::FromCPANfile, Module::Install::CPANfile, so that cpanfile can be used to describe dependencies for a CPAN distribution as well.

The cpanfile-dump tool can be used to dump dependencies.

---

👑 AUTHOR 👑

Tatsuhiko Miyagawa

---

🌟 ACKNOWLEDGEMENTS 🌟

The format (DSL syntax) is inspired by Module::Install and Module::Build::Functions.

cpanfile specification (this document) is based on Ruby’s Gemfile <http://bundler.io/v1.3/man/gemfile.5.html> specification.

---

💜 SEE ALSO 💜

• CPAN::Meta::Spec
• Module::Install
• Carton

---

mwah 💋 — page source/version: perl v5.42.0; date: 2018-04-27. that’s the whole manual, bestie, and it ate. 🫶✨