Use perl561delta to Audit an Old Perl Upgrade

You will finish with a small, repeatable audit for Perl code moving from the 5.005 or 5.6.0 era to 5.6.1 and later. The guide uses the installed perl561delta documentation, which describes the historical change from Perl 5.005 to 5.6.1. It does not claim that every note still describes modern Perl.

Allow 15 to 20 minutes for the document review, plus however long your test suite needs. You need a shell, the perl-doc package and a copy of the application or module you are reviewing. The commands below are 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 document title and its opening description tell you what it covers: differences between 5.005 and 5.6.1. Do not use the host interpreter 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. The page says that suidperl stopped running /bin/mail because some platforms supplied a vulnerable implementation, and it strongly discourages using suidperl. Treat any old deployment that depends on set-user-ID Perl as a security review, not a routine interpreter upgrade. Prefer a deliberately configured privilege boundary such as sudo, with its policy reviewed by an administrator.

This is a warning, not a request to enable or remove anything. Do not run a set-user-ID interpreter, send mail, or change ownership while following this guide. If the application uses that path, preserve the old environment in an isolated test system and obtain a replacement design before production work.

3. Search for changes that can alter program results

Use the page's headings to make a short impact list. A convenient read-only filter is:

$ 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

The exact surrounding output can vary with formatter and terminal, so use the full page when a heading looks relevant. These entries deserve concrete tests:

• sort changed comparison and argument context, and sorting became reentrant. A comparator that relies on implicit globals, wantarray or nested sorting should have a focused test.
• Globbing moved to the File::Glob implementation, and File::Glob::glob was renamed to bsd_glob; the old name remains for compatibility but is deprecated. Test ordering, quoting and empty matches rather than assuming a directory listing order.
• Unicode support 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 with non-ASCII data.
• The random-number and hash algorithms changed. Tests or protocols that compare a particular rand sequence, or code that accidentally relies on hash iteration order, are not stable compatibility tests.

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. The page also records incompatibilities: 64-bit bit operators can behave differently at native width, some diagnostic text changed, and the old $$1 interpolation meaning is no longer supported.

For XS modules, read 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 corresponding 5.005 builds. Public API assumptions, export lists and build flags still need testing on the target platform.

Do not turn an experimental feature on just because the page mentions it. Threads, Unicode, 64-bit support, lvalue subroutines, weak references and pseudo-hashes are 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 changing production. Add narrow regression tests for each item in your impact list. For example, 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 identity with 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 because the document specifically calls out platform width and thread configuration. A passing test on a non-threaded 32-bit build does not clear a threaded 64-bit deployment.