Installing llvm816

The project installs everything into tools/ under the repo root, so the tree is self-contained and deletable without affecting your system.

System requirements

Ubuntu 22.04 or 24.04 (or any Debian-based distro with apt). Other Linuxes work if you can install the packages listed below by hand.
Disk: ~10 GB free (LLVM build artifacts dominate).
RAM: 8 GB minimum, 16 GB recommended for the --build-llvm flag. The setup script's default skips the LLVM build and downloads a prebuilt toolchain instead — much faster, ~500 MB.
Build time: ~5 minutes for the default (prebuilt) path; 30-60 minutes for --build-llvm (full LLVM source build).

One-command install

git clone <this-repo-url> llvm816
cd llvm816
./setup.sh

setup.sh installs:

System apt packages — build-essential, cmake, ninja, clang, lld, python3, MAME, etc. See scripts/installDeps.sh for the full list. Requires sudo.
llvm-mos — source tree clone at tools/llvm-mos/ and a prebuilt SDK at tools/llvm-mos-sdk/. With --build-llvm it also runs cmake/ninja to build a usable W65816-aware clang at tools/llvm-mos-build/bin/clang.
Apple IIgs MAME — installs MAME via apt and downloads the apple2gs ROMs to tools/mame/roms/.
Calypsi 5.16 — reference 65816 C compiler, installed to tools/calypsi/. Used by the compare/ benchmarks to measure our codegen quality against a commercial baseline.
ORCA/C — Apple's official 65816 C compiler (header reference for the IIgs Toolbox bindings).

After setup.sh finishes:

ls tools/llvm-mos-build/bin/clang   # our compiler
ls tools/link816                     # our linker
mame -version                        # MAME (installed via apt)

Step-by-step (if `setup.sh` fails)

You can run each install script in isolation:

scripts/installDeps.sh         # apt packages
scripts/installLlvmMos.sh      # llvm-mos clone + prebuilt SDK
scripts/installLlvmMos.sh --build  # also build the source (slow)
scripts/installMame.sh         # MAME + apple2gs ROMs
scripts/installCalypsi.sh      # reference compiler (optional)
scripts/installOrcaC.sh        # reference compiler (optional)

If you only want to build C programs (no benchmarks, no comparison to Calypsi), installCalypsi.sh and installOrcaC.sh are optional.

Building the W65816 backend from source

The default install pulls a prebuilt LLVM SDK. To build our W65816-aware clang from source:

./setup.sh --build-llvm

Or, after a non---build-llvm install:

scripts/applyBackend.sh        # symlink our W65816 sources into llvm-mos clone
cmake --build tools/llvm-mos-build --target llc clang

The build takes 30-60 minutes on a modern laptop. Subsequent incremental builds after editing W65816 backend code are ~30 seconds.

Verifying the install

# Compile + disassemble a small C function
scripts/cDemo.sh

# Build the runtime library (libc, libgcc, etc.)
bash runtime/build.sh

# Run the smoke test suite (~150 checks, takes ~3 minutes)
bash scripts/smokeTest.sh

A successful smoke test ends with:

[llvm816] all smoke checks passed

Updating

git pull
scripts/applyBackend.sh        # re-symlink our sources into the LLVM tree
cmake --build tools/llvm-mos-build --target llc clang
bash runtime/build.sh

If you want a fully clean rebuild:

rm -rf tools/llvm-mos-build
./setup.sh --build-llvm

Uninstalling

The toolchain is fully contained under tools/. To uninstall:

rm -rf llvm816/
sudo apt-get remove mame mame-tools     # if you want MAME gone too

The setup script doesn't touch /usr/local or ~/.mame — nothing to clean up outside the repo.

Troubleshooting

cmake: command not found — run scripts/installDeps.sh. The apt packages aren't installed yet.

ROMs not found — the apple2gs ROM download from archive.org occasionally fails. Re-run scripts/installMame.sh. The script is idempotent; it skips ROMs already downloaded.

clang: error: unable to find target 'w65816' — the prebuilt SDK's clang doesn't know about our W65816 target. You need the source-built clang:

scripts/installLlvmMos.sh --build
# Or, more granular:
scripts/applyBackend.sh
cmake --build tools/llvm-mos-build --target clang

The W65816 target lives in our fork at tools/llvm-mos-build/bin/clang, not in the prebuilt SDK.

MAME can't find ROMs at runtime — make sure mame is launched with -rompath tools/mame/roms. The provided scripts/runInMame.sh does this automatically.

linkage error: missing __umulhisi3 — link runtime/libgcc.o into your binary. See USAGE.md.

MAME pops up a window I don't want — the runInMame.sh wrapper now runs headless (-video none + SDL_VIDEODRIVER=dummy). If you're invoking MAME directly, add those flags.

4.9 KiB Raw Blame History