Build a Threaded or 64-bit Perl for IBM AIX

You will finish with a separate Perl build configured for IBM AIX, with a deliberate choice of compiler, thread support, shared libraries and 32-bit or 64-bit mode. Allow 30 to 60 minutes for configuration, compilation and tests, longer on an older host. The examples follow the local perlaix(1) from perl-doc 5.38.2-3.2ubuntu0.6. That documentation describes Perl 5 on AIX rather than a command called perlaix, so there is no executable to run on a Linux host.

This is a build workflow, not an upgrade of the Perl used by AIX system scripts. It installs into a parallel prefix and leaves the system Perl links alone. You need an AIX source tree, an ANSI C compiler, the required AIX development files, enough disk space, and a shell account that can write the chosen prefix. The build commands are ordinary user commands until the final installation step, if your prefix is protected.

1. Record the AIX and compiler levels

Start with read-only checks. They tell you which branch of the document applies and give you evidence to keep with the build log:

$ oslevel
$ lslpp -l | egrep "syscalls|libm"
$ cc -qversion
$ gcc --version

The exact compiler command depends on what is installed. The documented choices include IBM xlc, xlc_r, cc, cc_r and vac, plus GCC. The current upstream documentation also lists IBM Open XL C/C++ for AIX 7.2 and 7.3, including the ibm-clang and ibm-clang_r names. Use a compiler that exists on this host; do not copy a compiler name from another AIX installation.

For a build that will link modules needing thread support, use the re-entrant compiler variant where available, such as cc_r. That choice makes Perl thread-enabled; it does not by itself make the whole Perl build threaded.

2. Check the GDBM header trap

Before configuring, inspect the AIX Toolbox headers if that software is present:

$ ls -l /opt/freeware/include/gdbm/dbm.h /opt/freeware/include/gdbm/ndbm.h

Older AIX Toolbox lib gdbm releases below 1.8.3-5 can conflict with the AIX system headers. If you need GDBM support, the documented minimum is gdbm-devel-1.8.3-5 or newer. Treat a missing file as a result to investigate, not as permission to create a replacement header by hand.

This step is read-only. If the headers are supplied by a package, use the normal AIX package-management process to update that package before building. Do not remove libraries from a running system to make Configure pass.

3. Choose a parallel installation prefix

Do not replace the Perl selected by AIX system scripts while testing a new build. The documented examples use prefixes such as /usr/opt/perl5_32 and /usr/opt/perl5_64, which keep a new tree parallel to the IBM system Perl installation.

Installing below /usr/opt may require elevated privileges. Build and test as an ordinary user first, then arrange the final installation with the AIX administrator. Do not change links in /usr/bin just to make a test script find the new interpreter. Call the new interpreter by its full path until the application migration has been reviewed.

4. Configure a normal 32-bit Perl

From the top of the Perl source tree, first remove the old configuration summary, then run Configure with the re-entrant compiler and shared-library support:

$ rm config.sh
$ ./Configure \
    -d \
    -Dcc=cc_r \
    -Duseshrplib \
    -Dprefix=/usr/opt/perl5_32

-d accepts the defaults, -Dcc=cc_r selects the compiler, -Duseshrplib requests a shared Perl library, and -Dprefix controls the installation directory. If this is a fresh source tree, config.sh may not exist. In that case, confirm that the shell reports only that the file is absent, then run Configure; do not replace the command with a guessed option.

When Configure finishes, read its summary before compiling. The important checks are the selected compiler, the installation prefix, shared-library support and the absence of an unexpected cross-compilation or ABI choice.

5. Add Perl thread support when required

If extensions or the application require a threaded Perl, add -Dusethreads to the same 32-bit configuration:

$ rm config.sh
$ ./Configure \
    -d \
    -Dcc=cc_r \
    -Duseshrplib \
    -Dusethreads \
    -Dprefix=/usr/opt/perl5_32

Do not add this flag merely because you used cc_r. The compiler variant and the Perl thread setting solve related but different problems. Keep the two decisions visible in the build notes.

Now compile and run the test suite using the normal Perl source-tree workflow:

$ make
$ make test

The perlaix(1) document describes its successful AIX combinations as builds whose make test runs finish 100 percent OK. Treat a failing test as a stop point. Capture the first failure, AIX level, compiler level and Configure summary before changing flags. Do not install a build that has not passed the tests you require.

6. Configure a 64-bit build

For 64-bit Perl, set AIX's object mode in the shell and add -Duse64bitall. The threaded form is:

$ export OBJECT_MODE=64
$ rm config.sh
$ ./Configure \
    -d \
    -Dcc=cc_r \
    -Duseshrplib \
    -Dusethreads \
    -Duse64bitall \
    -Dprefix=/usr/opt/perl5_64

In a csh-style shell, the documented equivalent is setenv OBJECT_MODE 64. If you do not need threads, omit -Dusethreads, but retain OBJECT_MODE=64 and -Duse64bitall. If you use GCC for a 64-bit build, the document specifies -Dcc='gcc -maix64' instead of the cc_r setting.

Check that the selected prefix is not the same as a working 32-bit installation. Mixing files from the two ABIs creates confusing loader failures and is harder to undo than a failed build in a new directory.

7. Investigate a linker failure without guessing

If linking miniperl reports undefined symbols such as .aintl, .copysignl, .syscall or .setresuid, the documented recovery is to clean the build, remove the configuration summary, and configure with -Dusenm:

$ make realclean
$ rm config.sh
$ ./Configure -Dusenm -Dcc=cc_r -Duseshrplib -Dprefix=/usr/opt/perl5_32

-Dusenm makes Configure use AIX's nm tool when scanning library symbols. The document also advises against using Configure's -r option on AIX because it affects how nm is used. Do not add -Dusenm to every build pre-emptively; use it for the linker symptom it addresses.

8. Install and verify the separate tree

After the selected build passes its tests, install it into the prefix chosen earlier. The precise privilege requirement depends on ownership of that directory, so use the site's normal administrative procedure for the install step. Then invoke the new interpreter by its full path and verify its version:

$ /usr/opt/perl5_32/bin/perl -V:version -V:useithreads -V:useshrplib
$ /usr/opt/perl5_32/bin/perl -e 'print "AIX Perl smoke test\n"'

For the 64-bit example, substitute /usr/opt/perl5_64. The first command reports the compiled version and selected build features; the second checks that the installed interpreter starts. Expected version output depends on the source tree, so compare it with the release you intended to build rather than copying a fixed number from this guide.

There is no single undo command for an installed Perl tree. The safe rollback is to stop using its full path, restore the previous application path or wrapper, and remove the new prefix only after confirming that no process or script still depends on it. Do not delete a shared prefix during an active service window.