/ 
Perl5-Dist-Backcompat-0.10
River stage zero No dependents
/ p5-dist-backcompat

NAME

p5-dist-backcompat - Will changes to dist/ build on older perls?

SYNOPSIS

Start in a git checkout of the Perl 5 source code with a threaded build of perl at a particular commit, branch or tag:

$ cd ${PERL_CHECKOUT_DIR}
$ git clean -dfx
$ sh ./Configure -des -Dusedevel -Duseithreads
$ make

From that directory or another, call this program:

$ p5-dist-backcompat \
    --perl_workdir=/path/to/git/checkout/of/perl \
    --cat_summaries \
    --verbose \
    --path_to_perls=/path/to/directory/holding/executables \
    --tarball_dir=/path/to/directory/holding/dist/tarballs/downloaded/from/CPAN \
    --older_perls_file=/path/to/file/holding/older/perls/metadata \
    --distro_metadata_file=/path/to/file/holding/dist/distros/metadata

Omit the --distro switch-parameter pairs and you will test all dist/ distros. (This will take approximately 45 minutes.)

PREREQUISITES

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

  • CPAN::DistnameInfo

  • Data::Dump

  • File::Copy::Recursive::Reduced

And with the library for which this program is a front end: Perl5::Dist::Backcompat (not yet available on CPAN).

Program will use a variety of modules which are shipped with the Perl 5 core distribution.

COMMAND-LINE SWITCHES

  • --perl_workdir

    Switch-parameter pair. Parameter should be an absolute path to the directory holding a git checkout of the Perl 5 core distribution; user must checkout branch, tag or commit in that directory as needed, then configure and build a threaded perl as far as make.

  • --distro

    Switch-parameter pair. Parameter should be hyphen-separated name of directory under /dist, e.g., ExtUtils-ParseXS, not ExtUtils::ParseXS. May be called more than once, e.g.:

    --distro Search-Dict --distro Safe --distro=Data-Dumper

    The parameters must be spelled "distribution-style" (Some-Distro) rather than "module-style" (Some::Distro).

  • --cat_summaries

    Flag. When set to true, will direct method print_distro_summaries() to concatenate all summaries on STDOUT.

  • --verbose

    Flag. Extra helpful output on STDOUT. Recommended, particularly with tee-ing of program's output to a file on disk.

  • --host

    Switch-parameter pair. Parameter should be the string returned by the system hostname call. Defaults to dromedary.p5h.org. (Until such time as we know that another host has a full set of executables for older perls, this is the only host on which this program can actually be run.)

  • --path_to_perls

    Switch-parameter pair. Parameter should be an absolute path to the directory holding binary executables of older perls. Defaults to /media/Tux/perls-t/bin, which is located on Dromedary.

  • --tarball_dir

    Switch-parameter pair. Parameter should be an absolute path to the directory where tarballs have been downloaded from CPAN of those dist/ distributions which have had a CPAN release.

  • --results_dir

    Switch-parameter pair. Parameter should be an absolute path to a directory where results files will be created. If not provided, a temporary directory created via File::Temp::tempdir() will be created.

OUTPUT

Results will be reported in plain-text files found in the directory specified by $results_dir. Let's assume that neither --verbose nor --cat-summaries has been requested. Let' further assume that we request reports on two distros: base and ExtUtils-ParseSX and that we're content to use a tempdir for results.

$ perl p5-dist-backcompat \
    --perl_workdir ${PERL_CHECKOUT_DIR} \
    --distro base \
    --distro ExtUtils-ParseXS

On STDOUT we would see something like this:

Beginning processing of requested distros;
  this will take some time ...
  FAIL: ExtUtils-ParseXS: 5.008009: make test

  Summaries
  ---------
  See results in /tmp/htXsoU2C1

In /tmp/htXsoU2C1Z we would see:

