Skip to content

Commit

Permalink
reorganized the command and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@miyagawa
miyagawa committed Jun 26, 2011
1 parent d2d9a68 commit d3ea4e0
Show file tree
Hide file tree
Showing 7 changed files with 229 additions and 251 deletions.
17 changes: 16 additions & 1 deletion Makefile.PL
View file
@@ -1,7 +1,8 @@
use inc::Module::Install;
name 'carton';
version_from 'lib/Carton.pm';
all_from 'bin/carton';
perl_version '5.008001';
license_from 'lib/Carton/Doc/Carton.pod';
readme_from('bin/carton');

requires 'version', 0.77;
Expand All @@ -12,7 +13,21 @@ requires 'Module::Metadata', 1.000003;

install_script 'bin/carton';

makemaker_args MAN1PODS => man1pods();

build_requires 'Test::More', 0.88;
test_requires 'Test::Requires';
auto_set_repository();
WriteAll;

sub man1pods {
my %pods;

for my $file (glob "lib/Carton/Doc/*.pod") {
my $name = ($file =~ m!Doc/(.*?)\.pod!)[0];
$name = $name eq 'Carton' ? "carton" : ("carton-" . lc($name));
$pods{$file} = "blib/man1/$name.1"
}

\%pods;
}
115 changes: 0 additions & 115 deletions README
View file
@@ -1,115 +0,0 @@
NAME
carton - Perl module dependency manager (aka Bundler for Perl)

SYNOPSIS
# During the development
> $EDITOR Makefile.PL
...
requires 'Plack', 0.9980;
requires 'Starman', 0.2000;
...

> carton install
> git commit -m "add Plack and Starman" Makefile.PL carton.lock

# Then elsewhere (on a deployment machine)
> carton install
> 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'll alternatively be able to install modules from the command line,
without managing the build file at all.

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

1 change: 1 addition & 0 deletions TODO
View file
Expand Up @@ -3,6 +3,7 @@ support CPAN distro only
carton config / .carton/config
-g, --global + local::lib (~/perl5)
exec
cpanm Module@Version

# 1.1
carton update
Expand Down
132 changes: 0 additions & 132 deletions bin/carton
View file
Expand Up @@ -4,135 +4,3 @@ use 5.008001;
use Carton;

Carton->new->run(@ARGV);

__END__
=head1 NAME
carton - Perl module dependency manager (aka Bundler for Perl)
=head1 SYNOPSIS
# During the development
> $EDITOR Makefile.PL
...
requires 'Plack', 0.9980;
requires 'Starman', 0.2000;
...
> carton install
> git commit -m "add Plack and Starman" Makefile.PL carton.lock
# Then elsewhere (on a deployment machine)
> carton install
> carton exec starman -p 8080 myapp.psgi
=head1 WARNING
B<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.>
=head1 DESCRIPTION
carton is a command line tool to track the Perl module dependencies
for your Perl application.
=head1 TUTORIAL
=head2 Initializing the environment
carton will use C<.carton> folder for local configuration and
C<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"
=head2 Tracking the dependencies
You can manage the dependencies of your application via the standard
C<Makefile.PL> or C<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 C<local> directory, and the
dependencies tree and version information are analyzed and saved into
C<carton.lock> in your directory.
Make sure you add C<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'll alternatively be able to install modules from the command line,
without managing the build file at all.
=head2 Deploying your application
Once you've done installing all the dependencies, you can push your
application directory to a remote machine (excluding C<local> and
C<.carton>) and run the following command:
> carton install
This will look at the C<carton.lock> and install the exact same
versions of the dependencies into C<local>, and now your application
is ready to run.
=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 C<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.
=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<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
26 changes: 23 additions & 3 deletions lib/Carton.pm
View file
Expand Up @@ -52,7 +52,7 @@ sub run {

push @commands, @ARGV;

my $cmd = shift @commands || 'help';
my $cmd = shift @commands || 'usage';
my $call = $self->can("cmd_$cmd");

if ($call) {
Expand All @@ -62,6 +62,26 @@ sub run {
}
}

sub commands {
my $self = shift;

no strict 'refs';
map { s/^cmd_//; $_ }
grep /^cmd_(.*)/, sort keys %{__PACKAGE__."::"};
}

sub cmd_usage {
my $self = shift;
print <<HELP;
Usage: carton <command>
where <command> is one of:
@{[ join ", ", $self->commands ]}
Run carton -h <command> for help.
HELP
}

sub parse_options {
my($self, $args, @spec) = @_;
Getopt::Long::GetOptionsFromArray($args, @spec);
Expand All @@ -87,8 +107,8 @@ sub error {

sub cmd_help {
my $self = shift;
my $cmd = $_[0] ? "carton-$_[0]" : "carton";
system "perldoc", $cmd;
my $module = "Carton::Doc::" . ($_[0] ? ucfirst $_[0] : "Carton");
system "perldoc", $module;
}

sub cmd_version {
Expand Down

0 comments on commit d3ea4e0

Please sign in to comment.