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.

       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