NAME¶
cpanfile - A format for describing CPAN dependencies for Perl applications
SYNOPSIS¶
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.
DESCRIPTION¶
"cpanfile" describes CPAN dependencies required to execute associated
Perl code.
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.
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