Add the Right OpenSSL ABI Dependency to a Perl XS Package

You will finish with a Debian package build that adds the matching perl-openssl-abi-* dependency to a Perl XS package which exposes OpenSSL binary objects. This is for package maintainers, not for installing an ordinary Perl module.

Allow about twenty minutes if the package already has a debhelper layout. You need a Debian source tree, a working debhelper build environment, and the installed perl-openssl-defaults package. The examples below use version 7build3 on this Ubuntu system. The installed dh_perl_openssl is dated 8 April 2024 in its manual, but its executable cannot run here because the optional debhelper Perl module is not installed. The examples therefore show the package-maintainer configuration and use the ABI helper for a local check.

1. Confirm that the package needs this dependency

Use dh_perl_openssl only when the Perl code exposes OpenSSL binary-interface objects, such as pointers to SSL_CTX structures. The concern is compatibility between XS modules built against different OpenSSL versions. A pure-Perl module, or an XS module that does not expose OpenSSL objects across its Perl interface, does not gain anything from adding this dependency.

Check the installed provider before editing the source package. This is read-only and needs no elevated privileges:

$ dpkg-query -W -f='${Package} ${Version} ${Architecture}\n' perl-openssl-defaults
perl-openssl-defaults 7build3 amd64
$ command -v dh_perl_openssl
/usr/bin/dh_perl_openssl

Checkpoint: the package name and executable should be present. The ABI helper reads the libssl.so SONAME and produces the ABI suffix that the maintainer tool turns into a package dependency.

2. Add the sequence to debian/control

The current debhelper route is the smallest configuration. Add the sequence package to Build-Depends, and make sure the binary package's Depends field contains ${perl:Depends}:

Source: example-perl-module
Section: perl
Priority: optional
Build-Depends: debhelper-compat (= 13),
 dh-sequence-perl-openssl,
 libssl-dev,
 perl

Package: example-perl-module
Architecture: any
Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}
Description: Example Perl module with an OpenSSL XS interface
 Example package description.

dh-sequence-perl-openssl is provided by perl-openssl-defaults on this machine. Keep it in Build-Depends, because it controls the package build sequence; do not put it in the installed binary package's runtime Depends. The ${perl:Depends} substitution is the destination for the dependency generated during the build.

Checkpoint: inspect the effective fields before building:

$ grep -E '^(Build-Depends|Depends):' debian/control
Build-Depends: debhelper-compat (= 13), dh-sequence-perl-openssl, libssl-dev, perl
Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}

3. Keep debian/rules simple

With the sequence package selected, the standard debhelper entry point is enough:

#!/usr/bin/make -f
%:
	dh $@

Make the file executable, then check it without changing the package contents:

$ chmod +x debian/rules
$ test -x debian/rules && echo 'debian/rules is executable'
debian/rules is executable

Do not add both dh-sequence-perl-openssl and --with perl_openssl unless you have a specific reason to manage the sequence manually. The two forms select the same addon and can make a later build harder to understand.

4. Use the explicit addon only for an older layout

If the source package cannot use the sequence package, select the addon in debian/rules instead:

#!/usr/bin/make -f
%:
	dh $@ --with perl_openssl

The addon inserts dh_perl_openssl after dh_perl. That ordering matters because both tools contribute to the ${perl:Depends} substitution. Do not use this form as well as the sequence package in the same build.

For a package using old-style debhelper commands rather than dh, run dh_perl_openssl after dh_perl. This is a maintenance choice for an existing package, not a reason to turn a modern dh build into a hand-written sequence.

5. Check the ABI value before a full build

The helper used by the installed maintainer tool is safe to run directly. It reads metadata from the development linker name and does not alter the source tree:

$ /usr/share/perl-openssl-defaults/get-libssl-abi
3

The exact value follows the installed OpenSSL development files and can change when the build environment changes. Do not hard-code perl-openssl-abi-3 in package metadata when the generated dependency is the purpose of this tool.

A missing libssl.so, the target architecture's objdump, or the ability to read the file makes this check fail. Fix the build dependencies or build environment first. Do not run the package build as root to hide a missing tool.

6. Build and inspect the result

Build the source package using your normal unprivileged packaging command:

$ dpkg-buildpackage -us -uc
$ dpkg-deb -f ../example-perl-module_*.deb Depends
libc6 (>= 2.34), perl (...), perl-openssl-abi-3, ...

Names, versions and other dependencies vary by package. The important check is that the binary package's Depends field contains the ABI package generated for the build host. Inspect the actual package rather than trusting a successful exit status alone.

On this machine, invoking dh_perl_openssl directly without debhelper installed fails while loading Debian::Debhelper::Dh_Lib. That is an environment problem, not a missing OpenSSL ABI. Install the declared build dependencies in the isolated build environment, then rerun the package build there. No elevated privilege is needed for the command itself.

7. Recover from a wrong or unwanted change

This workflow changes only packaging metadata generated in the build tree. To undo an uncommitted source edit, restore the affected debian/control or debian/rules change using your normal version-control workflow. Do not delete a built package you still need; remove an obsolete artefact only after checking its exact path and confirming that it is not the package you are testing.

If the generated dependency is absent, check these three boundaries in order: the addon or sequence is selected, ${perl:Depends} is present in the binary package stanza, and the ABI helper can read the target architecture's OpenSSL SONAME. Changing the runtime dependency by hand can conceal a repeatable build configuration error.