NAME

Perl5::Dist::Backcompat - Analyze dist/ distributions for CPAN release viability

SYNOPSIS

my $params = {
    perl_workdir => '/path/to/git/checkout/of/perl',
    verbose => 1,
};
my $self = Perl5::Dist::Backcompat->new( $params );

DESCRIPTION

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.

PREREQUISITES

perl 5.14.0 or newer, with the following modules installed from CPAN:

CPAN::DistnameInfo
Data::Dump
File::Copy::Recursive::Reduced

PUBLIC METHODS

`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.
- 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.)
- 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.
- verbose
  
  Boolean. Extra output during operation. Defaults to off (0), but recommended (1).
Return Value

Perl5::Dist::Backcompat object.

`init()`

Purpose

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.
Arguments
```
$self->init();
```
None; all data needed is found within the object.
Return Value

Returns the object itself.

`categorize_distros()`

Purpose

Categorize each dist/ distro in one of 4 categories based on the status and appropriateness of its Makefile.PL (if any).
Arguments
```
$self->categorize_distros();
```
None; all data needed is already within the object.
Return Value

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.
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.

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.
- 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.
- 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.

`show_makefile_pl_status`

Purpose

Display a chart listing dist/ distros in one column and the status of their respective Makefile.PLs in the second column.
Arguments
```
$self->show_makefile_pl_status();
```
None; this method simply displays data already present in the object.
Return Value

Returns a true value when complete.
Comment

Does nothing unless a true value for verbose was passed to new().

`get_distros_for_testing()`

Purpose

Assemble the list of dist/ distros which the program will actually test against older perls.
Arguments
```
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.
Return Value

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.
Comment

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.

`validate_older_perls()`

Purpose

Validate the paths and executability of the older perl versions against which we're going to test dist/ distros.
Arguments
```
my @perls = $self->validate_older_perls();
```
None; all necessary information is found within the object.
Return Value

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()`

Purpose

Test a given dist/ distro against each of the older perls against which it is eligible to be tested.
Arguments
```
$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.
Return Value

Returns the object itself.
Comment

The method will loop over the selected distros, calling test_one_distro_against_older_perls() against each.

`print_distro_summaries()`

Purpose

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.

Arguments

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} );
```
Return Value

Returns true value upon success.
Comment

You'll probably want to redirect or tee STDOUT to a file for further study.

`tally_results()`

Purpose

Provide an overall summary of PASSes and FAILs in the distro/perl-version matrix.
Arguments

None, all data needed is stored within object.
Return Value

Array ref with 4 elements: overall attempts, overall passes, overall failures, overall skipped.
Comment

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.

INTERNAL METHODS

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_distro_against_older_perls()`

Purpose

Test one selected dist/ distribution against the list of older perls.
Arguments

Single string holding the name of the distro in Some-Distro format.
Return Value

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.
- configure
  
  The result of calling perl Makefile.PL: 1 for success; 0 for failure; undef for not attempted.
- make
  
  The result of calling make: same meaning as above.
- make test
  
  The result of calling make test: same meaning as above.

`print_distro_summary()`

Purpose

Create a file holding a summary of the results for running one distro against each of the selected perls.

Arguments

$self->print_distro_summary('Some-Distro');

String holding name of distro.

Return Value

Returns true value on success.

Comment

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 },
}

INTERNAL SUBROUTINES

`sanity_check()`

Purpose

Assure us that our environment is adequate to the task.
Arguments
```
sanity_check(\%distmodules, $verbose);
```
List of two scalars: (i) reference to the hash which is storing list of dist/ distros; (ii) verbosity selection.
Return Value

Implicitly returns true on success, but does not otherwise return any meaningful value.
Comment

If verbosity is selected, displays the current git commit and other useful information on STDOUT.

`read_manifest()`

Purpose

Get a sorted list of all files in MANIFEST (without their descriptions).
Arguments
```
read_manifest('/path/to/MANIFEST');
```
One scalar: the path to MANIFEST in a git checkout of the Perl 5 core distribution.
Return Value

List (sorted) of all files in MANIFEST.
Comment

Depends on sort_manifest() from Porting/manifest_lib.pl.

(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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

PREREQUISITES

PUBLIC METHODS

new()

init()

categorize_distros()

show_makefile_pl_status

get_distros_for_testing()

validate_older_perls()

test_distros_against_older_perls()

print_distro_summaries()

tally_results()