Perl5::Dist::Backcompat - Analyze dist/ distributions for CPAN release viability
my $params = { perl_workdir => '/path/to/git/checkout/of/perl', verbose => 1, }; my $self = Perl5::Dist::Backcompat->new( $params );
This module serves as the backend for the program p5-dist-backcompat which is also part of the Perl5-Dist-Backcompat distribution. This document's focus is on documenting the methods used publicly in that program as well as internal methods and subroutines called by those public methods. For discussion on the problem which this distribution tries to solve, and how well it currently does that or not, please (i) read the plain-text README in the CPAN distribution or the README.md in the GitHub repository; and (ii) read the front-end program's documentation via perldoc p5-dist-backcompat.
perl 5.14.0 or newer, with the following modules installed from CPAN:
CPAN::DistnameInfo
Data::Dump
File::Copy::Recursive::Reduced
new()
Purpose
Perl5::Dist::Backcompat constructor.
Arguments
my $self = Perl5::Dist::Backcompat->new( $params );
Single hash reference. Currently valid keys for this hashref are:
path_to_perls
String holding absolute path to directory on disk where older perl executables are stored. Defaults to /media/Tux/perls-t/bin.
/media/Tux/perls-t/bin
perl_workdir
String holding absolute path to directory holding a git checkout of Perl 5 core distribution and which has been built up through make.
tarball_dir
String holding absolute path to directory holding tarballs of the most recent CPAN releases of dist/ distros.
older_perls_file
String holding path to file whose records list the versions of perl against which we intend to test the tarballs of dist/ distros found in tarball_dir. In that file, these versions match this pattern: ^perl5\.\d{1,2}\.\d1,2}$, e.g., perl5.14.4. (There is a default value which is only meaningful if you're starting in a git checkout of this Perl5-Dist-Backcompat library.)
^perl5\.\d{1,2}\.\d1,2}$
perl5.14.4
distro_metadata_file
String holding path to file whose records are pipe-delimited fields holding metadata about particular dist/ distributions.
# name|minimum_perl_version|needs_threaded_perl|needs_ppport_h|needs_threads_h|needs_shared_h threads|5.014000|1|1|1|0
(There is a default value which is only meaningful if you're starting in a git checkout of this Perl5-Dist-Backcompat library.)
host
String holding system's hostname. Defaults to dromedary.p5h.org.
dromedary.p5h.org
verbose
Boolean. Extra output during operation. Defaults to off (0), but recommended (1).
0
1
Return Value
Perl5::Dist::Backcompat object.
init()
Guarantee that we can find the perl executables we'll be using; the git checkout of the core distribution; metadata files and loading of data therefrom.
$self->init();
None; all data needed is found within the object.
Returns the object itself.
categorize_distros()
Categorize each dist/ distro in one of 4 categories based on the status and appropriateness of its Makefile.PL (if any).
$self->categorize_distros();
None; all data needed is already within the object.
Returns the object.
Comment
Since our objective is to determine the CPAN release viability of code found within dist/ distros in core, we need various ways to categorize those distros. This method will make a categorization based on the status of the distros's Makefile.PL. The categories will be mutually exclusive. By order of processing the categories will be:
unreleased: As based on an examination of %Maintainers::Modules in Porting/Maintainers.PL, at least one distro has no current CPAN release. Such modules will be categorized as unreleased.
%Maintainers::Modules
unreleased
cpan: Certain dist/ distros have a CPAN release which contains a Makefile.PL. Such distros may also have a Makefile.PL in core; that Makefile.PL may or may not be functionally identical to that on CPAN. In either case, we shall make an assumption that the Makefile.PL found in the most recent CPAN release is the version to be preferred for the purpose of this program. Such distros will be categorized as cpan.
cpan
Note: The following 3 categories should be considered dormant because, as the code in this methods is currently structured, all current dist/ distros are categorized as either unreleased or cpan. These categories may be removed in a future release.
core: Certain dist/ distros have a Makefile.PL in core. Assuming that such a distro has not already been categorized as cpan, we will use that version in this program. Such distros will be categorized as core.
core
generated: If a dist/ distro has no Makefile.PL either on CPAN or in core but, at the end of make in the Perl 5 build process does have a Makefile.PL generated by that process, we will categorize such a distro as generated.
generated
tbd: The remaining dist/ distros have a Makefile.PL neither on CPAN nor in core. For purpose of compilation in core they may have a Makefile generated by core's make_ext.pl process, but this file, if created, does not appear to be retained on disk at the end of make. Such a distro might lack a Makefile.PL in its CPAN release because the CPAN releasor uses technology such as Dist::Zilla to produce such a release and such technology does not require a Makefile.PL to be included in the CPAN tarball. At the present time we will categorize such distros as tbd and these will be skipped by subsequent methods.
tbd
show_makefile_pl_status
Display a chart listing dist/ distros in one column and the status of their respective Makefile.PLs in the second column.
$self->show_makefile_pl_status();
None; this method simply displays data already present in the object.
Returns a true value when complete.
Does nothing unless a true value for verbose was passed to new().
get_distros_for_testing()
Assemble the list of dist/ distros which the program will actually test against older perls.
my @distros_for_testing = $self->get_distros_for_testing( [ @distros_requested ] );
Single arrayref, optional (though recommended). If no arrayref is provided, then the program will test all dist/ distros except those whose "Makefile.PL status" is unreleased.
List holding distros to be tested. (This is provided for readability of the code, but the list will be stored within the object and subsequently referenced therefrom.
In a production program, the list of distros selected for testing may be provided on the command-line and processed by Getopt::Long::GetOptions() within that program. But it's only at this point that we need to add such a list to the object.
Getopt::Long::GetOptions()
validate_older_perls()
Validate the paths and executability of the older perl versions against which we're going to test dist/ distros.
my @perls = $self->validate_older_perls();
None; all necessary information is found within the object.
List holding older perl executables against which distros will be tested. (This is provided for readability of the code, but the list will be stored within the object and subsequently referenced therefrom.
test_distros_against_older_perls()
Test a given dist/ distro against each of the older perls against which it is eligible to be tested.
$self->test_distros_against_older_perls('/path/to/debugging/directory');
String holding absolute path to an already created directory to which files can be written for later study and debugging. That directory may be created by File::Temp:::tempdir(), but it should not be created with ( CLEANUP = 1)>; the user should manually remove this directory after analysis is complete.
File::Temp:::tempdir()
( CLEANUP =
The method will loop over the selected distros, calling test_one_distro_against_older_perls() against each.
test_one_distro_against_older_perls()
print_distro_summaries()
Print on STDOUT:
A list of the results_dir/Some-Distro.summary.txt files created for each tested distro (each file containing a summary of the results for that distro against each designated perl executable. Example:
Summaries --------- Attribute-Handlers /tmp/29LsgNfjVb/Attribute-Handlers.summary.txt Carp /tmp/29LsgNfjVb/Carp.summary.txt Data-Dumper /tmp/29LsgNfjVb/Data-Dumper.summary.txt ... threads /tmp/29LsgNfjVb/threads.summary.txt threads-shared /tmp/29LsgNfjVb/threads-shared.summary.txt
A concatenation of all those files.
To simply list the summary files:
$self->print_distro_summaries();
To list the summary files and concatenate their content:
$self->print_distro_summaries( {cat_summaries => 1} );
Returns true value upon success.
You'll probably want to redirect or tee STDOUT to a file for further study.
tally_results()
Provide an overall summary of PASSes and FAILs in the distro/perl-version matrix.
None, all data needed is stored within object.
Array ref with 4 elements: overall attempts, overall passes, overall failures, overall skipped.
An entry in the distro/perl-version matrix is skipped if there is a failure running Makefile.PL, which causes the configure, make and test values to be all undefined.
configure
make
test
The following methods use the Perl5::Dist::Backcompat object but are called from within the public methods. Other than this library's author, you shouldn't need to explicitly call these methods (or the internal subroutines documented below) in a production program. The documentation here is mainly for people working on this distribution itself.
Test one selected dist/ distribution against the list of older perls.
Single string holding the name of the distro in Some-Distro format.
Some-Distro
Hash reference with one element for each perl executable selected:
{ "5.006002" => { a => "perl5.6.2", configure => 1, make => 0, test => undef }, "5.008009" => { a => "perl5.8.9", configure => 1, make => 0, test => undef }, "5.010001" => { a => "perl5.10.1", configure => 1, make => 0, test => undef }, ... "5.034000" => { a => "perl5.34.0", configure => 1, make => 1, test => 1 }, }
The value of each element is a hashref with elements keyed as follows:
a
Perl version in the spelling used in the default value for path_to_perls.
The result of calling perl Makefile.PL: 1 for success; 0 for failure; undef for not attempted.
undef
The result of calling make: same meaning as above.
make test
The result of calling make test: same meaning as above.
print_distro_summary()
Create a file holding a summary of the results for running one distro against each of the selected perls.
$self->print_distro_summary('Some-Distro');
String holding name of distro.
Returns true value on success.
File created will be named like /path/to/results_dir/Some-Distro.summary.txt.
File's content will look like this:
Attribute-Handlers v5.35.7-48-g34e3587 { "5.006002" => { a => "perl5.6.2", configure => 1, make => 0, test => undef }, "5.008009" => { a => "perl5.8.9", configure => 1, make => 0, test => undef }, "5.010001" => { a => "perl5.10.1", configure => 1, make => 0, test => undef }, ... "5.034000" => { a => "perl5.34.0", configure => 1, make => 1, test => 1 }, }
sanity_check()
Assure us that our environment is adequate to the task.
sanity_check(\%distmodules, $verbose);
List of two scalars: (i) reference to the hash which is storing list of dist/ distros; (ii) verbosity selection.
Implicitly returns true on success, but does not otherwise return any meaningful value.
If verbosity is selected, displays the current git commit and other useful information on STDOUT.
read_manifest()
Get a sorted list of all files in MANIFEST (without their descriptions).
read_manifest('/path/to/MANIFEST');
One scalar: the path to MANIFEST in a git checkout of the Perl 5 core distribution.
List (sorted) of all files in MANIFEST.
Depends on sort_manifest() from Porting/manifest_lib.pl.
sort_manifest()
(This is so elementary and useful that it should probably be in Porting/manifest_lib.pl!)
To install Perl5::Dist::Backcompat, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl5::Dist::Backcompat
CPAN shell
perl -MCPAN -e shell install Perl5::Dist::Backcompat
For more information on module installation, please visit the detailed CPAN module installation guide.