Doc: update testing recipe in src/test/perl/README.

The previous text didn't provide any clear explanation of our policy
around TAP test portability.  The recipe for using perlbrew had some
problems, too: it resulted in a non-shared libperl (preventing
testing of plperl) and it caused some modules to be updated to
current when the point of the recipe is to build an old environment.

Discussion: https://postgr.es/m/[email protected]

diff --git a/src/test/perl/README b/src/test/perl/README
index bfc7cdcfa3095750a75985cea38d5d13912eddb0..67a050b9d48aaf3428485b4ef5a1a423bd8f7260 100644 (file)
--- a/src/test/perl/README
+++ b/src/test/perl/README
@@ -70,20 +70,36 @@ perldoc for the test modules, e.g.:
 
     perldoc src/test/perl/PostgresNode.pm
 
-Required Perl
--------------
+Portability
+-----------
+
+Avoid using any bleeding-edge Perl features.  We have buildfarm animals
+running Perl versions as old as 5.8.3, so your tests will be expected
+to pass on that.
 
-Tests must run on perl 5.8.3 and newer. perlbrew is a good way to obtain such
-a Perl; see http://perlbrew.pl .
+Also, do not use any non-core Perl modules except IPC::Run.  Or, if you
+must do so for a particular test, arrange to skip the test when the needed
+module isn't present.  If unsure, you can consult Module::CoreList to find
+out whether a given module is part of the Perl core, and which module
+versions shipped with which Perl releases.
 
-Just install and
+One way to test for compatibility with old Perl versions is to use
+perlbrew; see http://perlbrew.pl .  After installing that, do
 
+    export PERLBREW_CONFIGURE_FLAGS='-de -Duseshrplib'
     perlbrew --force install 5.8.3
     perlbrew use 5.8.3
     perlbrew install-cpanm
-    cpanm install IPC::Run
+    cpanm install Test::[email protected]_01
+    cpanm install IPC::[email protected]
+    cpanm install ExtUtils::[email protected]  # downgrade
 
-then re-run configure to ensure the correct Perl is used when running
-tests. To verify that the right Perl was found:
+Then re-run Postgres' configure to ensure the correct Perl is used when
+running tests.  To verify that the right Perl was found:
 
     grep ^PERL= config.log
+
+Due to limitations of cpanm, this recipe doesn't exactly duplicate the
+module list of older buildfarm animals.  The discrepancies should seldom
+matter, but if you want to be sure, bypass cpanm and instead manually
+install the desired versions of Test::Simple and IPC::Run.