Build a Separate Perl on macOS Without Replacing Apple's Perl

You will build Perl 5.38.2 from source in /usr/local, run its test suite, and install it without overwriting the Perl supplied by macOS. Allow 30 to 60 minutes, depending on the machine and whether Apple's developer tools are already installed. This is a historical, version-specific workflow: the installed perlmacosx manual is for Perl 5.38.2 and was last modified in 2013, so check your current upstream documentation before applying it to a newer release.

You need a Mac with a shell, a working network connection, and Apple's make from Xcode or the separate Command Line Tools bundle. The commands below build as an ordinary user. Only the final installation command uses sudo.

1. Check the tools before downloading source

Confirm that the developer tools and the basic build commands exist. These checks do not change the system:

$ command -v make
$ command -v curl
$ command -v tar
$ make --version

The manual says that make is supplied by Apple's developer tools. On macOS 10.7 and later it was also available in the separately downloadable Command Line Tools bundle. If make is missing, install that bundle through Apple's supported method, then repeat this check. Do not work around a missing compiler by using sudo.

2. Download and unpack the exact source archive

Create a temporary working directory in your home directory, then download the release named by this manual:

$ mkdir -p "$HOME/src"
$ cd "$HOME/src"
$ curl -O https://www.cpan.org/src/perl-5.38.2.tar.gz
$ tar -xzf perl-5.38.2.tar.gz
$ cd perl-5.38.2

The archive name and directory should both contain 5.38.2. If you downloaded a different release, do not silently use the options in this guide: read that release's INSTALL file and platform documentation first. Keep the archive and source directory until the installation has been checked.

This step does not replace any existing Perl. It only creates files below the working directory.

3. Configure an isolated installation prefix

Configure the build with the manual's recommended traditional Unix prefix:

$ ./Configure -des -Dprefix=/usr/local/
$ printf 'configure status: %s\n' "$?"

-des selects the documented non-interactive configuration path. The prefix keeps the new interpreter and its modules under /usr/local, leaving Apple's paths such as /usr/bin/perl and /System/Library/Perl alone. Read the configuration summary before continuing. If it reports an unexpected compiler, SDK or library path, stop and correct the environment rather than hoping the test suite will catch every mismatch.

4. Build and test before using elevated privileges

Compile the source as your normal user, then run the tests:

$ make
$ make test
$ printf 'test status: %s\n' "$?"

Do not treat a successful compile as sufficient. The manual specifically places make test before installation, and its platform notes describe known failures on very old macOS releases, including incomplete threading support on 10.2 and older and historical DB_File issues. Record the failing tests and compare them with the release documentation. If failures involve an unexpected external library, return to configuration rather than installing a suspect build.

Extra libraries can confuse configuration. The manual gives -Uloclibpth -Dlibpth=/usr/lib as a way to restrict library discovery to system libraries, while allowing an explicitly chosen list such as /usr/lib /opt/lib. Use those overrides only when the diagnostic points to library selection. They are not a general repair command.

5. Install into /usr/local

Installing below /usr/local changes system state and may replace files from an earlier manual installation. Before proceeding, check the destination and make a note of any existing Perl files:

$ ls -ld /usr/local /usr/local/bin 2>/dev/null || true
$ ls -l /usr/local/bin/perl /usr/local/bin/perl5.38.2 2>/dev/null || true

If the destination already contains a Perl you need, stop and decide whether to use a separate prefix such as $HOME/opt/perl-5.38.2. A different prefix requires re-running Configure; do not change it only on the make install line.

$ sudo make install

There is no safe, universal undo command for an installation because an older file may have been replaced. The recovery is to restore the previous files from your backup or reinstall the previous Perl through the same package or source process. This is why the guide keeps the source tree and recommends a separate prefix when /usr/local is already in use.

6. Verify which Perl your shell is using

Installation does not necessarily change your shell's command lookup. Check both the installed binary and the system Perl explicitly:

$ /usr/local/bin/perl -e 'print "$^V\n"'
v5.38.2
$ /usr/bin/perl -e 'print "$^V\n"'
$ command -v perl

The first command should report the built release. The second reports whatever version Apple supplies on that macOS installation. If command -v perl still prints /usr/bin/perl, nothing is broken: your PATH still prefers the system location.

For your own scripts, use an explicit shebang such as #!/usr/local/bin/perl only after confirming that path on every target machine. Do not rewrite scripts supplied by Apple or third-party installers merely to use the new interpreter. The manual warns that those scripts were generally tested with /usr/bin/perl.

7. Leave SDK and universal builds until you need them

The manual also documents SDK selection with an SDK environment variable and compiler and linker additions, plus universal binaries for old PowerPC and Intel combinations. These are specialised builds, not required for an ordinary native installation. If you need one, verify that the SDK path exists before configuring:

$ export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk
$ test -d "$SDK" && echo "SDK exists"
$ ./Configure -Accflags="-nostdinc -B$SDK/usr/include/gcc -B$SDK/usr/lib/gcc -isystem$SDK/usr/include -F$SDK/System/Library/Frameworks" -Aldflags="-Wl,-syslibroot,$SDK" -de

Replace the example SDK path with one that exists on the target. The manual warns that these settings also affect CPAN XS modules and that linked libraries must support every selected architecture. A successful Perl build therefore does not prove that later modules will link.