jamie-bitflight/perl-cpan-ecosystem

CPAN Ecosystem Guide

Comprehensive guide for managing Perl modules using cpanm, cpanfile, Carton, and local::lib.

cpanm (cpanminus)

The recommended tool for installing CPAN modules.

Installation

# Using curl
curl -L https://cpanmin.us | perl - --self-upgrade

# Using system package manager
# Debian/Ubuntu
sudo apt install cpanminus

# macOS
brew install cpanminus

# From CPAN
cpan App::cpanminus

Basic Usage

# Install a module
cpanm Module::Name

# Install specific version
cpanm Module::[email protected]

# Install with dependencies only (for testing)
cpanm --installdeps .

# Quiet installation
cpanm --quiet --notest Module::Name

# Install to local directory
cpanm --local-lib=~/perl5 Module::Name

Common Flags

| Flag | Purpose | | ------------------ | ------------------------------ | | --notest | Skip tests (faster, less safe) | | --quiet | Minimal output | | --verbose | Detailed output | | --force | Install despite test failures | | --installdeps | Install dependencies only | | --local-lib=DIR | Install to specific directory | | --self-upgrade | Update cpanm itself | | --mirror URL | Use specific CPAN mirror | | --skip-satisfied | Skip already installed |

Mirror Configuration

# Use a specific mirror
cpanm --mirror https://cpan.metacpan.org Module::Name

# Use mirror only (no fallback)
cpanm --mirror https://cpan.metacpan.org --mirror-only Module::Name

cpanfile

Declare dependencies in a cpanfile for reproducible installations.

Basic cpanfile

# cpanfile
requires 'Moo';
requires 'Path::Tiny';
requires 'Try::Tiny';

# Version constraints
requires 'DBI', '1.643';           # Exact version
requires 'JSON::XS', '>= 4.0';     # Minimum version
requires 'Plack', '< 2.0';         # Maximum version
requires 'Moose', '>= 2.0, < 3.0'; # Range

# Development dependencies
on 'develop' => sub {
    requires 'Perl::Critic';
    requires 'Perl::Tidy';
};

# Test dependencies
on 'test' => sub {
    requires 'Test::More', '0.98';
    requires 'Test::Exception';
    requires 'Test::Deep';
};

# Build dependencies
on 'build' => sub {
    requires 'Module::Build';
};

# Recommended (not required)
recommends 'JSON::XS';
suggests 'IO::Socket::SSL';

Feature Phases

| Phase | Purpose | When Installed | | --------- | --------------- | ---------------- | | runtime | Production deps | Always (default) | | test | Testing deps | --with-test | | develop | Dev tools | --with-develop | | build | Build tools | During build |

Install from cpanfile

# Install all runtime dependencies
cpanm --installdeps .

# Include test dependencies
cpanm --installdeps --with-test .

# Include all phases
cpanm --installdeps --with-develop --with-test .

Carton

Lock dependencies to exact versions for reproducible deployments.

Installation

cpanm Carton

Basic Workflow

# Create cpanfile.snapshot from cpanfile
carton install

# Install to local/ directory
carton install --deployment

# Update dependencies
carton update

# Run script with locked dependencies
carton exec perl script.pl

# Run with specific local path
carton exec --path local perl app.pl

Generated Files

| File | Purpose | Git | | ------------------- | ---------------------- | ------ | | cpanfile | Dependency declaration | Commit | | cpanfile.snapshot | Locked versions | Commit | | local/ | Installed modules | Ignore |

.gitignore for Carton

/local/
/.carton/

Deployment Pattern

# Development machine
carton install
git add cpanfile cpanfile.snapshot
git commit -m "Update dependencies"

# Production machine
git pull
carton install --deployment --without develop,test
carton exec perl app.pl

local::lib

Install modules in user directory without root access.

Setup

# Install local::lib
cpanm local::lib

# Initialize (add to shell profile)
eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)

# Add to ~/.bashrc or ~/.zshrc
echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bashrc

Environment Variables

local::lib sets these variables:

PERL5LIB=$HOME/perl5/lib/perl5
PERL_LOCAL_LIB_ROOT=$HOME/perl5
PERL_MB_OPT="--install_base $HOME/perl5"
PERL_MM_OPT="INSTALL_BASE=$HOME/perl5"
PATH=$HOME/perl5/bin:$PATH

Custom Installation Path

# Use different directory
eval $(perl -Mlocal::lib=$HOME/myperllib)

# Project-specific
eval $(perl -Mlocal::lib=./local)

Module Resolution Order

Perl searches for modules in this order:

1. Directories in @INC
2. PERL5LIB paths
3. Site lib (system-wide)
4. Core modules

Check current @INC:

perl -V  # Full config including @INC
perl -e 'print join("\n", @INC)'

Finding Modules

Search MetaCPAN

# Using mccpan (if installed)
cpanm App::cpanminus::reporter
cpan-outdated

# Or use web: https://metacpan.org/

Check Installed Modules

# List all installed
perldoc perllocal

# Check specific module
perl -MModule::Name -e 'print $Module::Name::VERSION'

# Using cpan
cpan -l

# Using pmvers (from pmtools)
pmvers Module::Name

Troubleshooting

Common Issues

Module not found after install:

# Check PERL5LIB
echo $PERL5LIB

# Verify module location
perl -MModule::Name -e 'print $INC{"Module/Name.pm"}'

Permission denied:

# Use local::lib instead of sudo
eval $(perl -Mlocal::lib)
cpanm Module::Name

Build failures:

# Install build tools
# Debian/Ubuntu
sudo apt install build-essential

# Check build log
less ~/.cpanm/build.log

XS module compilation:

# Install development headers
sudo apt install libssl-dev  # For SSL modules
sudo apt install libxml2-dev # For XML modules

Project Setup Example

Initialize a new Perl project with proper dependency management:

# Create project structure
mkdir -p myapp/{lib,t,bin}
cd myapp

# Create cpanfile
cat > cpanfile << 'EOF'
requires 'Moo';
requires 'Path::Tiny';
requires 'Try::Tiny';

on 'test' => sub {
    requires 'Test::More', '0.98';
};
EOF

# Install with Carton
carton install

# Add to .gitignore
echo '/local/' >> .gitignore
echo '/.carton/' >> .gitignore

# Commit dependency spec
git add cpanfile cpanfile.snapshot

Additional Resources

For Perl version management with perlbrew, see the perl-environment-setup skill.