Test::Against::Build - Test CPAN modules against specific Perl build
my $self = Test::Against::Build->new( { build_tree => '/path/to/top/of/build_tree', results_tree => '/path/to/top/of/results_tree', verbose => 1, } ); my $gzipped_build_log = $self->run_cpanm( { module_file => '/path/to/cpan-river-file.txt', title => 'cpan-river-1000', verbose => 1, } ); $ranalysis_dir = $self->analyze_cpanm_build_logs( { verbose => 1 } ); $fcdvfile = $self->analyze_json_logs( { verbose => 1, sep_char => '|' } );
This library should be used by anyone who wishes to assess the impact of a given build of the Perl 5 core distribution on the installability of libraries found on the Comprehensive Perl Archive Network (CPAN).
Perl 5 undergoes an annual development cycle whose components typically include:
Individual commits to the Perl 5 git repository
These commits may be identified by commit IDs (SHAs), branches or tags.
Release tarballs
Monthly development release tarballs
Whose version numbers follow the convention of 5.27.0, 5.27.1, etc., where the middle digits are always odd numbers.
5.27.0
5.27.1
Release Candidate (RC) tarballs
Whose version numbers follow the convention of 5.28.0-RC1, 5.28.0-RC2, 5.28.1-RC1.
5.28.0-RC1
5.28.0-RC2
5.28.1-RC1
Production release tarballs
Whose version numbers follow the convention of 5.28.0 (new release); 5.28.1, 5.28.2, etc. (maintenance releases).
5.28.0
5.28.1
5.28.2
You can configure, build and install a perl executable starting from any of the above components and you can install CPAN modules against any such perl executable. Given a list of specific CPAN modules, you may want to be able to compare the results you get from trying to install that list against different perl executables built from different commits or releases at various points in the development cycle. To make such comparisons, you will need to have data generated and recorded in a consistent format. This library provides methods for that data generation and recording.
For any particular attempt to build a perl executable from any of the starting points described above, Test::Against::Build guarantees that there exists on disk two directory trees:
The build tree is a directory beneath which perl, other executables and libraries will be installed (or already are installed). As such, the structure of this tree will look like this:
top_of_build_tree/bin/ bin/perl bin/perldoc bin/cpan bin/cpanm ... top_of_build_tree/lib/ lib/perl5/ lib/perl5/5.29.0/ lib/perl5/site_perl/ ... top_of_build_tree/.cpanm/ top_of_build_tree/.cpanreporter/
Test::Against::Build presumes that you will be using Miyagawa's cpanm utility to install modules from CPAN. The .cpanm and .cpanreporter directories will be the locations where data concerning attempts to install CPAN modules are recorded.
The results tree is a directory beneath which data parsed from the .cpanm directory is formatted and stored. Its format looks like this:
top_of_results_tree/analysis/ buildlogs/ storage/
The names of the top-level directories are arbitrary; the names of their subdirectories are not. The top-level directories may be located anywhere writable on disk and need not share a common parent directory. It is the Test::Against::Build object which will establish a relationship between the two trees.
Test::Against::Build does not provide you with methods to build or install these executables. It presumes that you know how to build perl from source, whether that be from a specific git checkout or from a release tarball. It further presumes that you know how to install cpanm against that perl. It does provide a method to identify the directory you should use as the value of the -Dprefix= option to Configure. It also provides methods to determine that you have installed perl and cpanm in the expected locations. Once that determination has been made, it provides you with methods to run cpanm against a specific list of modules, parse the results into files in JSON format and then summarize those results in a delimiter-separated-values file (such as a pipe-separated-values (.psv) file).
-Dprefix=
.psv
Why, you may ask, does Test::Against::Build not provide methods to install these executables? There are a number of reasons why not.
perl and cpanm already installed
You may already have on disk one or more perls built from specific commits or release tarballs and have no need to re-install them.
Starting from git commit versus starting from a tarball
You can build perl either way, but there's no need to have code in this package to express both ways.
Many ways to configure perl
perl configuration is a matter of taste. The only thing which this package needs to provide you is a value for the -Dprefix= option. It should go without saying that if want to measure the impact on CPAN modules of two different builds of perl, you should call Configure with exactly the same set of options for each.
The examples below will provide guidance.
new()
Purpose
Test::Against::Build constructor. Guarantees that the build tree and results tree have the expected directory structure. Determines whether perl and cpanm have already been installed or not.
Arguments
my $self = Test::Against::Build->new( { build_tree => '/path/to/top/of/build_tree', results_tree => '/path/to/top/of/results_tree', verbose => 1, } );
Return Value
Test::Against::Build object.
Comment
The following accessors return the absolute path to the directories in their names:
get_build_tree()
get_bin_dir()
get_lib_dir()
get_cpanm_dir()
get_cpanreporter_dir()
get_results_tree()
get_analysis_dir()
get_buildlogs_dir()
get_storage_dir()
is_perl_built()
Determines whether a perl executable has actually been installed in the directory returned by get_bin_dir().
None.
1 for yes; 0 for no.
1
0
is_cpanm_built()
Determines whether a cpanm executable has actually been installed in the directory returned by get_bin_dir().
run_cpanm()
Use cpanm to install selected Perl modules against the perl built for testing purposes.
Two mutually exclusive interfaces:
Modules provided in a list
$gzipped_build_log = $self->run_cpanm( { module_list => [ 'DateTime', 'AnyEvent' ], title => 'two-important-libraries', verbose => 1, } );
Modules listed in a file
$gzipped_build_log = $self->run_cpanm( { module_file => '/path/to/cpan-river-file.txt', title => 'cpan-river-1000', verbose => 1, } );
Each interface takes a hash reference with the following elements:
module_list OR module_file
module_list
module_file
Mutually exclusive; must use one or the other but not both.
The value of module_list must be an array reference holding a list of modules for which you wish to track the impact of changes in the Perl 5 core distribution over time. In either case the module names are spelled in Some::Module format -- i.e., double-colons -- rather than in Some-Module format (hyphens).
Some::Module
Some-Module
title
String which will be used to compose the name of project-specific output files. Required.
verbose
Extra information provided on STDOUT. Optional; defaults to being off; provide a Perl-true value to turn it on. Scope is limited to this method.
analyze_cpanm_build_logs()
Parse the build.log created by running run_cpanm(), creating JSON files which log the results of attempting to install each module in the list or file.
$ranalysis_dir = $self->analyze_cpanm_build_logs( { verbose => 1 } );
Hash reference which, at the present time, can only take one element: verbose. Optional.
String holding absolute path to the directory holding .log.json files for a particular run of run_cpanm().
analyze_json_logs()
my $gzipped_build_log = $self->run_cpanm( { module_file => '/path/to/cpan-river-file.txt', title => 'cpan-river-1000', verbose => 1, } ); $ranalysis_dir = $self->analyze_cpanm_build_logs( { verbose => 1 } ); $fcdvfile = $self->analyze_json_logs( { verbose => 1, sep_char => '|' } ); 834:sub setup_results_directories { 933:sub run_cpanm { 1010:sub gzip_cpanm_build_log {
To install Test::Against::Dev, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Against::Dev
CPAN shell
perl -MCPAN -e shell install Test::Against::Dev
For more information on module installation, please visit the detailed CPAN module installation guide.