Audit Legacy Perl Code with perl5101delta

You will turn the Perl 5.10.1 release notes into a focused compatibility check: identify code whose meaning changed after Perl 5.10.0, exercise the risky paths, and record which newer facilities are safe to adopt. Allow about 30 minutes for a small script and longer for a module with tests.

Before you start

This guide is for code moving from Perl 5.10.0 to 5.10.1, or for an older codebase whose original target matters. The installed manpage is historical: this machine has the perl-doc package at 5.38.2-3.2ubuntu0.6 and Perl reports v5.38.2. That modern interpreter is useful for syntax checks and smoke tests, but it is not evidence that every 5.10.1 detail still behaves identically. Run the real application under the Perl versions you support.

Start in a disposable checkout. The commands below read files and run small programs; they do not need elevated privileges. Do not test an upgrade by replacing the system Perl or by running an unfamiliar script as root.

1. Confirm the baseline and read the right delta

Record the interpreter and the release-note scope before changing code. perl5101delta covers 5.10.0 to 5.10.1 only. If the project is coming from 5.8.x, the manpage says to read perl5100delta first.

perl -V:version -V:archname
man perl5101delta | col -b | sed -n '1,90p'

Expected output includes a version='5.38.2'-style line on this host and the heading "perl5101delta - what is new for perl v5.10.1". Checkpoint: if the application still runs on 5.10.0, keep that interpreter available for comparison rather than guessing from a newer one.

2. Search for the semantic changes

The highest-risk section is the change to ~~. In 5.10.1, smart match is no longer commutative: the type of the right-hand operand drives dispatch. The notes specifically call out array distribution, hash and array callbacks, undef against a hash, code references and objects without a ~~ overload.

rg -n --glob '*.pl' --glob '*.pm' \
  '~~|\b(given|when)\b|use feature\s+.*5\.10|qr/.*/m' path/to/project

For each hit, write a small test for the intended result instead of relying on a visual code review. These cases make the changed array and undefined-value rules explicit:

use strict;
use warnings;

my @values = (1, 2, 3);
print 2 ~~ @values ? "match\n" : "no match\n";

my %keys = ('' => 1);
print undef ~~ %keys ? "undef match\n" : "undef no match\n";

On the installed Perl, the output is match followed by undef no match, with deprecation warnings for smart match. That warning is a modern-version signal, not a failure of the 5.10.1 example. A production fix should normally replace a deliberately tested smart match with a clearer comparison, but do that only after the test captures the required behaviour.

3. Inspect given and when boundaries

The release notes add two special cases to when. Flip-flop expressions such as /^=begin/ .. /^=end/ are evaluated as booleans, which makes a bistable range useful. A defined-or expression such as expr1 // expr2 can also be treated as boolean when its first expression is boolean.

Do not use when (1..10) as an integer membership test. The documented form is when ([1..10]), using an array reference. Put that case in the compatibility test suite if the project uses the switch feature. The exact switch syntax and feature availability vary on later Perl releases, so compile and run it under the oldest supported interpreter as well as the modern one.

perl -c path/to/legacy-script.pl
prove -lr t

Checkpoint: a clean compile is not enough. A changed dispatch rule can produce a plausible but wrong result, so include assertions around every given/when branch found in step 2.

4. Check feature bundles and regular expressions

The meaning of use feature ':5.10' and use feature ':5.10.X' changed slightly: in 5.10.1 the final component is ignored, so the two bundles have the same effect. Treat the bundle as a version contract, not as a way to request an exact patch release. Prefer naming the individual features when the code needs a stable, reviewable set.

Also look for a regular expression compiled with qr, then used with /m. The manpage records a behaviour change between 5.8.x and 5.10.0: a pattern such as qr/^bar/ embedded in a multiline match no longer matched the second line in the old way. This is not a new 5.10.1 regression, but it is easy to misattribute during an upgrade.

perl -c path/to/module.pm
prove -v t/regex.t

Keep a test for line anchoring, Unicode input and any generated pattern. Avoid "fixing" a failing test until you know which Perl version defined the intended result.

5. Use the new facilities deliberately

Perl 5.10.1 adds autodie as a lexically scoped alternative to Fatal, and adds parent for establishing an ISA relationship at compile time. It also adds the overloading pragma for lexical control of overloading. These are adoption options, not reasons to rewrite a stable service during a version change.

use strict;
use warnings;
use autodie;

open my $fh, '<', '/path/to/input.txt';
my $line = <$fh>;

Run this only against a known input path. autodie changes failure handling, so review callers that currently inspect return values. The 5.10.1 notes also warn that string eval can let its behaviour leak outside the intended scope. Keep such code out of a first migration, or add a test that proves the boundary.

For inheritance, use parent 'Base::Class'; expresses the relationship without the extra behaviour of base. Confirm that the base module is available in the target installation before deploying. No package installation or system-wide change is required for this audit.

6. Test the build and known failure modes

If you build Perl or distribute XS modules, include the operational notes in the test plan. The release supports parallel core tests on Unix-like systems with TEST_JOBS and make test_harness, but the manpage names tests that may fail in parallel and should be rerun sequentially. It also records removed distribution modules, including Test::Harness::Straps and two ExtUtils::MakeMaker helper modules.

TEST_JOBS=3 make test_harness
make test

The second command is the recovery path for a parallel-only failure, not a guarantee that the code is correct. For a module release, check the generated metadata and ensure configure_requires prerequisites are installed before Makefile.PL or Build.PL runs.

Do not treat every listed fix as a new feature to verify manually. The delta includes Unicode Character Database 5.1.0, many module updates, interpreter crash fixes and diagnostics. Prioritise entries that touch your code: smart match, switch syntax, feature bundles, regular expressions, inheritance, error handling and build tooling.