$ ls /tmp/htXsoU2C1Z/
base.perl5.10.1.txt  base.perl5.30.3.txt              ExtUtils-ParseXS.perl5.20.3.txt
base.perl5.12.5.txt  base.perl5.32.1.txt              ExtUtils-ParseXS.perl5.22.4.txt
base.perl5.14.4.txt  base.perl5.34.0.txt              ExtUtils-ParseXS.perl5.24.4.txt
base.perl5.16.3.txt  base.perl5.8.9.txt               ExtUtils-ParseXS.perl5.26.3.txt
base.perl5.18.4.txt  base.summary.txt                 ExtUtils-ParseXS.perl5.28.3.txt
base.perl5.20.3.txt  ExtUtils-ParseXS.perl5.10.1.txt  ExtUtils-ParseXS.perl5.30.3.txt
base.perl5.22.4.txt  ExtUtils-ParseXS.perl5.12.5.txt  ExtUtils-ParseXS.perl5.32.1.txt
base.perl5.24.4.txt  ExtUtils-ParseXS.perl5.14.4.txt  ExtUtils-ParseXS.perl5.34.0.txt
base.perl5.26.3.txt  ExtUtils-ParseXS.perl5.16.3.txt  ExtUtils-ParseXS.perl5.8.9.txt
base.perl5.28.3.txt  ExtUtils-ParseXS.perl5.18.4.txt  ExtUtils-ParseXS.summary.txt

That is one distro.perl_version.txt file for each combination of distro selected and older perl actually run, plus one distro.summary.txt file for each distro selected. (Some combinations are excluded because older perls cannot supply prerequisites needed by a CPAN distro's Makefile.PL, *.pm files or t/*.t files.)

If we examine ExtUtils-ParseXS.perl5.8.9.txt, we would see that the configured successfully with the Makefile.PL from its current CPAN distribution and that make also completed successfully. However, three of its test files are lacking a prerequisite. That cannot be supplied by our perl5.8.9 executable on disk.

If we now look at ExtUtils-ParseXS.summary.txt, we see:

$ cat /tmp/htXsoU2C1Z/ExtUtils-ParseXS.summary.txt
ExtUtils-ParseXS                                      v5.35.8-6-g441c427
{
  "5.006002" => { a => "perl5.6.2", configure => undef, make => undef, test => undef },
  "5.008009" => { a => "perl5.8.9", configure => 1, make => 1, test => 0 },
  "5.010001" => { a => "perl5.10.1", configure => 1, make => 1, test => 1 },
  "5.012005" => { a => "perl5.12.5", configure => 1, make => 1, test => 1 },
  "5.014004" => { a => "perl5.14.4", configure => 1, make => 1, test => 1 },
  "5.016003" => { a => "perl5.16.3", configure => 1, make => 1, test => 1 },
  "5.018004" => { a => "perl5.18.4", configure => 1, make => 1, test => 1 },
  "5.020003" => { a => "perl5.20.3", configure => 1, make => 1, test => 1 },
  "5.022004" => { a => "perl5.22.4", configure => 1, make => 1, test => 1 },
  "5.024004" => { a => "perl5.24.4", configure => 1, make => 1, test => 1 },
  "5.026003" => { a => "perl5.26.3", configure => 1, make => 1, test => 1 },
  "5.028003" => { a => "perl5.28.3", configure => 1, make => 1, test => 1 },
  "5.030003" => { a => "perl5.30.3", configure => 1, make => 1, test => 1 },
  "5.032001" => { a => "perl5.32.1", configure => 1, make => 1, test => 1 },
  "5.034000" => { a => "perl5.34.0", configure => 1, make => 1, test => 1 },
}

We interpret this to mean: "If we were to plop down ExtUtil-ParseXS's code as it appears in blead into a candidate for a CPAN release, we would expect that ..."

  • The program would not attempt even to configure against perl5.6.2, because we already have ruled that out due to previously observed failures of some kind.

  • On perl5.8.9, the CPAN distro candidate would pass perl Makefile.PL and make but fail during make test.

  • On all subsequent perls, ExtUtils-ParseXS would configure, build and test successfully.

We would then leave it to the person designated to do a new CPAN release of ExtUtils-ParseXS to determine what efforts need to be made to get it to pass on perl5.8.9 and whether efforts should be made to get it to work on perl5.6.2. Since, by definition as a dist/ distro, ExtUtils-ParseXS is "blead-upstream", the releasor might have to file tickets about problem's in the Perl 5 core distribution's issue queue.