1 files changed, 179 insertions, 0 deletions
diff --git a/lib/Carton.pm b/lib/Carton.pm
new file mode 100644
index 0000000..7546c77
--- /dev/null
+++ b/lib/Carton.pm
@@ -0,0 +1,179 @@
+package Carton;
+use strict;
+use 5.008_005;
+use version; our $VERSION = version->declare("v1.0.21");
+
+1;
+__END__
+
+=head1 NAME
+
+Carton - Perl module dependency manager (aka Bundler for Perl)
+
+=head1 SYNOPSIS
+
+  # On your development environment
+  > cat cpanfile
+  requires 'Plack', '0.9980';
+  requires 'Starman', '0.2000';
+
+  > carton install
+  > git add cpanfile cpanfile.snapshot
+  > git commit -m "add Plack and Starman"
+
+  # Other developer's machine, or on a deployment box
+  > carton install
+  > carton exec starman -p 8080 myapp.psgi
+
+=head1 AVAILABILITY
+
+Carton only works with perl installation with the complete set of core
+modules. If you use perl installed by a vendor package with modules
+stripped from core, Carton is not expected to work correctly.
+
+Also, Carton requires you to run your command/application with
+C<carton exec> command, which means it's difficult or impossible to
+run in an embedded perl use case such as mod_perl.
+
+=head1 DESCRIPTION
+
+carton is a command line tool to track the Perl module dependencies
+for your Perl application. Dependencies are declared using L<cpanfile>
+format, and the managed dependencies are tracked in a
+I<cpanfile.snapshot> file, which is meant to be version controlled,
+and the snapshot file allows other developers of your application will
+have the exact same versions of the modules.
+
+For C<cpanfile> syntax, see L<cpanfile> documentation.
+
+=head1 TUTORIAL
+
+=head2 Initializing the environment
+
+carton will use the I<local> directory to install modules into. You're
+recommended to exclude these directories from the version control
+system.
+
+  > echo local/ >> .gitignore
+  > git add cpanfile cpanfile.snapshot
+  > git commit -m "Start using carton"
+
+=head2 Tracking the dependencies
+
+You can manage the dependencies of your application via C<cpanfile>.
+
+  # cpanfile
+  requires 'Plack', '0.9980';
+  requires 'Starman', '0.2000';
+
+And then you can install these dependencies via:
+
+  > carton install
+
+The modules are installed into your I<local> directory, and the
+dependencies tree and version information are analyzed and saved into
+I<cpanfile.snapshot> in your directory.
+
+Make sure you add I<cpanfile> and I<cpanfile.snapshot> to your version
+controlled repository and commit changes as you update
+dependencies. This will ensure that other developers on your app, as
+well as your deployment environment, use exactly the same versions of
+the modules you just installed.
+
+  > git add cpanfile cpanfile.snapshot
+  > git commit -m "Added Plack and Starman"
+
+=head2 Deploying your application
+
+Once you've done installing all the dependencies, you can push your
+application directory to a remote machine (excluding I<local> and
+I<.carton>) and run the following command:
+
+  > carton install --deployment
+
+This will look at the I<cpanfile.snapshot> and install the exact same
+versions of the dependencies into I<local>, and now your application
+is ready to run.
+
+The C<--deployment> flag makes sure that carton will only install
+modules and versions available in your snapshot, and won't fallback to
+query for CPAN Meta DB for missing modules.
+
+=head2 Bundling modules
+
+carton can bundle all the tarballs for your dependencies into a
+directory so that you can even install dependencies that are not
+available on CPAN, such as internal distribution aka DarkPAN.
+
+  > carton bundle
+
+will bundle these tarballs into I<vendor/cache> directory, and
+
+  > carton install --cached
+
+will install modules using this local cache. Combined with
+C<--deployment> option, you can avoid querying for a database like
+CPAN Meta DB or downloading files from CPAN mirrors upon deployment
+time.
+
+=head1 PERL VERSIONS
+
+When you take a snapshot in one perl version and deploy on another
+(different) version, you might have troubles with core modules.
+
+The simplest solution, which might not work for everybody, is to use
+the same version of perl in the development and deployment.
+
+To enforce that, you're recommended to use L<plenv> and
+C<.perl-version> to lock perl versions in development.
+
+You can also specify the minimum perl required in C<cpanfile>:
+
+  requires 'perl', '5.16.3';
+
+and carton (and cpanm) will give you errors when deployed on hosts
+with perl lower than the specified version.
+
+=head1 COMMUNITY
+
+=over 4
+
+=item L<https://github.com/miyagawa/carton>
+
+Code repository, Wiki and Issue Tracker
+
+=item L<irc://irc.perl.org/#carton>
+
+IRC chat room
+
+=back
+
+=head1 AUTHOR
+
+Tatsuhiko Miyagawa
+
+=head1 COPYRIGHT
+
+Tatsuhiko Miyagawa 2011-
+
+=head1 LICENSE
+
+This software is licensed under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<cpanm>
+
+L<cpanfile>
+
+L<Bundler|http://gembundler.com/>
+
+L<pip|http://pypi.python.org/pypi/pip>
+
+L<npm|http://npmjs.org/>
+
+L<perlrocks|https://github.com/gugod/perlrocks>
+
+L<only>
+
+=cut