1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
=head1 NAME
cpanfile - A format for describing CPAN dependencies for Perl applications
=head1 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';
};
=head1 VERSION
This document describes cpanfile format version 1.0.
=head1 DESCRIPTION
C<cpanfile> describes CPAN dependencies required to execute associated
Perl code.
=head1 SYNTAX
=over 4
=item requires, recommends, suggests, conflicts
requires $module, $version_requirement;
Describes the requirement for a module. See L<CPAN::Meta::Spec> for
the meanings of each requirement type.
When version requirement is omitted, it is assumed that C<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 L<CPAN::Meta::Spec/Version Ranges>, such as C<< >= 1.0, !=
1.1 >>.
Note that, per L<CPAN::Meta::Spec>, when a plain version number is
given, it means the version I<or newer> is required. If you want a
specific version for a module, use the specific range syntax, i.e.
C< == 2.1 >.
=item on
on $phase => sub { ... };
Describe requirements for a specific phase. Available phases are
C<configure>, C<build>, C<test>, C<runtime> and C<develop>.
=item feature
feature $identifier, $description => sub { ... };
Group requirements with features. Description can be omitted, when it
is assumed to be the same as identifier. See
L<CPAN::Meta::Spec/optional_features> for more details.
=item 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 C<requires> in specific phase. This is mainly provided
for compatibilities with L<Module::Install> DSL.
=back
=head1 USAGE
C<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 C<cpanfile> in the root of the
directory containing the associated code.
Tools supporting C<cpanfile> format (e.g. L<cpanm> and L<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 L<Module::CPANfile>,
L<Dist::Zilla::Plugin::Prereqs::FromCPANfile>,
L<Module::Install::CPANfile>, so that C<cpanfile> can be used to
describe dependencies for a CPAN distribution as well.
The L<cpanfile-dump> tool can be used to dump dependencies.
=head1 AUTHOR
Tatsuhiko Miyagawa
=head1 ACKNOWLEDGEMENTS
The format (DSL syntax) is inspired by L<Module::Install> and
L<Module::Build::Functions>.
C<cpanfile> specification (this document) is based on Ruby's
L<Gemfile|http://bundler.io/v1.3/man/gemfile.5.html> specification.
=head1 SEE ALSO
L<CPAN::Meta::Spec> L<Module::Install> L<Carton>
=cut
|
