Use perl561delta to Audit an Old Perl Upgrade

Moving Perl code from the 5.005 or 5.6.0 era to 5.6.1 or later is not a recompile, it is an audit. This guide turns the installed perl561delta documentation into a short, repeatable checklist for that move. The document describes the historical change from Perl 5.005 to 5.6.1; it does not claim every note still describes modern Perl.

Allow 15 to 20 minutes for the document review, plus whatever your test suite needs. You need a shell, the perl-doc package, and a copy of the application or module you are reviewing. Every command below is read-only unless you deliberately run your own tests.

1. Confirm which documentation you are reading

Start with the installed interpreter and package. This matters because the document is about Perl 5.6.1, while the copy installed on this machine is Perl 5.38.2:

$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2) built for x86_64-linux-gnu-thread-multi

$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6

$ perldoc -l perl561delta
/usr/share/perl/5.38/pod/perl561delta.pod

The package version tells you which copy of the reference is installed. The title and opening description tell you what it covers: the differences between 5.005 and 5.6.1. Do not treat the host interpreter's version as evidence that an old application has already been tested against it.

2. Read the high-risk notes first

Open the page in a terminal:

$ perldoc perl561delta

Read the security section before the feature list. It says that suidperl stopped running /bin/mail because some platforms shipped a vulnerable implementation, and it strongly discourages using suidperl at all.

3. Search for changes that can alter program results

Use the page's own headings to build a short impact list. This read-only filter is a convenient starting point:

$ perldoc -T perl561delta | grep -E -i 'sort|glob|unicode|utf-8|random|hash|open\(\)|64-bit|weak references|taint'
Enhanced support for sort() subroutines
File globbing implemented internally
Unicode and UTF-8 support
Better pseudo-random number generator
Better worst-case behavior of hashes

Output varies with formatter and terminal, so check the full page when a heading looks relevant. These entries deserve a concrete test:

• sort changed comparison and argument context, and sorting became reentrant. Give a comparator that relies on implicit globals, wantarray or nested sorting a focused test.
• Globbing moved to File::Glob, and File::Glob::glob was renamed to bsd_glob; the old name still works but is deprecated. Test ordering, quoting and empty matches, do not assume a directory listing order.
• Unicode uses UTF-8 internally for character strings, with the utf8 and bytes pragmas controlling the lexical scope. Test byte lengths, character lengths, regular expressions and file boundaries against non-ASCII data.
• Random numbers and hash algorithms changed. A test that compares a particular rand sequence, or code that accidentally relies on hash iteration order, is not a stable compatibility test.

4. Check source and interface assumptions

For application code, look for the documented language changes rather than trying to reproduce every historical bug. Perl 5.6 introduced three-argument open, lexical filehandles, dotted version syntax, weak references, lvalue subroutines and experimental threading or 64-bit support. It also records incompatibilities: 64-bit bit operators can behave differently at native width, some diagnostic text changed, and the old $$1 interpolation meaning is gone.

For XS modules, treat the C source and binary compatibility sections as a separate work item. The default build is generally described as binary compatible with 5.005 maintenance releases, but threaded or multiplicity builds are not compatible with the corresponding 5.005 builds. Public API assumptions, export lists and build flags still need testing on the target platform.

Do not switch on an experimental feature just because the page mentions it. Threads, Unicode, 64-bit support, lvalue subroutines, weak references and pseudo-hashes are all explicitly marked experimental in the historical document. Decide whether the application actually uses one, then test that feature on the exact interpreter and platform you plan to deploy.

5. Turn the notes into safe tests

Run the application's existing tests under the candidate interpreter before touching production. Add narrow regression tests for each item on your impact list: compare sorted results after explicitly defining the comparator, assert text and byte behaviour separately, and replace hash-order assertions with set comparisons.

Capture the interpreter's identity alongside the test result:

$ perl -V:version -V:archname -V:use64bitint -V:useithreads
version='5.38.2';
archname='x86_64-linux-gnu-thread-multi';
use64bitint='define';
useithreads='define';

Your values may differ; keep this output with the test log, since the document specifically calls out platform width and thread configuration. A pass on a non-threaded 32-bit build does not clear a threaded 64-bit deployment.