Perl Environment Setup

Perl Environment Setup

Guide for setting up Perl development environments using perlbrew for version management.

perlbrew Overview

perlbrew manages multiple Perl installations in user space without root access.

Benefits

• Install any Perl version without root
• Switch between versions instantly
• Isolated module installations per version
• Test against multiple Perl versions

Installation

Quick Install

# Download and run installer
curl -L https://install.perlbrew.pl | bash

# Initialize perlbrew
perlbrew init

# Add to shell profile (~/.bashrc or ~/.zshrc)
source ~/perl5/perlbrew/etc/bashrc

Verify Installation

perlbrew version
perlbrew list
which perl

Installing Perl Versions

List Available Versions

# Show all available versions
perlbrew available

# Show only stable releases
perlbrew available | grep -E '^\s*perl-5\.\d+\.\d+$'

Install a Version

# Install latest stable
perlbrew install perl-5.38.2

# Install with threading
perlbrew install perl-5.38.2 -Dusethreads

# Install with optimizations
perlbrew install perl-5.38.2 -Doptimize=-O2

# Quick install (skip tests)
perlbrew install perl-5.38.2 --notest

# Install with custom name
perlbrew install perl-5.38.2 --as perl-5.38-dev

Common Build Options

Switching Versions

# Switch for current shell
perlbrew use perl-5.38.2

# Set permanent default
perlbrew switch perl-5.38.2

# Temporary switch with command
perlbrew exec --with perl-5.38.2 perl -v

# Return to system Perl
perlbrew switch-off
perlbrew off  # Shortcut

Managing Installations

# List installed versions
perlbrew list

# Show current version
perlbrew info

# Remove a version
perlbrew uninstall perl-5.36.0

# Upgrade perlbrew itself
perlbrew self-upgrade

Library Management

perlbrew lib creates isolated module environments per Perl version.

Create Libraries

# Create a library for a project
perlbrew lib create perl-5.38.2@myproject

# List libraries
perlbrew lib list

# Switch to library
perlbrew use perl-5.38.2@myproject

# Delete library
perlbrew lib delete perl-5.38.2@myproject

Per-Project Libraries

# Create project-specific environment
perlbrew lib create perl-5.38.2@webapp

# Install modules to this library
perlbrew use perl-5.38.2@webapp
cpanm Mojolicious DBIx::Class

# Switch between project environments
perlbrew use perl-5.38.2@webapp
perlbrew use perl-5.38.2@cli-tools

cpanm Integration

# Install cpanm for current Perl
perlbrew install-cpanm

# Now cpanm is available
cpanm Module::Name

Testing Across Versions

# Run command with all installed Perls
perlbrew exec perl -v

# Run tests with all versions
perlbrew exec prove -l t/

# Run with specific versions
perlbrew exec --with perl-5.36.0,perl-5.38.2 prove t/

Shell Integration

Bash/Zsh

Add to ~/.bashrc or ~/.zshrc:

source ~/perl5/perlbrew/etc/bashrc

Fish

Add to ~/.config/fish/config.fish:

source ~/perl5/perlbrew/etc/perlbrew.fish

Project Configuration

.perl-version File

Create a .perl-version file in project root (for tools that support it):

5.38.2

Project Setup Script

#!/bin/bash
# setup-perl-env.sh

PERL_VERSION="perl-5.38.2"
PROJECT_LIB="myproject"

# Ensure perlbrew is loaded
source ~/perl5/perlbrew/etc/bashrc

# Install Perl if needed
if ! perlbrew list | grep -q "$PERL_VERSION"; then
    perlbrew install "$PERL_VERSION" --notest
fi

# Create project library if needed
if ! perlbrew lib list | grep -q "$PROJECT_LIB"; then
    perlbrew lib create "${PERL_VERSION}@${PROJECT_LIB}"
fi

# Switch to project environment
perlbrew use "${PERL_VERSION}@${PROJECT_LIB}"

# Install cpanm if needed
command -v cpanm >/dev/null || perlbrew install-cpanm

# Install project dependencies
cpanm --installdeps .

echo "Environment ready: $(perl -v | grep version)"

Directory Structure

perlbrew creates this structure:

~/perl5/perlbrew/
├── bin/           # perlbrew executable
├── build/         # Temporary build files
├── dists/         # Downloaded Perl sources
├── etc/           # Shell integration scripts
└── perls/         # Installed Perl versions
    ├── perl-5.36.0/
    └── perl-5.38.2/

Troubleshooting

Build Failures

# Check build log
less ~/perl5/perlbrew/build.perl-5.38.2.log

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

# Install with verbose output
perlbrew --verbose install perl-5.38.2

Path Issues

# Verify perlbrew is loaded
which perl
# Should show ~/perl5/perlbrew/perls/...

# Check current environment
perlbrew info

# Force reload
source ~/perl5/perlbrew/etc/bashrc

Cleanup

# Remove build artifacts
perlbrew clean

# Remove downloaded source archives
rm -rf ~/perl5/perlbrew/dists/*

Recommended Setup

For new development machines:

# 1. Install perlbrew
curl -L https://install.perlbrew.pl | bash
source ~/perl5/perlbrew/etc/bashrc

# 2. Install latest stable Perl
perlbrew install perl-5.38.2 --notest
perlbrew switch perl-5.38.2

# 3. Install cpanm
perlbrew install-cpanm

# 4. Install essential modules
cpanm App::cpanoutdated
cpanm Perl::Critic
cpanm Perl::Tidy

# 5. Add to shell profile
echo 'source ~/perl5/perlbrew/etc/bashrc' >> ~/.bashrc

Alternative: plenv

plenv is an alternative to perlbrew inspired by rbenv:

# Install plenv
git clone https://github.com/tokuhirom/plenv.git ~/.plenv
git clone https://github.com/tokuhirom/Perl-Build.git ~/.plenv/plugins/perl-build/

# Add to PATH
echo 'export PATH="$HOME/.plenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(plenv init -)"' >> ~/.bashrc

# Install Perl
plenv install 5.38.2
plenv global 5.38.2
plenv install-cpanm

plenv advantages:

• Simpler architecture (shims-based)
• Faster shell startup
• Per-directory version files (.perl-version)

perlbrew advantages:

• More mature and widely used
• Better library management
• More configuration options

Additional Resources

For CPAN module management, see the perl-cpan-ecosystem skill.