Building SQLite on Apple M1 Fails Due to Outdated config.guess/config.sub

Build Failure on Apple M1 with "Invalid Configuration arm64-apple-darwin" Error

Issue Overview: Mismatched Architecture Detection in SQLite Build System

The core problem arises when attempting to build SQLite on Apple Silicon (M1/M2) machines using environments that rely on GNU Coreutils utilities like uname, such as Nix Shell or Homebrew. The ./configure script fails with an error indicating an unrecognized machine type arm64-apple-darwin20.6.0. This occurs because SQLite’s build system uses outdated config.guess and config.sub scripts that do not recognize the arm64 architecture identifier.

These scripts are part of the GNU Autotools framework and are responsible for detecting the host system’s architecture, operating system, and other platform-specific details. When they are outdated, they cannot map the arm64 identifier returned by uname -m (or guname -m in GNU Coreutils) to a valid machine type. This results in a broken build chain, as the configure script cannot generate a valid system configuration. The error is particularly acute in environments where GNU Coreutils tools override or supplement macOS’s native utilities, such as Nix Shell, which prioritizes GNU tools in the PATH.

The macOS native uname utility reports arm for the processor type (uname -p), while GNU Coreutils’ guname -p reports arm64. This discrepancy creates further confusion in build systems expecting consistency between these values. SQLite’s build process relies on these values to set compiler flags, link libraries, and configure platform-specific optimizations. When config.guess and config.sub cannot reconcile these values, the build aborts. The problem is exacerbated by the fact that SQLite’s included config.guess and config.sub files date to 2019, predating the release of Apple Silicon hardware (2020) and its associated software ecosystem changes.

Possible Causes: Outdated Autotools Scripts, Toolchain Conflicts, and Coreutils Discrepancies

1. Obsolete config.guess and config.sub Files in SQLite Source Tree

The config.guess and config.sub scripts distributed with SQLite are versioned from May 2019. These scripts lack support for the arm64-apple-darwin triple used by Apple Silicon. The GNU Autotools project maintains these scripts, and updates are regularly released to support new architectures. SQLite’s build system has not integrated these updates, leading to a mismatch between the detected architecture (arm64) and the known machine types in the scripts. The failure occurs because config.sub cannot normalize arm64-apple-darwin20.6.0 into a valid triple, causing configure to abort.

2. Toolchain Environment Differences: Nix Shell, Homebrew, and PATH Ordering

Environments like Nix Shell or Homebrew alter the default toolchain behavior by prioritizing GNU Coreutils (e.g., guname) over macOS’s BSD-derived utilities. macOS’s native uname reports arm for the processor type (uname -p), while GNU Coreutils’ guname reports arm64. Build systems that use GNU Coreutils tools will see inconsistent architecture detection compared to those using macOS tools. For example, Nix Shell modifies the PATH to include GNU utilities first, causing configure to use guname instead of the native uname. This creates a divergence from SQLite’s default build expectations, which are tuned for macOS’s toolchain.

3. GNU Coreutils Bug in uname for Apple Silicon

A specific bug in GNU Coreutils (fixed in late 2021) caused uname -p to report arm64 instead of arm on Apple Silicon. This bug was patched in Coreutils’ Git repository but had not been backported to stable releases at the time of the discussion. Environments using pre-patch Coreutils versions (e.g., Homebrew’s coreutils formula) inherited this bug, leading to incorrect processor type detection. SQLite’s build system, expecting arm from uname -p, instead receives arm64, which is not handled by the outdated config.sub script.

Troubleshooting Steps: Updating Autotools Scripts, Environment Workarounds, and Coreutils Patching

1. Update config.guess and config.sub to Latest Versions

The definitive fix is to replace SQLite’s outdated config.guess and config.sub files with the latest versions from the GNU Autotools repository. These files are maintained upstream and include support for Apple Silicon’s arm64 architecture.

Steps:

1. Download the latest config.guess and config.sub from GNU’s Git repository:

   wget -O config.sub https://git.savannah.gnu.org/cgit/config.git/plain/config.sub
   wget -O config.guess https://git.savannah.gnu.org/cgit/config.git/plain/config.guess
   

2. Replace the existing files in SQLite’s source tree with the downloaded versions.
3. Rerun ./configure to regenerate the build system with the updated architecture detection.

Validation:
After updating, running bash ./config.sub $(bash ./config.guess) should output aarch64-apple-darwin20.6.0 instead of failing. The aarch64 identifier is recognized by modern Autotools scripts as equivalent to arm64, resolving the configuration error.

2. Modify Environment to Prioritize macOS Native Tools

If updating Autotools scripts is not feasible (e.g., in a restricted build environment), reconfigure the toolchain to use macOS’s native utilities instead of GNU Coreutils. This ensures uname -p returns arm, matching SQLite’s expectations.

Steps for Nix Shell:

1. Adjust the PATH variable to place /usr/bin before Nix-managed paths:

   export PATH="/usr/bin:$PATH"
   

2. Verify tool precedence with which uname, which should return /usr/bin/uname.

Steps for Homebrew:

1. Avoid using gnu-uname or other Coreutils formulae that override system utilities. If installed, unlink them:

   brew unlink coreutils
   

2. Ensure Homebrew does not add GNU utilities to the PATH by default by modifying shell configuration files (e.g., .zshrc, .bashrc).

3. Apply GNU Coreutils Patches for Apple Silicon Compatibility

If the environment requires GNU Coreutils, apply the upstream patch that fixes uname -p reporting on Apple Silicon. This patch corrects the processor type detection to align with macOS’s behavior.

Steps:

1. Clone the GNU Coreutils Git repository:

   git clone https://git.savannah.gnu.org/git/coreutils.git
   

2. Check out the commit with the Apple Silicon patch:

   git checkout e3d1ff04370b3e090e4cfeb8f6cc4a63590a516f
   

3. Build and install Coreutils from source, replacing the buggy versions in Homebrew or Nix.

Note: This approach is recommended only for advanced users, as building Coreutils from source introduces maintenance overhead. Prefer using updated Autotools scripts in SQLite as the primary solution.

4. Manual Override of Configure Script Parameters

As a temporary workaround, manually specify the host system type to bypass architecture detection. This forces the build system to use known-good settings for Apple Silicon.

Steps:

1. Run ./configure with explicit host and build parameters:

   ./configure --build=aarch64-apple-darwin --host=aarch64-apple-darwin
   

2. Verify that the configure script accepts these parameters and proceeds to generate the Makefile.

Limitations: This method assumes prior knowledge of valid configuration triples and may not handle all platform-specific optimizations correctly. It is a stopgap until config.guess and config.sub are updated.

5. Advocate for Upstream Updates to SQLite’s Build System

To prevent future issues, engage with the SQLite community to update the config.guess and config.sub files in the official source distribution. This ensures all users benefit from improved architecture detection without manual intervention.

Steps:

1. File a bug report or feature request on SQLite’s Fossil repository, referencing the GNU Coreutils patch and Apple Silicon build failures.
2. Submit a patch to the SQLite team with updated Autotools scripts, ensuring compatibility with their build process.

Outcome: Once accepted, SQLite’s official releases will include modern Autotools scripts, eliminating the need for manual updates on Apple Silicon systems.