From 07b35b6fe060e658ccb06d46362abdef0e8c8f34 Mon Sep 17 00:00:00 2001
From: James E Keenan <jkeenan@cpan.org>
Date: Mon, 27 Feb 2017 12:24:25 -0500
Subject: [PATCH] When and how to use Devel::PatchPerl to repair older builds.

Following recommendation by Matthew Horsfall.
---
 pod/perlgit.pod                |  7 ++++++
 pod/perlhack.pod               | 49 ++++++++++++++++++++++++++++++++++++++++++
 t/porting/known_pod_issues.dat |  1 +
 3 files changed, 57 insertions(+)

diff --git a/pod/perlgit.pod b/pod/perlgit.pod
index 9d3edcc..12aace2 100644
--- a/pod/perlgit.pod
+++ b/pod/perlgit.pod
@@ -481,6 +481,13 @@ the "first commit where the bug is solved".
 C<git help bisect> has much more information on how you can tweak your
 binary searches.
 
+Following bisection you may wish to configure, build and test perl at
+commits identified by the bisection process.  Sometimes, particularly
+with older perls, C<make> may fail during this process.  In this case
+you may be able to patch the source code at the older commit point.  To
+do so, please follow the suggestions provided in
+L<perlhack/Building perl at older commits>.
+
 =head2 Topic branches and rewriting history
 
 Individual committers should create topic branches under
diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index c8c6b86..7572d83 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1041,6 +1041,55 @@ is broken (for example, the utf8 length cache on long utf8 strings).
 Add a test that will take a fraction of a second normally, and minutes
 otherwise, causing the test file to time out on failure.
 
+=head2 Building perl at older commits
+
+In the course of hacking on the Perl core distribution, you may have occasion
+to configure, build and test perl at an old commit.  Sometimes C<make> will
+fail during this process.  If that happens, you may be able to salvage the
+situation by using the Devel::PatchPerl library from CPAN (not included in the
+core) to bring the source code at that commit to a buildable state.
+
+Here's a real world example, taken from work done to resolve
+L<perl #72414|https://rt.perl.org/Ticket/Display.html?id=72414>.
+Use of F<Porting/bisect.pl> had identified commit
+C<ba77e4cc9d1ceebf472c9c5c18b2377ee47062e6> as the commit in which a bug was
+corrected.  To confirm, a P5P developer wanted to configure and build perl at
+commit C<ba77e4c^> (presumably "bad") and then at C<ba77e4c> (presumably
+"good").  Normal configuration and build was attempted:
+
+    $ sh ./Configure -des -Dusedevel
+    $ make test_prep
+
+C<make>, however, failed with output (excerpted) like this:
+
+    cc -fstack-protector -L/usr/local/lib -o miniperl \
+      gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \
+      mg.o reentr.o mro.o hv.o av.o run.o pp_hot.o sv.o \
+      pp.o scope.o pp_ctl.o pp_sys.o doop.o doio.o regexec.o \
+      utf8.o taint.o deb.o universal.o globals.o perlio.o \
+      perlapi.o numeric.o mathoms.o locale.o pp_pack.o pp_sort.o  \
+      miniperlmain.o opmini.o perlmini.o
+    pp.o: In function `Perl_pp_pow':
+    pp.c:(.text+0x2db9): undefined reference to `pow'
+    ...
+    collect2: error: ld returned 1 exit status
+    makefile:348: recipe for target 'miniperl' failed
+    make: *** [miniperl] Error 1
+
+Another P5P contributor recommended installation and use of Devel::PatchPerl
+for this situation, first to determine the version of perl at the commit in
+question, then to patch the source code at that point to facilitate a build.
+
+    $ perl -MDevel::PatchPerl -e \
+        'print Devel::PatchPerl->determine_version("/path/to/sourcecode"), "\n";'
+    5.11.1
+    $ perl -MDevel::PatchPerl -e \
+        'Devel::PatchPerl->patch_source("5.11.1", "/path/to/sourcecode");'
+
+Once the source was patched, C<./Configure> and C<make test_prep> were called
+and completed successfully, enabling confirmation of the findings in RT
+#72414.
+
 =head1 MORE READING FOR GUTS HACKERS
 
 To hack on the Perl guts, you'll need to read the following things:
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 44c13ff..ebe09a9 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -343,6 +343,7 @@ pod/perlgit.pod	? Should you be using F<...> or maybe L<...> instead of	1
 pod/perlgit.pod	Verbatim line length including indents exceeds 79 by	1
 pod/perlguts.pod	? Should you be using L<...> instead of	1
 pod/perlhack.pod	? Should you be using L<...> instead of	1
+pod/perlhack.pod	Verbatim line length including indents exceeds 79 by	2
 pod/perlhist.pod	Verbatim line length including indents exceeds 79 by	1
 pod/perlhpux.pod	Verbatim line length including indents exceeds 79 by	1
 pod/perlinterp.pod	? Should you be using L<...> instead of	1
-- 
2.7.4