Permalink
Browse files

clarified docs

  • Loading branch information...
1 parent dd6708d commit 2a1ddaa393f90333be8192258506a323bfb24f99 @miyagawa miyagawa committed Jun 26, 2011
Showing with 141 additions and 6 deletions.
  1. +1 −1 Makefile.PL
  2. +125 −0 README
  3. +15 −5 lib/Carton/Doc/Carton.pod
View
2 Makefile.PL
@@ -3,7 +3,7 @@ name 'carton';
version_from 'lib/Carton.pm';
perl_version '5.008001';
license_from 'lib/Carton/Doc/Carton.pod';
-readme_from('bin/carton');
+readme_from('lib/Carton/Doc/Carton.pod');
requires 'version', 0.77;
requires 'JSON';
View
125 README
@@ -0,0 +1,125 @@
+NAME
+ carton - Perl module dependency manager (aka Bundler for Perl)
+
+SYNOPSIS
+ # During the development
+ > cat Makefile.PL
+ use inc::Module::Install;
+ name 'MyApp';
+ version '1.0';
+
+ requires 'Plack', 0.9980;
+ requires 'Starman', 0.2000;
+
+ WriteAll;
+
+ > carton install
+ > git commit -m "add Plack and Starman" Makefile.PL carton.lock
+
+ # Then elsewhere (on a deployment machine)
+ > carton install --deployment
+ > carton exec starman -p 8080 myapp.psgi
+
+WARNING
+ This software is under the heavy development and considered ALPHA
+ quality till the version hits v1.0.0. Things might be broken, not all
+ features have been implemented, and APIs will be likely to change. YOU
+ HAVE BEEN WARNED.
+
+DESCRIPTION
+ carton is a command line tool to track the Perl module dependencies for
+ your Perl application.
+
+TUTORIAL
+ Initializing the environment
+ carton will use ".carton" folder for local configuration and "local" to
+ install modules. You're recommended to exclude these directories from
+ the version control system.
+
+ > carton check
+ > echo .carton >> .gitignore
+ > echo local/ >> .gitignore
+ > git add carton.lock
+ > git commit -m "Start using carton"
+
+ Tracking the dependencies
+ You can manage the dependencies of your application via the standard
+ "Makefile.PL" or "Build.PL".
+
+ # Makefile.PL
+ use inc::Module::Install;
+ name 'MyAwesomeApp';
+ requires 'Plack', 0.9980;
+ requires 'Starman', 0.2000;
+ WriteAll;
+
+ And then you can install these dependencies via:
+
+ > carton install
+
+ The modules are installed into your "local" directory, and the
+ dependencies tree and version information are analyzed and saved into
+ "carton.lock" in your directory.
+
+ Make sure you add "carton.lock" to your version controlled repository
+ and commit changes as you update dependencies.
+
+ > git commit -m "Added Plack and Starman" Makefile.PL carton.lock
+
+ You can aternatively install modules adhoc from the command line,
+ without managing the build file at all.
+
+ > carton install Devel::NYTProf
+ > carton install AnyEvent::Redis
+
+ carton will install these modules into "local" directory in the same
+ way, and also can track and analyze the dependencies.
+
+ Deploying your application
+ Once you've done installing all the dependencies, you can push your
+ application directory to a remote machine (excluding "local" and
+ ".carton") and run the following command:
+
+ > carton install
+
+ This will look at the "carton.lock" and install the exact same versions
+ of the dependencies into "local", and now your application is ready to
+ run.
+
+ 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 "local/cache" directory, and
+
+ > carton install --cached
+
+ will install modules using this local cache. This way you can avoid a
+ dependency on CPAN meta DB and search.cpan.org at a deploy time, or you
+ can have dependencies onto private CPAN modules aka DarkPAN.
+
+AUTHOR
+ Tatsuhiko Miyagawa
+
+COPYRIGHT
+ Tatsuhiko Miyagawa 2011-
+
+LICENSE
+ This software is licensed under the same terms as Perl itself.
+
+SEE ALSO
+ cpanm
+
+ Bundler <http://gembundler.com/>
+
+ pip <http://pypi.python.org/pypi/pip>
+
+ npm <http://npmjs.org/>
+
+ perlrocks <https://github.com/gugod/perlrocks>
+
+ only
+
View
20 lib/Carton/Doc/Carton.pod
@@ -5,17 +5,21 @@ carton - Perl module dependency manager (aka Bundler for Perl)
=head1 SYNOPSIS
# During the development
- > $EDITOR Makefile.PL
- ...
+ > cat Makefile.PL
+ use inc::Module::Install;
+ name 'MyApp';
+ version '1.0';
+
requires 'Plack', 0.9980;
requires 'Starman', 0.2000;
- ...
+
+ WriteAll;
> carton install
> git commit -m "add Plack and Starman" Makefile.PL carton.lock
# Then elsewhere (on a deployment machine)
- > carton install
+ > carton install --deployment
> carton exec starman -p 8080 myapp.psgi
=head1 WARNING
@@ -69,9 +73,15 @@ repository and commit changes as you update dependencies.
> git commit -m "Added Plack and Starman" Makefile.PL carton.lock
-You'll alternatively be able to install modules from the command line,
+You can aternatively install modules adhoc from the command line,
without managing the build file at all.
+ > carton install Devel::NYTProf
+ > carton install AnyEvent::Redis
+
+carton will install these modules into C<local> directory in the same
+way, and also can track and analyze the dependencies.
+
=head2 Deploying your application
Once you've done installing all the dependencies, you can push your

0 comments on commit 2a1ddaa

Please sign in to comment.