ballz
b7219dccfc
New targets: help (default) — show usage (was the -help/--help equivalent) compile — compile main.c → build/nyuller.prg run — compile + run in oscar64 built-in emulator run-vice — compile + run in VICE x64 (foreground) run-vice-cycle — compile + run in VICE x64sc (cycle-exact) play — compile + launch VICE x64 detached play-cycle — compile + launch VICE x64sc detached kill — kill any detached VICE clean — remove build/ artifacts build/nyuller.d64 — build the .d64 disk image from the .prg Optimization: override with 'make OPT=O3' (or O0/O1/O2/Os/g). Default is -O1 (oscar64 default). The Makefile builds oscar64 automatically if missing, uses c1541 to create the .d64 with verification, and passes -drive8type 1541 to VICE (required for autostart). Removed src/build.sh and updated all docs (README, tasks.md, AGENT_CONTEXT.md, GAME.md, helloworld.c) to reference make.
72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
# nyuller
|
|
|
|
A C64 programming project using [Oscar64](https://github.com/drmortalwombat/oscar64)
|
|
as the cross-compiler. Oscar64 is checked in as a git submodule under
|
|
`./oscar64/`.
|
|
|
|
## Layout
|
|
|
|
```
|
|
.
|
|
├── oscar64/ # Oscar64 cross-compiler (git submodule)
|
|
├── build/ # Build output (gitignored)
|
|
├── docs/c64/ # Low-level C64 reference (memory map, VIC, CIA, SID, …)
|
|
├── src/ # Your C code
|
|
│ └── *.c, *.h
|
|
├── Makefile # Build + run targets (gnu make)
|
|
├── OSCAR64.md # Notes on the Oscar64 compiler internals
|
|
└── PROG_C64.md # Notes on programming the C64 hardware
|
|
```
|
|
|
|
## First-time setup
|
|
|
|
```sh
|
|
# 1. Clone with submodules:
|
|
git clone --recurse-submodules <this-repo-url>
|
|
|
|
# Or, if you already cloned without --recurse-submodules:
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
## Building
|
|
|
|
```sh
|
|
make # show help with all targets
|
|
make compile # compile → build/nyuller.prg (-O1)
|
|
make run # compile + run in oscar64 emulator (headless, fast)
|
|
make play # compile + launch VICE x64 in background
|
|
make kill # kill any detached VICE
|
|
make OPT=O3 # release build (auto-ZP, outliner, aggressive inlining)
|
|
make clean # remove build/ artifacts
|
|
```
|
|
|
|
`make` will build the oscar64 compiler automatically the first time
|
|
(it runs `make -C make compiler` inside `./oscar64/` if
|
|
`./oscar64/bin/oscar64` doesn't exist yet).
|
|
|
|
Run `make help` for the full list of targets with descriptions.
|
|
|
|
**Default test tool is the oscar64 built-in emulator** (`make run`): it
|
|
runs headless, needs no ROMs, no display, and is fast. Every `Verify`
|
|
step in `tasks.md` uses this.
|
|
|
|
**VICE 3.9 is installed** at `/usr/bin/` (`x64`, `x64sc`, `x128`,
|
|
`xvic`, `xpet`) and is available via `make run-vice` / `make run-vice-cycle`.
|
|
It is a GUI emulator and **needs a real X11 / Wayland display to render** — it
|
|
won't produce useful screenshots in this headless environment.
|
|
Use it from a real terminal session for interactive play-testing
|
|
and cycle-exact validation of raster IRQ and SID timing; don't
|
|
expect to script it.
|
|
|
|
## Documentation
|
|
|
|
- `PROG_C64.md` — how the C64 hardware actually works, from a low-level
|
|
programming perspective. Start here if you want to understand what's
|
|
going on under the hood.
|
|
- `OSCAR64.md` — how the Oscar64 compiler works internally, plus a C64-
|
|
specific section on how to use it well (memory model, bank switching,
|
|
raster IRQs, common mistakes).
|
|
- `docs/c64/` — downloaded reference material: the full Commodore 64
|
|
Programmer's Reference Guide text, Christian Bauer's canonical VIC-II
|
|
paper, and per-chip reference notes.
|