131 lines
3.4 KiB
Plaintext
131 lines
3.4 KiB
Plaintext
=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
|
|
|