Use perl589delta to Audit a Perl 5.8.9 Upgrade

You will turn the perl589delta manpage into a short compatibility audit for a Perl 5.8.8 to 5.8.9 upgrade. The checks cover version assumptions, changed runtime variables, directory-handle tests, and the C++ XS boundary. Allow 20 to 30 minutes for a small application, plus time to run its own test suite.

This is a historical release note, not a guide to the Perl installed on every current Linux system. The manpage installed here describes Perl 5.8.9, while the local interpreter is Perl 5.38.2. Use the local commands to check the shell and interpreter mechanics, but use the release boundary in the manpage when deciding what changed between 5.8.8 and 5.8.9.

1. Confirm the document and interpreter

Start by checking which documentation and executable you are actually using. This avoids comparing a system Perl with a copied manpage from a different installation.

$ command -v perl
/usr/bin/perl
$ perl -v | sed -n '1,4p'

This is perl 5, version 38, subversion 2 (v5.38.2)
$ PERLDOC_PAGER=cat perldoc -t perl589delta | sed -n '1,12p'
NAME
    perl589delta - what is new for perl v5.8.9

DESCRIPTION
    This document describes differences between the 5.8.8 release and the
    5.8.9 release.

On a machine without the perl-doc package, perldoc may not find this page. Install documentation through the normal package-management process only if that is permitted for the host. Do not treat a missing manpage as evidence that the interpreter is an old Perl.

2. Read the compatibility boundary first

The manpage says that no changes were intentionally incompatible with 5.8.8, apart from a C++ extension construction described later. That is a statement about intended compatibility, not a guarantee that application bugs or reliance on old bugs will behave the same way.

It also calls 5.8.9 the last significant 5.8.x release and recommends moving to 5.10.x. Treat that as migration planning information from the 5.8.9 release, not as current support advice. For a real upgrade, list the application, its CPAN modules, its XS modules, and its deployment Perl before changing anything.

$ perl -V:version -V:archname -V:useshrplib
version='5.38.2';
archname='x86_64-linux-gnu-thread-multi';
useshrplib='true';

The exact values will differ on an older host. Keep this output with the audit: architecture, threading and shared-library choices can matter to compiled extensions even when ordinary Perl code is unchanged.

3. Check version guards in application code

Perl 5.8.9 adds support for no VERSION, which requests a Perl older than the supplied version. Use it to test source that must avoid features introduced after a compatibility target, but do not confuse a successful parse with a complete application test.

$ perl -e 'no 5.10; print "version gate passed\n"'
version gate passed

The command above runs on the local 5.38.2 interpreter. Your migration test should run the real program under the target Perl as well. Search the project for version declarations, no VERSION, feature pragmata and modules with XS code:

$ rg -n 'use [0-9]|no [0-9]|XS|Makefile\.PL|Build\.PL' lib bin t Makefile.PL 2>/dev/null

A search result is a review queue, not a failure. Inspect each match in context. A version guard may be deliberate, while an old workaround may now hide the behaviour you need to test.

4. Exercise the new runtime status variable

The release notes add ${^CHILD_ERROR_NATIVE}. It preserves the native status from a successful system, pipe close, backtick command, wait or waitpid. It is different from the portable interpretation of $?, so log both when diagnosing a child-process failure.

$ perl -e 'system("sh", "-c", "exit 7"); print "status=$? native=${^CHILD_ERROR_NATIVE}\n"'
status=1792 native=1792

The numeric value is platform and child-status dependent. The useful check is that the command ran, the status is non-zero, and the native variable is populated. Never decide that a child succeeded merely because the system call itself returned.

Run this test as the same unprivileged account and with the same environment as the application. It does not require sudo, and it starts a short-lived shell without changing files or services.

5. Test directory-handle file tests

Perl 5.8.9 permits stat and the -X file tests on directory handles. The handle-versus-filehandle ambiguity described by the manpage still matters: use a lexical handle and make the intended object obvious.

$ perl -e 'open my $dh, "." or die $!; print((-d $dh ? "directory\n" : "not-directory\n")); print((-X $dh ? "executable\n" : "not-executable\n")); closedir $dh'
directory
executable

-X here asks whether the opened directory is executable according to the current account and filesystem permissions. It is not a test that a child process can perform every operation inside that directory. Use a temporary test directory if your application depends on a particular permission layout; do not alter a production directory just to make this probe pass.

6. Review Unicode and XS changes

The manpage records a Unicode Character Database update from 4.1.0 to 5.1.0 and a rewritten UTF-8 offset cache. If your application compares character classes, transliteration mappings or character offsets, add representative non-ASCII cases to its test suite. The release notes also expose ${^UTF8CACHE}: it is normally 1, can be set to 0 to disable the cache, and -1 enables diagnostic checking.

$ perl -we '${^UTF8CACHE}=0; print "utf8cache=${^UTF8CACHE}\n"'
utf8cache=0

This is a diagnostic switch, not a general performance setting. Do not leave it changed in a service without recording why. Compare test results with the default and with caching disabled, then restore the normal process environment by starting a new process.

For C++ XS code, search for the old typedef form typedef XS(...). The documented adjustment is to use typedef XSPROTO(...) where that construction is required. C extensions and already compiled extensions are not automatically proof against every ABI or toolchain issue, so rebuild and test every extension during the upgrade. This is build work, normally done in a controlled build environment, not a reason to edit a live installation as root.

7. Finish with a migration decision

Run the application's tests under both the old and new interpreters where possible. Include Unicode cases, child-process handling, module loading, directory permissions and every XS dependency. Keep the old runtime and deployment artefacts until the new process has passed its acceptance checks. If the upgrade changes a service unit, wrapper or symlink, prepare the previous version as the rollback target and change one deployment boundary at a time.

Do not use the presence of new features as a reason to rewrite working code. The useful outcome of perl589delta is a short list of behaviours your application actually depends on, with tests that show whether the target runtime preserves them.