168 lines
4.9 KiB
Markdown
168 lines
4.9 KiB
Markdown
# 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.
|