Use perl5005delta to Plan a Safe Legacy Perl Upgrade

You will use perl5005delta as a compatibility checklist when maintaining an old Perl application or extension. The page compares Perl 5.004 with Perl 5.005, so it is historical documentation rather than a command that changes an interpreter. Allow about 15 minutes for the first pass, plus time to test the application itself.

You need a shell, the perl-doc package, and a copy of the application or module you are reviewing. The examples below were checked on Ubuntu with Perl 5.38.2 and perl-doc package version 5.38.2-3.2ubuntu0.6. The manual's subject is still Perl 5.005, even though the installed reader is newer.

1. Confirm which documentation is installed

Start by checking the interpreter and the manual's source path. This avoids reviewing a copied document from a different Perl installation:

$ 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 perl5005delta
/usr/share/perl/5.38/pod/perl5005delta.pod

perldoc -l reports the installed POD file. If it reports that the page cannot be found, install the distribution's documentation package through your normal package-management process. Do not treat a missing manual as evidence that the Perl runtime lacks a feature.

Checkpoint: the version shown by perl -v may be far newer than 5.005. Record both versions in an upgrade note. The first is the interpreter you are running; the second is the release described by this document.

2. Read the delta without changing the system

Use either the terminal manual or plain-text perldoc. Both are read-only operations:

$ man perl5005delta
$ perldoc -T perl5005delta | sed -n '1,24p'
NAME
    perl5005delta - what's new for perl5.005

DESCRIPTION
    This document describes differences between the 5.004 release and this
    one.

The document is organised by risk and feature area. Read Incompatible Changes before the longer list of new features. Its central warning is that Perl 5.005 is not binary compatible with Perl 5.004. Dynamically loaded extensions built for 5.003 or 5.004 must be rebuilt and reinstalled for 5.005.

This is the first decision point: if your application is pure Perl, continue to the source-compatibility checks. If it loads XS modules or other compiled extensions, plan a rebuild in the target Perl environment before you spend time chasing script-level differences.

3. Check compiled extensions and threading

Search the project for signs that it builds or loads native code. These checks do not execute project code:

$ find /path/to/project -type f \( -name 'Makefile.PL' -o -name 'Build.PL' -o -name '*.xs' \) -print
$ rg -n 'XSLoader|DynaLoader|use threads|use Thread' /path/to/project

The manual describes two separate compatibility boundaries. Every binary extension must be rebuilt for 5.005, and a threaded build is incompatible with a non-threaded build. A shared object compiled for one Perl configuration is not made safe by copying it into another library directory.

If an XS build fails with an undeclared thr variable while targeting a threaded Perl, the historical guidance points to the dTHR; macro at the beginning of the affected block. Treat that as a source-review clue, not as a universal repair. First confirm the Perl headers and build configuration being used, then make the smallest source change and rerun the module's tests.

For older XS code, also look for unqualified Perl globals such as sv_undef or na. The documented 5.005 direction is to use names such as PL_sv_undef and PL_na, and to use the Perl_ prefix for API functions where appropriate. These changes belong in the extension source, not in a shell environment variable.

4. Check pure-Perl compatibility traps

Without experimental features, the manual expects few visible source changes, but it calls out new keywords and reserved words. Review code that defines or calls a subroutine named our, and code that relies on the meaning of lock, INIT, or qr//. A warning produced with -w can be useful evidence during this review:

$ perl -we 'my $re = qr/foo/; print $re, "\n";'
(?^:foo)
$ perl -we 'my $x = "hello"; my $old = substr($x, 1, 2, "i"); print "$old:$x\n";'
el:hilo

These smoke tests demonstrate syntax supported by the current interpreter. They do not prove that an old application is compatible, and they do not recreate the exact 5.005 runtime. Use the project's own test suite for that. The delta also documents changes to regular expressions, tied data structures, substr, splice, record-oriented input, and locale handling, so give those areas targeted tests if the application uses them.

5. Treat taint and experimental features as boundaries

The 5.005 notes say that taint leaks and omissions were corrected, which can make an older script fail. That is a security-relevant compatibility change: do not restore the old behaviour by compiling with -DINCOMPLETE_TAINTS. The manual explicitly says that this produces a Perl with known insecurities.

Threads, the compiler tools, exception references, reliable signals, and 64-bit support are described as experimental in this release. Do not infer production support from their presence in the page. If the application depends on one, test it in an isolated copy of the target environment and keep the existing interpreter available until the test result is understood.

6. Run the application test gate

Make a backup or use version control before rebuilding modules. Rebuilding can replace compiled artefacts, and a package or build script may remove files that the old runtime still needs. This is the only state-changing part of the workflow, so follow the project's documented build command and keep the old environment separate.

After the rebuild, run the project's tests with the exact interpreter selected for deployment. Capture the interpreter, architecture, threading mode, module versions, and test result. If a failure appears, classify it against the manual: binary loading, XS compilation, threading, taint behaviour, a language construct, or an unrelated application defect.

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

Do not copy this architecture result into a configuration file. It is a diagnostic record. The useful comparison is between the interpreter running the tests and the interpreter that will run the service.