Building Chromium on Linux ARM64

chromium-linux-arm64.md

Building Chromium on Linux (Arch Linux / ARM64)

This guide documents the process for building Chromium on an Arch Linux system, specifically addressing challenges with depot_tools and architecture mismatches on ARM64.

Prerequisites

• OS: Arch Linux (ARM64)
• Disk Space: >100GB (SSD recommended)
• RAM: >8GB (16GB+ recommended)
• Tools: git, python3

1. Install System Dependencies

On Arch Linux, the provided install-build-deps.sh script does not work. You must install dependencies manually via pacman.

In addition to standard build tools, we must install system compilers (Clang, Rust, LLD) because the pre-packaged binaries downloaded by Chromium are for x86_64 only.

sudo pacman -S --needed python perl gcc gcc-libs bison flex gperf pkgconfig \
    nss alsa-lib glib2 gtk3 nspr freetype2 cairo dbus xorg-server-xvfb \
    xorg-xdpyinfo nodejs clang llvm lld rust rust-bindgen

Note: We include nodejs, clang, rust, etc., because the bundled binaries in Chromium source are x86_64 and will fail on ARM64.

2. Install depot_tools

Clone the tools repository and add it to your PATH.

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
export PATH="$PWD/depot_tools:$PATH"

3. Fetch the Code

Create a directory and fetch the source. Using --no-history significantly reduces the download size and time.

mkdir chromium && cd chromium
fetch --nohooks --no-history chromium
cd src

4. Fix Node.js Architecture Mismatch (ARM64 Specific)

Chromium's build process (gclient runhooks) downloads a bundled Node.js binary at third_party/node/linux/node-linux-x64/bin/node. This binary is compiled for x86_64 and will fail with Exec format error on ARM64 systems.

The Fix: Replace the bundled binary with a symlink to the system's ARM64 Node.js.

# Verify your system node location
which node
# e.g., /usr/bin/node

# Replace the incompatible binary
rm -f third_party/node/linux/node-linux-x64/bin/node
ln -s $(which node) third_party/node/linux/node-linux-x64/bin/node

5. Configure Build for ARM64 (System Toolchain)

By default, Chromium attempts to use its bundled Clang and Rust toolchains (x86_64). On ARM64, we must force it to use the system's toolchains. Simply pointing clang_base_path to /usr is often insufficient because the build scripts expect a specific directory layout and versioning that system packages do not match.

5.1. Create a Fake Toolchain Directory

We create a directory structure that mimics what Chromium expects, but populates it with symlinks to our system binaries.

# Create the base directory
mkdir -p third_party/llvm-build/Release+Asserts/bin
mkdir -p third_party/llvm-build/Release+Asserts/lib

# Symlink essential binaries
for tool in clang clang++ lld llvm-ar llvm-nm llvm-readelf llvm-objcopy llvm-strip llvm-profdata llvm-symbolizer ld.lld; do
  ln -sf /usr/bin/$tool third_party/llvm-build/Release+Asserts/bin/$tool
done

5.2. Handle Version Mismatches and Headers

Chromium often expects a specific version of Clang (e.g., 23) while the system might have an older one (e.g., 21). We need to symlink the system headers to the location Chromium checks.

# Check your system clang version
clang --version 
# e.g., returns 21.1.8

# Find the resource directory
clang -print-resource-dir
# e.g., /usr/lib/clang/21

# Create the expected directory structure (check args.gn or error logs for the expected version, e.g., 23)
mkdir -p third_party/llvm-build/Release+Asserts/lib/clang/23/include

# Symlink system headers to the expected location
ln -sf /usr/lib/clang/21/include/* third_party/llvm-build/Release+Asserts/lib/clang/23/include/

# Also ensure the system version directory exists in the fake toolchain
mkdir -p third_party/llvm-build/Release+Asserts/lib/clang/21
ln -sf /usr/lib/clang/21/include third_party/llvm-build/Release+Asserts/lib/clang/21/include

5.3. Fix Runtime Libraries

Chromium looks for libclang_rt.builtins.a. On Arch Linux, this might be named libclang_rt.builtins-aarch64.a.

# Locate the system library (path may vary)
find /usr/lib/clang -name "libclang_rt.builtins*.a"

# Symlink it to the expected name in the fake toolchain
# (Adjust source path based on the 'find' command result)
ln -sf /usr/lib/clang/21/lib/aarch64-unknown-linux-gnu/libclang_rt.builtins-aarch64.a \
       third_party/llvm-build/Release+Asserts/lib/clang/21/lib/aarch64-unknown-linux-gnu/libclang_rt.builtins.a

6. Configure GN Arguments

Run gn args out/Default and use the following configuration to point to our fake toolchain and system Rust.

# Point to our fake toolchain
clang_base_path = "//third_party/llvm-build/Release+Asserts"
clang_use_chrome_plugins = false  # Plugins are pre-built x86_64 binaries

# Use system Rust
enable_rust = true
enable_rust_cxx = true
rust_sysroot_absolute = "/usr"
rust_bindgen_root = "/usr"

# Disable bundled sysroot (use system libraries)
use_sysroot = false

# Relax strict warnings and checks
treat_warnings_as_errors = false
llvm_force_head_revision = true  # Bypass version checks

# Disable Siso (use Ninja instead)
use_siso = false

7. Handle Compiler Flags

System compilers might not support all flags used by Chromium's bleeding-edge Clang. You may need to edit build/config/compiler/BUILD.gn to remove unsupported flags if you encounter "unknown warning option" errors.

Common flags to remove/comment out:

• -Wno-unsafe-buffer-usage-in-static-sized-array
• -fno-lifetime-dse
• -fsanitize-ignore-for-ubsan-feature=array-bounds

8. Compile

Regenerate build files and start the build using autoninja.

# Regenerate build files
gn gen out/Default

# Clean up Siso state if present (optional, if switching from Siso)
rm -f out/Default/.siso*

# Build
autoninja -C out/Default chrome

Tip: This process can take several hours.

9. Run

Once the build completes, the binary is located at:

./out/Default/chrome