# 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

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

`setup.sh` installs:

1. **System apt packages** — build-essential, cmake, ninja, clang, lld,
   python3, MAME, etc. See [`scripts/installDeps.sh`](../scripts/installDeps.sh)
   for the full list. *Requires sudo.*
2. **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`.
3. **Apple IIgs MAME** — installs MAME via apt and downloads the
   apple2gs ROMs to `tools/mame/roms/`.
4. **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.
5. **ORCA/C** — Apple's official 65816 C compiler (header reference
   for the IIgs Toolbox bindings).

After `setup.sh` finishes:

```bash
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:

```bash
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:

```bash
./setup.sh --build-llvm
```

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

```bash
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

```bash
# 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

```bash
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:

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

## Uninstalling

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

```bash
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:

```bash
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`](../scripts/runInMame.sh) does this
automatically.

**`linkage error: missing __umulhisi3`** — link `runtime/libgcc.o`
into your binary. See [USAGE.md](USAGE.md#linking).

**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.