tweak, and heavily add comments to the Extutils::ParseXS code

MANIFEST

@@ -4157,6 +4157,7 @@ dist/ExtUtils-CBuilder/t/01-basic.t					tests for ExtUtils::CBuilder
 dist/ExtUtils-CBuilder/t/02-link.t					tests for ExtUtils::CBuilder
 dist/ExtUtils-CBuilder/t/03-cplusplus.t					tests for ExtUtils::CBuilder
 dist/ExtUtils-CBuilder/t/04-base.t					tests for ExtUtils::CBuilder
+dist/ExtUtils-ParseXS/author/mksnapshot.pl			Utility for detecting before/after changes to xsubpp output
 dist/ExtUtils-ParseXS/Changes					ExtUtils::ParseXS change log
 dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm			converts Perl XS code into C code
 dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pod			ExtUtils::ParseXS documentation
@@ -5210,12 +5211,12 @@ ext/XS-APItest/t/xsub_h.t			Tests for XSUB.h
 ext/XS-APItest/typemap
 ext/XS-APItest/XSUB-redefined-macros.xs		XS code needing redefined macros.
 ext/XS-APItest/XSUB-undef-XS_VERSION.xs		XS code needing #undef XS_VERSION
-ext/XS-Typemap/Makefile.PL		XS::Typemap extension
-ext/XS-Typemap/README			XS::Typemap extension
-ext/XS-Typemap/stdio.c			XS::Typemap extension
+ext/XS-Typemap/Makefile.PL		non-installed XS::Typemap extension
+ext/XS-Typemap/README			non-installed XS::Typemap extension
+ext/XS-Typemap/stdio.c			non-installed XS::Typemap extension
 ext/XS-Typemap/t/Typemap.t		test that typemaps work
-ext/XS-Typemap/Typemap.pm		XS::Typemap extension
-ext/XS-Typemap/Typemap.xs		XS::Typemap extension
+ext/XS-Typemap/Typemap.pm		non-installed XS::Typemap extension
+ext/XS-Typemap/Typemap.xs		non-installed XS::Typemap extension
 h2pl/cbreak.pl				cbreak routines using .ph
 h2pl/cbreak2.pl				cbreak routines using .pl
 h2pl/eg/sizeof.ph			Sample sizeof array initialization

Porting/exec-bit.txt

@@ -20,6 +20,7 @@ dist/Devel-PPPort/devel/regenerate
 dist/Devel-PPPort/devel/scanprov
 dist/Devel-PPPort/devel/update_release_date.pl
 dist/Devel-PPPort/soak
+dist/ExtUtils-ParseXS/author/mksnapshot.pl
 dist/Thread-Queue/examples/callback.pl
 dist/Thread-Queue/examples/queue.pl
 installperl

dist/ExtUtils-ParseXS/author/mksnapshot.pl

@@ -0,0 +1,69 @@
+#!/usr/bin/perl
+#
+# mksnapshot.pl
+#
+# This is a very crude script to help check whether and/or what has
+# changed in generated .c files as a result of changes to xsubpp and its
+# modules.
+#
+# It finds all .xs files under the current directory, then copies to
+# another directory, each associated .c file if it exists.
+#
+# The idea is that, while cd'ed to the base of the perl distribution, you
+# run this script, which will copy all the generated .c files to one
+# directory. You then rebuild perl with the newly modified xsubpp, and
+# create a second snapshot to another directory, then compare the results.
+#
+# For example,
+#
+#    ... build perl...
+#
+#    $ mkdir /tmp/snap1 /tmp/snap2
+#    $ dist/ExtUtils-ParseXS/author/mksnapshot.pl /tmp/snap1
+#    $ git clean -xdf
+#
+#    ... modify xsubpp ...
+#    ... build perl...
+#
+#    $ dist/ExtUtils-ParseXS/author/mksnapshot.pl /tmp/snap2
+#    $ diff -ru /tmp/snap[12]
+#
+# Each snapped .c file is saved with each '/' component of its pathname
+# changed to a '='. So ext/POSIX/POSIX.c would be copied to
+#    /tmp/snap1/ext=POSIX=POSIX.c
+
+use warnings;
+use strict;
+
+use File::Find;
+use File::Copy;
+
+die "usage: $0 snapdirectory\n" unless @ARGV == 1;
+my $snapdir = shift @ARGV;
+
+die "No such directory: $snapdir\n" unless -d $snapdir;
+
+find(
+    {
+        wanted   => \&wanted,
+        no_chdir => 1,
+    },
+
+    '.'
+);
+
+
+
+sub wanted {
+    return unless /\.xs$/;
+    my $f = $_;
+    $f =~ s/\.xs$/.c/ or die;
+    return unless -f $f;
+    my $df = $f;
+    $df =~ s{^/}{};
+    $df =~ s{^\./}{};
+    $df =~ s{/}{=}g;
+    $df = "$snapdir/$df";
+    print "snapping $f\n";
+    copy($f, $df) or die "Can't copy $f to $df: $!\n";
+}