Carmel CPAN Artifact Repository Manager

Carmel stores build artifacts in a central repository, typically at $HOME/.carmel/{version}-{archname}/builds.

When you run carmel install, it computes the best versions satisfying cpanfile, installs them via cpanm into this central repository, and records the mapping in cpanfile.snapshot.

When running via carmel exec, Carmel dynamically prepends the necessary build directories to the Perl @INC array, allowing you to run applications with pinned dependencies without manually managing PERL5LIB.

While Carmel manages dependencies in $HOME/.carmel to avoid polluting your project directory, you can explicitly create a local directory containing your project's dependencies by using the carmel rollout command. This is useful when you need a standard local directory for specific deployment or build tasks.

# Example command to populate the local directory
carmel rollout

Use the update command to modify the versions pinned in your snapshot:

• carmel update <Module>: Updates a specific module to the latest version from CPAN (and updates its dependencies if necessary).
• carmel update <Module>@<Version>: Pins a module to a specific version.
• carmel update: Updates all modules listed in your cpanfile to their latest versions.

# Update a specific module
carmel update Plack

# Pin modules to specific versions
carmel update DBI@1.633 Plack@1.0000

# Update everything in the snapshot
carmel update

If you want to vendor your dependencies for use with cpanm on a target machine (e.g., in a CI/CD pipeline or a restricted environment), use carmel package. This creates a directory containing tarballs and CPAN-style package indexes.

# Create a vendor cache
carmel package

# On the target machine, use cpanm to install from the vendor cache
cpanm -L ./local --from $PWD/vendor/cache -nq --installdeps .

To avoid requiring Carmel on production hosts or dealing with large @INC overhead, use carmel rollout. This command extracts all files from the pinned dependencies into a standard Perl library directory structure (defaults to ./local). This directory can then be used like a local::lib path.

# Roll out dependencies to the ./local directory
carmel rollout

# Run your application using the rolled-out path
perl -Ilocal/lib/perl5 local/bin/starman -p 8080 myapp.psgi

In a development workflow, use carmel install to set up your environment or update it when cpanfile changes. This command updates your build artifacts and saves the specific versions used to cpanfile.snapshot. You should commit both cpanfile and cpanfile.snapshot to your version control system to ensure consistency across machines.

To run your application using the exact versions pinned in your snapshot, use carmel exec.

# Setup environment
carmel install

# Run an application (e.g., Starman) with pinned dependencies
carmel exec starman -p 8080 myapp.psgi

# Run a perl command directly
carmel exec perl -e 'use Carmel::Preload;'

The carmel executable is used to manage Perl dependencies and environments via cpanfile and cpanfile.snapshot. It provides a suite of commands for loading modules, managing snapshots, and running scripts within a controlled environment.

Based on the internal CLI logic, the tool operates by interpreting commands passed to Carmel::App. Common usage patterns include running commands within specific directories or executing scripts using the artifacts managed by carmel.

Version Conflicts

Conflicts can occur when a new dependency requires a version of a module that contradicts what is currently pinned in cpanfile.snapshot. Recommendation: Always run carmel install before making changes to your cpanfile. This ensures the build cache is prepared. If a conflict occurs, use carmel update <Module> to force an update of the conflicting module.

Missing Artifacts

If you see the error Can't find an artifact for Foo, it means a dependency was missed during the initial carmel install. This is a known issue with certain modules. Check the Carmel issue tracker for known problematic modules.

Taint Mode

Carmel does not support Perl's Taint mode (-T). Running with -T will result in an error: Insecure dependency in require while running with -T switch.

For developers integrating carmel into testing frameworks or automation scripts, the xt::CLI module provides a TestCLI class to simulate and capture CLI execution.

Key methods for programmatic execution include:

• run(@args): Executes a carmel command and captures stdout, stderr, and the exit_code.
• cmd(@args): Executes a system command and captures output.
• run_in_dir($dir, @args): Executes a carmel command within a specific subdirectory.
• cmd_in_dir($dir, @args): Executes a system command within a specific subdirectory.
• run_ok(@args): Runs a command and asserts that the exit_code is 0.
• run_fails(@args): Runs a command and asserts that the exit_code is non-zero.

use xt::CLI;

my $cli = cli(clean => 1);
$cli->write_cpanfile("module A", "module B");
$cli->run_ok("list");