cpanfile(3pm)

1cpanfile(3)           User Contributed Perl Documentation          cpanfile(3)
2
3
4

NAME

6       cpanfile - A format for describing CPAN dependencies for Perl
7       applications
8

SYNOPSIS

10         requires 'Plack', '1.0'; # 1.0 or newer
11         requires 'JSON', '>= 2.00, < 2.80';
12
13         recommends 'JSON::XS', '2.0';
14         conflicts 'JSON', '< 1.0';
15
16         on 'test' => sub {
17           requires 'Test::More', '>= 0.96, < 2.0';
18           recommends 'Test::TCP', '1.12';
19         };
20
21         on 'develop' => sub {
22           recommends 'Devel::NYTProf';
23         };
24
25         feature 'sqlite', 'SQLite support' => sub {
26           recommends 'DBD::SQLite';
27         };
28

VERSION

30       This document describes cpanfile format version 1.0.
31

DESCRIPTION

33       "cpanfile" describes CPAN dependencies required to execute associated
34       Perl code.
35

SYNTAX

37       requires, recommends, suggests, conflicts
38             requires $module, $version_requirement;
39
40           Describes the requirement for a module. See CPAN::Meta::Spec for
41           the meanings of each requirement type.
42
43           When version requirement is omitted, it is assumed that 0 is
44           passed, meaning any version of the module would satisfy the
45           requirement.
46
47           Version requirement can either be a version number or a string that
48           satisfies "Version Ranges" in CPAN::Meta::Spec, such as ">= 1.0, !=
49           1.1".
50
51           Note that, per CPAN::Meta::Spec, when a plain version number is
52           given, it means the version or newer is required. If you want a
53           specific version for a module, use the specific range syntax, i.e.
54           " == 2.1 ".
55
56       on
57             on $phase => sub { ... };
58
59           Describe requirements for a specific phase. Available phases are
60           "configure", "build", "test", "runtime" and "develop".
61
62       feature
63             feature $identifier, $description => sub { ... };
64
65           Group requirements with features. Description can be omitted, when
66           it is assumed to be the same as identifier. See "optional_features"
67           in CPAN::Meta::Spec for more details.
68
69       configure_requires, build_requires, test_requires, author_requires
70             configure_requires $module, $version;
71             # on 'configure' => sub { requires $module, $version }
72
73             build_requires $module, $version;
74             # on 'build' => sub { requires $module, $version };
75
76             test_requires $module, $version;
77             # on 'test' => sub { requires $module, $version };
78
79             author_requires $module, $version;
80             # on 'develop' => sub { requires $module, $version };
81
82           Shortcut for "requires" in specific phase. This is mainly provided
83           for compatibilities with Module::Install DSL.
84

USAGE

86       "cpanfile" is a format to describe dependencies. How to use this file
87       is dependent on the tools reading/writing it.
88
89       Usually, you're expected to place the "cpanfile" in the root of the
90       directory containing the associated code.
91
92       Tools supporting "cpanfile" format (e.g. cpanm and carton) will
93       automatically detect the file and install dependencies for the code to
94       run.
95
96       There are also tools to support converting cpanfile to CPAN toolchain
97       compatible formats, such as Module::CPANfile,
98       Dist::Zilla::Plugin::Prereqs::FromCPANfile, Module::Install::CPANfile,
99       so that "cpanfile" can be used to describe dependencies for a CPAN
100       distribution as well.
101
102       The cpanfile-dump tool can be used to dump dependencies.
103

AUTHOR

105       Tatsuhiko Miyagawa
106

ACKNOWLEDGEMENTS

108       The format (DSL syntax) is inspired by Module::Install and
109       Module::Build::Functions.
110
111       "cpanfile" specification (this document) is based on Ruby's Gemfile
112       <http://bundler.io/v1.3/man/gemfile.5.html> specification.
113