Initial Commit

database/perl/lib/cpanfile.pod

@@ -0,0 +1,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
+