Plan: Distribute pre-built cross-compiled runtimes in ponyc releases

[SeanTAllen]

Cross-compilation to Linux targets via embedded LLD (#4964) works. The problem is getting the runtime libraries to users who don't want to build LLVM from source. Right now, if you install ponyc via ponyup, you can't cross-compile without cloning the ponyc repo and running make libs + make cross-libponyrt. That's a non-starter for most people.

The fix: bundle pre-built cross-compiled runtimes (libponyrt + CRT objects) directly in the ponyc release tarballs. Install ponyc, get cross-compilation support for free. No separate downloads, no extra steps.

Change Type

Added (new feature). PR gets a changelog - added label and a release notes file.

What Gets Bundled

Each host platform's tarball includes cross-compiled runtimes for the other supported Linux targets:

x86-64 host tarball includes:

• aarch64-unknown-linux-gnu
• riscv64-unknown-linux-gnu
• arm-unknown-linux-gnueabi
• arm-unknown-linux-gnueabihf

arm64 host tarball includes:

• x86_64-unknown-linux-gnu
• riscv64-unknown-linux-gnu
• arm-unknown-linux-gnueabi
• arm-unknown-linux-gnueabihf

The total size increase is about 2MB per tarball. Negligible.

Install Tree Layout

Cross-runtimes go in lib/<triple>/ alongside the native runtime:

x86-64 host:

lib/
  x86-64/                           # native (existing)
    libponyrt.a
    libponyrt-pic.a
    crtbeginS.o / crtendS.o / crtbeginT.o / crtend.o
  aarch64-unknown-linux-gnu/        # cross target
    libponyrt.a
    libponyrt-pic.a
    crtbeginS.o / crtendS.o / crtbeginT.o / crtend.o
  riscv64-unknown-linux-gnu/        # cross target
    ...
  arm-unknown-linux-gnueabi/        # cross target
    ...
  arm-unknown-linux-gnueabihf/      # cross target
    ...

arm64 host:

lib/
  armv8-a/                          # native (existing)
    libponyrt.a
    libponyrt-pic.a
    crtbeginS.o / crtendS.o / crtbeginT.o / crtend.o
  x86_64-unknown-linux-gnu/         # cross target
    libponyrt.a
    libponyrt-pic.a
    crtbeginS.o / crtendS.o / crtbeginT.o / crtend.o
  riscv64-unknown-linux-gnu/        # cross target
    ...
  arm-unknown-linux-gnueabi/        # cross target
    ...
  arm-unknown-linux-gnueabihf/      # cross target
    ...

Using the full triple for directory names keeps things unambiguous and matches the --triple compiler flag. The convention scales to future targets without any structural changes.

Which Tarballs

x86-64 and arm64 Linux glibc (Ubuntu) tarballs. These are the primary cross-compilation hosts. Alpine, macOS, and Windows tarballs are unchanged.

User Workflow

# Install ponyc via ponyup (cross-runtimes included)
ponyup update ponyc nightly

# Install target sysroot
sudo apt install gcc-aarch64-linux-gnu

# Cross-compile
PONYPATH=/path/to/ponyc/lib/aarch64-unknown-linux-gnu \
  ponyc --triple=aarch64-unknown-linux-gnu \
        --cpu=generic \
        --linker=aarch64-linux-gnu-gcc \
        myapp

The user still sets PONYPATH manually. A future compiler enhancement could auto-discover runtimes in lib/<triple>/ when --triple is specified, but that's a separate issue.

Implementation

Makefile changes

Two things need to happen. First, a cross_name variable that controls the cross-build output directory. Right now both arm and armhf use arch=armv7-a, which means they'd write to the same directory if built in the same job. cross_name defaults to $(arch) so existing tier-2 CI is unaffected, but the nightly/release builds can set it to the triple to keep outputs separate.

Second, a cross-install target that copies cross-compiled artifacts into the install prefix. It mirrors the native install target's logic for libponyrt.a, libponyrt-pic.a, and the CRT objects.

Docker images

Two sets of Docker image changes are needed.

Ubuntu builder images get cross-compiler packages added. One-time change in the ponyc-ci-dockerfiles repo.

x86-64 builders (ponyc-ci-x86-64-unknown-linux-ubuntu24.04-builder and 22.04 variant):

• gcc-aarch64-linux-gnu
• gcc-riscv64-linux-gnu
• gcc-arm-linux-gnueabi
• gcc-arm-linux-gnueabihf

arm64 builder (ponyc-ci-arm64-unknown-linux-ubuntu24.04-builder):

• gcc-x86-64-linux-gnu
• gcc-riscv64-linux-gnu
• gcc-arm-linux-gnueabi
• gcc-arm-linux-gnueabihf

Existing CI cross-arm and cross-armhf images switch from Linaro GCC 7.5.0 (2019) tarballs to Ubuntu apt packages (gcc-arm-linux-gnueabi, gcc-arm-linux-gnueabihf). The base image is Ubuntu 24.04 with GCC 13+, so apt provides a much newer compiler than the frozen Linaro release. This eliminates the Linaro dependency entirely — all ARM cross-compilation uses apt-provided compilers, so CI validation and nightly/release builds use identical toolchains.

Nightly and release scripts

The existing nightly/release scripts (x86-64-nightly.bash, arm64-nightly.bash, x86-64-release.bash, arm64-release.bash) are shared across Linux Ubuntu, Linux Alpine, and macOS builds. Cross-compiled runtimes only apply to Ubuntu (glibc) builds. Rather than adding guards or no-op calls to the shared scripts, four new explicitly-named scripts handle the Ubuntu builds:

• x86-64-nightly-with-cross-runtimes.bash
• arm64-nightly-with-cross-runtimes.bash
• x86-64-release-with-cross-runtimes.bash
• arm64-release-with-cross-runtimes.bash

Each mirrors the corresponding existing script but adds cross-runtime build and install between make install and tar. The existing scripts stay unchanged for macOS and Alpine. The workflow entries for Ubuntu switch to the new scripts.

Cross-compilation stanzas in each script:

x86-64 host scripts build:

aarch64:

• arch=armv8-a (consistent with native arm64 builds)
• cross_cc=aarch64-linux-gnu-gcc, cross_cxx=aarch64-linux-gnu-g++
• cross_cflags="-march=armv8-a -mtune=generic" (generic tuning — aarch64 targets span Graviton, Ampere, Cortex-A72/A76, and others)
• cross_llc_flags=-march=aarch64
• cross_name=aarch64-unknown-linux-gnu

riscv64:

• arch=rv64gc
• cross_cc=riscv64-linux-gnu-gcc, cross_cxx=riscv64-linux-gnu-g++
• cross_cflags="-march=rv64gc -mtune=rocket"
• cross_llc_flags=-march=riscv64
• cross_name=riscv64-unknown-linux-gnu

arm (soft-float):

• arch=armv7-a
• cross_cc=arm-linux-gnueabi-gcc, cross_cxx=arm-linux-gnueabi-g++
• cross_cflags="-march=armv7-a -mtune=cortex-a9"
• cross_llc_flags="-O3;-march=arm"
• cross_name=arm-unknown-linux-gnueabi

arm (hard-float):

• arch=armv7-a
• cross_cc=arm-linux-gnueabihf-gcc, cross_cxx=arm-linux-gnueabihf-g++
• cross_cflags="-march=armv7-a -mtune=cortex-a9"
• cross_llc_flags="-O3;-march=arm"
• cross_name=arm-unknown-linux-gnueabihf

arm64 host scripts build:

x86-64:

• arch=x86-64 (consistent with native x86-64 builds; CMake auto-adds -mcx16 when CMAKE_SYSTEM_PROCESSOR is x86-64)
• cross_cc=x86_64-linux-gnu-gcc, cross_cxx=x86_64-linux-gnu-g++
• cross_cflags="-march=x86-64 -mtune=generic"
• cross_llc_flags=-march=x86-64
• cross_name=x86_64-unknown-linux-gnu

riscv64:

• arch=rv64gc
• cross_cc=riscv64-linux-gnu-gcc, cross_cxx=riscv64-linux-gnu-g++
• cross_cflags="-march=rv64gc -mtune=rocket"
• cross_llc_flags=-march=riscv64
• cross_name=riscv64-unknown-linux-gnu

arm (soft-float):

• arch=armv7-a
• cross_cc=arm-linux-gnueabi-gcc, cross_cxx=arm-linux-gnueabi-g++
• cross_cflags="-march=armv7-a -mtune=cortex-a9"
• cross_llc_flags="-O3;-march=arm"
• cross_name=arm-unknown-linux-gnueabi

arm (hard-float):

• arch=armv7-a
• cross_cc=arm-linux-gnueabihf-gcc, cross_cxx=arm-linux-gnueabihf-g++
• cross_cflags="-march=armv7-a -mtune=cortex-a9"
• cross_llc_flags="-O3;-march=arm"
• cross_name=arm-unknown-linux-gnueabihf

Tier-2 CI for cross-compilation

The three existing cross-compilation CI jobs (riscv64, arm, armhf) all cross-compile from x86-64. Two additional categories of CI coverage are needed:

1. aarch64 cross-compilation from x86-64: New cross-aarch64 Docker image and workflow job, following the existing pattern.

2. x86-64 cross-compilation from arm64: New cross-x86-64 Docker image and workflow job on arm64 runners.

The riscv64/arm/armhf cross targets from arm64 hosts don't need separate CI jobs — they use the same cross-compilers and produce the same artifacts as from x86-64 hosts, and the cross-compilation machinery is validated by the existing jobs.

General Framework for Future Targets

Adding a new cross target is mechanical once this infrastructure is in place:

1. Add the cross-compiler to the builder Docker images
2. Add a stanza to the *-with-cross-runtimes.bash scripts
3. Make sure a tier-2 CI job validates the target (this should already exist before we'd distribute it)

Potential future targets: wasm32-unknown-unknown (different model, would need its own approach).

Open Questions

1. LLC target inference: The except_try_catch.ll compilation should be verified to produce correct-architecture object files even without explicit LL_FLAGS. The tier-2 CI tests pass, so it works in practice, but worth confirming.

2. LLVM -march for x86-64: Verify that llc -march=x86-64 is the correct LLVM target name for 64-bit x86 when cross-compiling except_try_catch.ll from arm64.

Tracks #4968.

[SeanTAllen]

Reworked as #5591 and superseded by it. ponyc is fully on embedded LLD now, so the linker comes from the target triple and there is no --linker flag to set; the new plan also makes the bundled runtime resolve from --triple alone. Closing this in favor of that one.