Read Perl 5.8.2's Change Notes Without Guessing at Compatibility

Perl 5.8.2 quietly changed hash randomisation and module binary compatibility in ways that can break a threaded 5.8.1 deployment. This guide turns that fact, and the rest of perl582delta(1), into a small, repeatable audit: identify the installed documentation, check the interpreter you will actually run, find the cases that need a rebuild, and turn the release notes into tests. The examples are read-only apart from an optional temporary demonstration file.

Allow about 20 minutes. You need a shell and the perl-doc package. This guide uses the locally installed perl582delta(1) as its primary source. On this machine that package is perl-doc 5.38.2-3.2ubuntu0.6, so the document describes a historical Perl release even though the host's interpreter is Perl 5.38.2.

1. Confirm which documentation and interpreter you have

First check the package and interpreter. These ordinary, read-only commands do not need sudo:

$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc perl-base
perl-doc 5.38.2-3.2ubuntu0.6
perl-base 5.38.2-3.2ubuntu0.6
$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2) built for x86_64-linux-gnu-thread-multi

Your version will differ. Do not read the 5.8.2 notes as proof that a current interpreter shares the same implementation or bugs; they are a migration record for the change from 5.8.1 to 5.8.2.

2. Read the release boundary locally

Render the complete manual in the terminal:

$ man -P cat perl582delta | col -b | less

Search within less for /Incompatible Changes, /Hash Randomisation, /Threading, and /Platform Specific Problems. If you only need a captured copy for review, write it into a disposable directory, never a source or deployment directory:

$ tmpdir=$(mktemp -d)
$ man -P cat perl582delta | col -b > "$tmpdir/perl582delta.txt"
$ sed -n '1,220p' "$tmpdir/perl582delta.txt"
$ rm -rf "$tmpdir"

The final command removes only the temporary directory named by mktemp; copy the file to a deliberately chosen review location if you need to keep the notes. The manual's scope is explicit: it compares 5.8.1 with 5.8.2. For an upgrade from 5.6.x, read the earlier perl58delta and perl581delta documents too.

3. Find the compatibility trap before starting an upgrade

The highest-risk item here is narrow but operationally significant. Threaded Perl 5.8.1 builds lost binary compatibility with 5.8.0 for modules that called certain re-entrant system calls. Perl 5.8.2 restored compatibility with 5.8.0, which necessarily broke compatibility with 5.8.1 for that affected case.

• Treat the upgrade as a rebuild event if your old runtime is a threaded Perl 5.8.1 loading compiled modules.
• Record the module list, install Perl 5.8.2 in the target environment, then recompile and reinstall those modules against that interpreter.
• Never copy old .so files into the new installation.

For a modern host, use the same principle even though the exact 5.8.1 boundary no longer applies. Check the interpreter and module ABI together:

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

Exact field formatting varies; the facts that matter are the Perl version, architecture and whether threads are enabled. If any of those change, plan to rebuild XS modules rather than assume an old binary is safe.

4. Test code that assumes a hash order

Perl hash key order is not an application interface. The 5.8.2 notes describe an amended hash-randomisation implementation that resisted algorithmic-complexity attacks while restoring source and binary compatibility with both 5.8.0 and 5.8.1 in the affected area.

The practical audit is a read-only search of application code and tests for output that serialises a hash and then compares it byte for byte:

$ rg -n 'keys\s*\(|values\s*\(|each\s*\(|Data::Dumper|sortkeys|hash' /path/to/project

Replace /path/to/project with a real checkout. Sort keys explicitly wherever order matters for output. With Data::Dumper, use its documented Sortkeys setting. When insertion order itself is the requirement, use a deliberately ordered data structure rather than relying on a normal hash.

5. Check the smaller fixes that affect your platform

The release notes also record fixes for memory leaks involving variables shared between threads, parser handling of syntax errors involving unrecognised filetest operators, and more complete interpreter initialisation when -DMULTIPLICITY is off. Treat these as regression-testing clues, not as promises that every program shows a visible change.

If you build or embed Perl, read the platform section before choosing a test matrix. The notes mention adjusted dynamic-linker flags for Solaris and OS X, fixes for OS/2 sockets and tmpfile, and workarounds for setreuid and related calls on OS X. A Linux host cannot validate those platform-specific fixes; run the test on the target platform with the target build configuration.

The updated module list includes Devel::PPPort, Digest::MD5, MIME::Base64, Time::HiRes, Unicode::Collate, Unicode::Normalize, UNIVERSAL and others. Use it as a prompt to compare your dependency lockfile and regression results, not as a reason to upgrade individual modules out of context.

6. Record evidence for the change review

Save the exact interpreter identity, the package versions, the release-note scope, and the application's test results. A compact evidence block needs no elevated privileges:

$ printf 'perl: '
$ perl -e 'printf "%vd\n", $^V'
perl: 5.38.2
$ perl -V:archname -V:useithreads
archname='x86_64-linux-gnu-thread-multi';
useithreads='define';
$ man -P cat perl582delta | col -b | sed -n '1,35p'