Carton(3pm)

💖 Carton(3pm) — the Perl dependency manager bestie 💖

okay so you're looking at Carton(3pm), from the User Contributed Perl Documentation. No cap, this is the Perl module dependency manager — aka Bundler for Perl, and yes that comparison is doing exactly what you think it's doing. 🎀

---

✨ NAME ✨

Carton — Perl module dependency manager (aka Bundler for Perl) 🫶

---

🌸 SYNOPSIS 🌸

Here's the whole vibe in one go, bestie:

# 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

# carton exec is optional
> perl -Ilocal/lib/perl5 local/bin/starman -p 8080 myapp.psgi
> PERL5LIB=/path/to/local/lib/perl5 /path/to/local/bin/starman -p 8080 myapp.psgi

like... it's giving "write it down once, everyone gets the same thing forever". iconic. 💅

---

🦋 AVAILABILITY 🦋

Big disclaimer time, and I need you to actually read this one:

Carton only works with a perl installation that has the complete set of core modules. If your perl came from a vendor package with modules stripped out of core, Carton is not expected to work correctly. 😭

Also — and this is the part people forget — Carton requires you to run your command/application either with the carton exec command, or to shove the local/lib/perl5 directory into your Perl library search path. You can do that with PERL5LIB, with -I, or via lib. Pick your fighter. ✨

---

💜 DESCRIPTION 💜

carton is a command line tool that tracks the Perl module dependencies for your Perl application. Obsessed, honestly.

Dependencies get declared using the cpanfile format, and the managed dependencies get tracked in a cpanfile.snapshot file. That snapshot file is meant to be version controlled, and it's the whole point — it lets every other developer on your application have the exact same versions of the modules. no drift, no chaos, no "it works on my machine". 🧚

For the cpanfile syntax, go see the cpanfile documentation. iykyk.

---

🌈 TUTORIAL 🌈

Initializing the environment

carton uses the local directory to install modules into. And bestie, you're recommended to exclude these directories from your version control system. like, please. 🙈

> echo local/ >> .gitignore
> git add cpanfile cpanfile.snapshot
> git commit -m "Start using carton"

Tracking the dependencies

You can manage the dependencies of your application via cpanfile:

# cpanfile
requires 'Plack', '0.9980';
requires 'Starman', '0.2000';

And then you install these dependencies via:

> carton install

The modules get installed into your local directory, and the dependency tree plus version information get analyzed and saved into cpanfile.snapshot in your directory. ✨

Make sure you add cpanfile and cpanfile.snapshot to your version controlled repository and commit changes as you update dependencies. This is what ensures that other developers on your app — and your deployment environment — use exactly the same versions of the modules you just installed. teamwork, but make it reproducible. 🫶

> git add cpanfile cpanfile.snapshot
> git commit -m "Added Plack and Starman"

Specifying a CPAN distribution

You can pin a module resolution to a specific distribution using a combination of dist, mirror and url options in cpanfile. yes, all three. mix and match, main character energy. 👑

# specific distribution on PAUSE
requires 'Plack', '== 0.9980',
  dist => 'MIYAGAWA/Plack-0.9980.tar.gz';

# local mirror (darkpan)
requires 'Plack', '== 0.9981',
  dist => 'MYCOMPANY/Plack-0.9981-p1.tar.gz',
  mirror => 'https://pause.local/';

# URL
requires 'Plack', '== 1.1000',
  url => 'https://pause.local/authors/id/M/MY/MYCOMPANY/Plack-1.1000.tar.gz';

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 this:

> carton install --deployment

This looks at the cpanfile.snapshot and installs the exact same versions of the dependencies into local, and now your application is ready to run. slay. 💖

The --deployment flag makes sure that carton will only install modules and versions available in your snapshot, and won't fallback to querying the CPAN Meta DB for missing modules. periodt.

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 — like internal distributions, aka DarkPAN. 🖤

> carton bundle

will bundle these tarballs into the vendor/cache directory, and

> carton install --cached

will install modules using this local cache. Combine it with the --deployment option and you can avoid querying for a database like CPAN Meta DB or downloading files from CPAN mirrors at deployment time. chef's kiss. 😌

As of Carton v1.0.32, the bundle also includes a package index, which lets you simply use cpanm (which has a standalone version) instead of installing Carton on a remote machine. look at that, no install required:

> cpanm -L local --from "$PWD/vendor/cache" --installdeps --notest --quiet .

---

⭐ 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 classic.

The simplest solution — which might not work for everybody — is to use the same version of perl in development and deployment.

To enforce that, you're recommended to use plenv and .perl-version to lock perl versions in development. 🔒

You can also specify the minimum perl required in 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. it will absolutely tell you. loudly. 💀

---

🎀 COMMUNITY 🎀

• <https://github.com/perl-carton/carton> — Code repository, Wiki and Issue Tracker

---

👑 AUTHOR 👑

Tatsuhiko Miyagawa

---

💅 COPYRIGHT 💅

Tatsuhiko Miyagawa 2011-

---

🌸 LICENSE 🌸

This software is licensed under the same terms as Perl itself.

---

🦋 SEE ALSO 🦋

• Carmel
• cpanm
• cpanfile
• Bundler <http://gembundler.com/>
• pip <http://pypi.python.org/pypi/pip>
• npm <http://npmjs.org/>
• perlrocks <https://github.com/gugod/perlrocks>
• only

---

and that's the whole page, bestie! this one shipped as part of perl v5.34.0, dated 2022-05-12, and the page itself is Carton(3pm) 💖 go forth and pin your deps fr fr 🫶✨