view release on metacpan or  search on metacpan

lib/Carmel.pm  view on Meta::CPAN

  # Requires all your modules in cpanfile in one shot
  carmel exec perl -e 'use Carmel::Preload;'

  # Roll out the currently selected modules into ./local
  carmel rollout

  # package modules tarballs and index into ./vendor/cache
  carmel package

  # use Carmel packages inside a script (without carmel exec)
  perl -e 'use Carmel::Setup; ...'

  # prints export PATH=... etc for shell scripting
  carmel export

  # find a module in a repository
  carmel find DBI

  # find a module matching the version query
  carmel find Plack ">= 1.0000, < 1.1000"

=head1 DESCRIPTION

Carmel is yet another CPAN module manager.

Unlike traditional CPAN module installer, Carmel keeps the build of
your dependencies in a central repository, then select the library
paths to include upon runtime in development.

Carmel also allows you to rollout all the files in a traditional perl INC
directory structure, which is useful to use in a production environment, such as
containers.

=head1 WORKFLOW

=head2 Development

During the development, run C<carmel install> when you setup a new environment,
and any time you make changes to C<cpanfile>. This will update your build
artifacts, and saves the changes to C<cpanfile.snapshot>. Commit the snapshot
file in version control system so that you can reproduce the exact same versions
across machines.

C<carmel exec> makes it easy to run your application using the versions in
C<cpanfile> and C<cpanfile.snapshot> dynamically.

  # On your development environment
  > cat cpanfile
  requires 'Plack', '0.9980';
  requires 'Starman', '0.2000';

  > carmel install
  > echo /.carmel >> .gitignore
  > git add cpanfile cpanfile.snapshot .gitignore
  > git commit -m "add Plack and Starman"

  # On a new setup, or another developer's machine
  > git pull
  > carmel install
  > carmel exec starman -p 8080 myapp.psgi

  # Add a new dependency
  > echo "requires 'Try::Tiny';" >> cpanfile
  > carmel install
  > git commit -am 'Add Try::Tiny'

  # Update Plack to the latest
  > carmel update Plack

=head2 Production Deployments

Carmel allows you to manage all the dependencies the same way across development
environments and production environments. However, there might be cases where
you want to avoid running your application with C<carmel exec> in production, to
avoid the overhead with large number of include paths, or to avoid installing
Carmel in the production hosts.

Carmel provides two easy ways to avoid depending on Carmel on the deploy target
environments. First, C<carmel rollout> rolls out the build artifacts into a
regular perl5 library path in C<local>. Once the rollout is complete, you can
include the path just like a regular L<local::lib> directory.

  # Production environment: Roll out to ./local
  > carmel rollout
  > perl -Ilocal/lib/perl5 local/bin/starman -p 8080 myapp.psgi

You can run C<carmel rollout>> in a CI system to create the C<local> directory
next to your application code for a linux package (e.g. deb package), or Docker
containers.

Second, C<carmel package> (similar to C<carton bundle>) creates a directory with
tarballs and CPAN-style package index files, which you can pass to L<cpanm> on a
target machine. This way, you only need C<cpanm>, which is available as a
self-contained single executable, to bootstrap the installation on a host with a
stock perl.

  # Vendor all the packages to vendor/cache
  > carmel package
  > git add vendor/cache
  > git commit -m 'Vendor all the tarballs'

  # Remote environment (CI etc.)
  > git clone https://.../myapp.git && cd myapp
  > cpanm -L /path/to/lib --from $PWD/vendor/cache -nq --installdeps .

=head1 HOW IT WORKS

Carmel will keep the build directory (artifacts) after a cpanm
installation in a repository, which defaults to C<$HOME/.carmel/{version}-{archname}/builds>,
and your directory structure would look like:

  $HOME/.carmel/5.20.1-darwin-2level/builds
    Plack-1.0033/
      blib/
        arch/
        lib/
    URI-1.64/
      blib/
        arch/
        lib/
    URI-1.63/
      blib/
        arch/
        lib/

Carmel scans this directory and creates the mapping of which version
of any package belongs to which build directory.

Given the list of modules and requirements from C<cpanfile>, C<carmel install>
computes which versions satisfy the requirements best, and if there isn't,
installs the modules from CPAN to put it to the artifact repository. The
computed mappings are preserved as a snapshot in C<cpanfile.snapshot>.

Once the snapshot is created, each following C<carmel> command runs uses both
C<cpanfile> and C<cpanfile.snapshot> to determine the best versions to satisfy
the requirements. When you update C<cpanfile> to bump a version or add a new
module, C<carmel> will install the new dependencies and update the snapshot
accordingly.

C<carmel exec> command, like C<install> command, lists the build directories and
C<.pm> files you need from the repository, and then prepend the mappings of
these files in the C<@INC> hook. This is a handy way to run a perl program using
the dependencies pinned by Carmel, without changing any include path.

C<carmel update> command allows you to selectively update a dependency while