=head1 NAME

Carton::Doc::Install - Install the dependencies

=head1 SYNOPSIS

  carton install [--deployment] [--path=PATH] [modules...]

=head1 DESCRIPTION

Install the dependencies for your application. This command has two
modes and the behavior is slightly different.

=head2 DEVELOPMENT MODE

=over 4

=item carton install <name>

If you run C<carton install> with the arguments, carton will fetch and
install the modules given as arguments.

=item carton install (no arguments)

If you run C<carton install> without any arguments and if a build file
(I<Makefile.PL> or I<Build.PL>) exists, carton will scan dependencies
from the build file and install the modules.

=back

In either way, if you run C<carton install> for the first time
(i.e. I<carton.lock> does not exist), carton will fetch all the
modules specified, resolve dependencies and install all required
modules from CPAN.

If I<carton.lock> file does exist, carton will still try to install
modules specified or updated in the build file, but uses
I<carton.lock> for the dependency resolution, and then cascades to
CPAN.

carton will analyze all the dependencies and their version
information, and it is saved into I<carton.lock> file. It is important
to add I<carton.lock> file into a version controlled repository and
commit the changes as you update your dependencies.

=head2 DEPLOYMENT MODE

If you specify the C<--deployment> command line option or the
I<carton.lock> exists and your build file does not exist, carton will
fetch all remote modules and use the dependencies specified in the
I<carton.lock> instead of resolving dependencies.

=head1 CONSERVATIVE UPDATE

C<carton install> doesn't update the modules already installed into
I<local> library path as long as the version is satisfied.

For example, one day you install URI-1.50 from CPAN:

  > carton install URI
  Successfully installed URI-1.50

Few weeks later, URI module is updated to 1.51 on CPAN. If you run the
C<carton install URI> again:

  > carton install URI
  You have URI (1.50)

because you haven't specified the version number, carton won't update
the module in your local library path. If you want to update to the
latest version of CPAN, you can either use C<carton update> command,
or specify the required version either in your build file or a command
line argument:

 > carton install URI~1.51
 > carton update URI

 > cat Makefile.PL
 requires 'URI', 1.51;

Any of those will upgrade URI to the latest one from CPAN, and the
version specified in the I<carton.lock> will be bumped.

=head1 OPTIONS

=over 4

=item --deployment

Force the deployment mode and carton will ignore build file contents.

=item --path

Specify the path to install modules to. Defaults to I<local> in the current directory.

=back