--- name: "Devel::Cover::Collection" section: "3pm" platform: "linux" package: "perl-devel-cover" version: "1.52-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Devel::Cover::Collection" --- # Devel::Cover::Collection(3pm) Code coverage for a collection of modules ## 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 (\) 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 `"class"` feature) - • Devel::Cover::DB - • JSON::MaybeXS - • Parallel::Iterator - • Template - • Time::HiRes ## SEE ALSO Devel::Cover, \ ## AUTHOR Paul Johnson \ ## 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: \.