NAME
Devel::Cover::Collection - Code coverage for a collection of modules
VERSION
version 1.52
SYNOPSIS
use Devel::Cover::Collection;
my $collection = Devel::Cover::Collection->new(
results_dir => "/path/to/results",
bin_dir => "/path/to/bin",
workers => 4,
verbose => 1,
);
# Add modules to process
$collection->add_modules("Some::Module", "Another::Module");
# Or load from a file
$collection->set_module_file("/path/to/modules.txt");
$collection->process_module_file;
# Run coverage collection
$collection->cover_modules;
# Generate HTML reports
$collection->generate_html;DESCRIPTION
Devel::Cover::Collection provides infrastructure for running code coverage analysis across a collection of CPAN modules. It is primarily used by the CPANCover service (http://cpancover.com) to generate coverage reports for CPAN distributions.
The module supports:
Parallel processing of multiple modules
Docker-based isolation for coverage runs
HTML and JSON report generation
Tracking of covered and failed modules
Compression of old coverage results
This module requires Perl 5.42.0 or later and uses the builtin class feature.
CONSTRUCTOR
new
my $collection = Devel::Cover::Collection->new(%options);Creates a new Collection object. All options are optional and have sensible defaults.
ATTRIBUTES
Read-Only Attributes
These attributes can only be set via the constructor.
bin_dir
Directory containing the cover binary. Used when running coverage commands.
cpancover_dir
Directory for CPANCover-specific files and configuration.
cpan_dir
An arrayref of CPAN directories to search for build directories. Defaults to ~/.cpan and ~/.local/share/.cpan if they exist.
results_dir
Directory where coverage results are stored. Required for most operations.
dryrun
Boolean. If true, commands are printed but not executed. Default: 0.
env
Environment identifier (e.g., 'prod', 'dev'). Default: 'prod'.
force
Boolean. If true, re-run coverage even for already-covered modules. Default: 0.
output_file
Filename for the main output file. Default: 'index.html'.
report
Report format to generate. Default: 'html_basic'.
timeout
Timeout in seconds for coverage runs. Default: 1800 (30 minutes).
verbose
Boolean. If true, print additional progress information. Default: 0.
workers
Number of parallel workers for coverage runs. Default: 0 (no parallelism).
docker
Docker command to use. Default: 'docker'.
local
Boolean. If true, run in local mode without Docker. Default: 0.
Read-Write-Private Attributes
These attributes have public readers but private setters. Use the provided methods to modify them.
build_dirs
Arrayref of build directories to process. Modify via add_build_dirs.
modules
Arrayref of module names to process. Modify via add_modules or set_modules.
module_file
Path to a file containing module names (one per line). Set via set_module_file.
Read-Write Attributes
These attributes can be read and written directly.
dir
$collection->dir("/path/to/dir");
my $dir = $collection->dir;Working directory for the current operation.
file
$collection->file("/path/to/file");
my $file = $collection->file;Current file being processed.
METHODS
Module Management
add_modules
$collection->add_modules(@module_names);Appends modules to the list of modules to process.
set_modules
$collection->set_modules(@module_names);Replaces the entire module list with the given modules.
set_module_file
$collection->set_module_file("/path/to/modules.txt");Sets the path to a file containing module names.
process_module_file
$collection->process_module_file;Reads module names from the file specified by module_file and adds them to the modules list. Blank lines and lines starting with # are ignored.
Build Operations
build_modules
$collection->build_modules;Builds all modules in the modules list using cpan -Ti. If force is true, uses the -f flag.
add_build_dirs
$collection->add_build_dirs;Scans the CPAN directories for build directories and adds them to build_dirs.
local_build
$collection->local_build;Orchestrates a complete local build workflow: processes the module file, builds modules, adds build directories, and runs coverage on all.
Coverage Operations
run
$collection->run($build_dir);Runs coverage analysis on a single build directory. Creates coverage reports in the results directory.
run_all
$collection->run_all;Runs coverage analysis on all directories in build_dirs, using parallel workers if configured.
cover_modules
$collection->cover_modules;Covers all modules using Docker containers. Processes the module file, then runs coverage for each module in parallel.
Report Generation
generate_html
$collection->generate_html;Generates HTML coverage reports for all modules in the results directory. Creates an index page, per-module pages, and an about page.
coverage_class
my $css_class = $collection->coverage_class($percentage);Converts a coverage percentage to a CSS class name for HTML reports:
n/a -> "na"
< 75 -> "c0"
< 90 -> "c1"
< 100 -> "c2"
100 -> "c3"write_summary
$collection->write_summary($vars);Writes the HTML summary pages using Template Toolkit. Called by generate_html.
write_json
$collection->write_json($vars);Writes a JSON file (cpancover.json) containing coverage data for all modules.
Status Tracking
is_covered
if ($collection->is_covered($module_dir)) { ... }Returns true if coverage results exist for the given module directory.
is_failed
if ($collection->is_failed($module_dir)) { ... }Returns true if the module has been marked as failed.
set_covered
$collection->set_covered($module_dir);Marks a module as successfully covered (removes any failure marker).
set_failed
$collection->set_failed($module_dir);Marks a module as failed by creating a timestamp file in the failed directory.
Path Methods
made_res_dir
my ($path, $output) = $collection->made_res_dir;
my ($path, $output) = $collection->made_res_dir($subdir);Creates and returns the results directory path. If $subdir is provided, creates that subdirectory within the results directory.
covered_dir
my $path = $collection->covered_dir($module_dir);Returns the path where coverage results for a module are stored.
failed_dir
my $path = $collection->failed_dir;Returns the path to the directory containing failure markers.
failed_file
my $path = $collection->failed_file($module_dir);Returns the path to the failure marker file for a module.
dc_file
my $path = $collection->dc_file;Returns the path to the dc utility script.
Maintenance
compress_old_versions
$collection->compress_old_versions($num_versions_to_keep);Compresses old coverage results, keeping only the specified number of most recent versions for each module.
get_latest
$collection->get_latest;Fetches and prints the latest CPAN release information using CPAN::Releases::Latest.
System Commands
sys
my $output = $collection->sys(@command);Runs a system command, displaying the first portion of output immediately and buffering the rest. Returns the output on success, empty string on failure.
bsys
my $output = $collection->bsys(@command);Like sys, but buffers all output (no immediate display).
fsys
my $output = $collection->fsys(@command);Like sys, but dies on failure.
fbsys
my $output = $collection->fbsys(@command);Like bsys, but dies on failure.
EMBEDDED CLASSES
Devel::Cover::Collection::Template::Provider
A subclass of Template::Provider that provides built-in templates for HTML report generation. The following templates are available:
colours - CSS colour definitions
html - Base HTML wrapper
summary - Main index page
about - About page
module_by_start - Module listing by first letter
DEPENDENCIES
Perl 5.42.0 or later (for builtin
classfeature)
SEE ALSO
Devel::Cover, http://cpancover.com
AUTHOR
Paul Johnson <paul@pjcj.net>
LICENCE
Copyright 2014-2026, Paul Johnson (paul@pjcj.net)
This software is free. It is licensed under the same terms as Perl itself.
The latest version of this software should be available on CPAN and from my homepage: https://pjcj.net/.