devel/mktodo: Add some comments

[perl5.git] / dist / Devel-PPPort / devel / mktodo

#!/usr/bin/perl -w
################################################################################
#
#  mktodo -- generate baseline and todo files by running mktodo.pl
#
# It calls plain 'mktodo' on each perl version it finds based on the input
# parameters.
#
################################################################################
#
#  Version 3.x, Copyright (C) 2004-2013, Marcus Holland-Moritz.
#  Version 2.x, Copyright (C) 2001, Paul Marquess.
#  Version 1.x, Copyright (C) 1999, Kenneth Albanowski.
#
#  This program is free software; you can redistribute it and/or
#  modify it under the same terms as Perl itself.
#
################################################################################

use strict;
use Getopt::Long;

require './devel/devtools.pl';

our %opt = (
  base    => 0,     # If specified, this will generate base files, not todo ones
  check   => 1,     # Do extra checking
  verbose => 0,
  install => '/tmp/perl/install/default',
  blead   => 'bleadperl-debug',
);

# The way this works, is it expects to find perl binaries for a bunch of
# different versions in a given directory.  This defaults to the 'install' one
# listed above, but is overriddable by the --install parameter.  It also uses
# blead, again with an overridable default.
#
# It first verifies that the test file works properly for blead.
#
# Then it goes through the list of perl binaries sorted in decreasing order of
# version number.  If something works in version n, but not in version n-1,
# that means it was introduced (or perhaps fixed) in version n, and adds that
# thing to the version n list.
#
# After everything is done, we have lists of what got added when.  The --base
# parameter tells it to not use ppport.h when computing this.  Thus we get
# what the official perls added when.  Without this parameter, we do use
# ppport.h, so we get, as patched by ppport.h, what gets added when

GetOptions(\%opt, qw( base check! verbose install=s blead=s blead-version=s )) or die;

identify();

my $outdir = 'parts/todo';

my @perls = sort { $b->{version} <=> $a->{version} }
            map { { version => `$_ -e 'printf "%.6f", \$]'`, path => $_ } }
            ($opt{blead}, grep !/-RC\d+/, glob "$opt{install}/bin/perl5.*");

if (exists $opt{'blead-version'}) {
  $perls[0]{version} = $opt{'blead-version'};
}

# blead's todo is its version plus 1.  Otherwise, each todo is the previous
# one's version
$perls[0]{todo} = $perls[0]{version} + 1;
for (1 .. $#perls) {
  $perls[$_]{todo} = $perls[$_-1]{version};
}

for (@perls) {
  my $todo = do { my $v = $_->{todo}; $v =~ s/\D+//g; $v };
  -e "$outdir/$todo" and next;
  my @args = ('--perl', $_->{path}, '--version', "$_->{todo}");

  push @args, '--blead' if $_ == $perls[0]; # First one is blead
  push @args, '--todo', $_->{'todo'};
  push @args, '--base' if $opt{base};
  push @args, '--verbose' if $opt{verbose};
  push @args, '--nocheck' unless $opt{check};
  runperl('devel/mktodo.pl', @args) or die "error running mktodo.pl [$!] [$?]\n";
}