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

perl v5.36.0                                       2022-11-19                                      cpanfile(3pm)