CI/CD templates for Commodore Plus/4 projects: the c64-tools set with xplus4 and the plus4-builder image

2026-09-07 23:20:17 +02:00
commit 8f6d420e3d
6 changed files with 187 additions and 0 deletions
@@ -0,0 +1,62 @@
+# plus4-build
+
+CI/CD templates for Commodore Plus/4 (ACME + VICE) game projects, in the same
+spirit as [c64-tools](../c64-tools): the Plus/4 shares the C64's 6502 core, so
+the toolchain is the same ACME assembler — only the emulator (`xplus4`), the
+load address (`$1001`) and the TED registers differ.
+
+- `example-makefile.make` — project Makefile: local dev targets
+  (`deps`, `build`, `run`, `clear`, `rebuild`, `rebuildrun`).
+- `example-woodpecker.yaml` — a one-line marker (`platform: plus4`): the
+  full pipeline (version → build → artifact → publish) is served by the update server's Woodpecker
+  configuration extension — preview it with
+  `curl "https://teletypegames.org/build/config?platform=plus4"`.
+- `example-metadata.json` — catalog metadata; the `version` field drives
+  the pipeline's version step, the rest (`name`, `title`, `author`, `desc`, `site`,
+  `repo`, `license`) is what `WarpEngine::Platforms::Plus4::Service` writes into
+  the DB (`site` becomes the "Source Code", `repo` the "Repository"
+  external link).
+- `example-tasks.json` — VS Code `.vscode/tasks.json` wrapping the local
+  make targets.
+
+## Usage in a game repo
+
+1. Copy `example-makefile.make` to `Makefile`, set `PROJECT` (and
+   `TARGET` if the .prg name differs from `$(PROJECT).prg`).
+2. Copy `example-metadata.json` to `metadata.json` and fill it in;
+   `name` must match `PROJECT`.
+3. Copy `example-woodpecker.yaml` to `.woodpecker.yaml` (a one-line marker — the
+   pipeline itself is served by the update server; add `name:` when the
+   software name differs from the repo name) and add the
+   `application_token` secret in Woodpecker (an ApplicationToken with
+   the `update` + `upload` scopes, created in the admin).
+4. Copy `example-tasks.json` to `.vscode/tasks.json`.
+
+## Plus/4 specifics
+
+- A BASIC program starts at `$1001` (the C64's is `$0801`), so the SYS stub
+  and the `* =` origin differ; the entry point after a minimal stub is
+  `$100D` (`SYS 4109`).
+- Screen RAM is at `$0C00`, colour RAM at `$0800`; a colour byte is
+  `luminance << 4 | hue` (bit 7 flashes).
+- Video is the TED at `$FF00`–`$FF3F` (`$FF15` background, `$FF19` border,
+  `$FF1D`/`$FF1C` raster line); there is no VIC-II, no SID and no CIA.
+- The KERNAL jump table is compatible (`$FFD2` CHROUT, `$FFE4` GETIN).
+
+## Builder image
+
+`builder.Dockerfile` bakes the pipeline's build-step dependencies
+(ACME assembler + make) into `git.teletypegames.org/build/plus4-builder`,
+so the build step does not run `apt-get` on every run (VICE is a
+local-dev tool only and is not included):
+
+```sh
+docker build --platform linux/amd64 -f builder.Dockerfile \
+  -t git.teletypegames.org/build/plus4-builder:latest .
+docker push git.teletypegames.org/build/plus4-builder:latest
+```
+
+The served pipeline uploads `$(PROJECT)-$(VERSION).prg` and
+`$(PROJECT)-$(VERSION).metadata.json` via `/build/upload`, then triggers
+`/build/publish?platform=plus4&name=$(PROJECT)&version=$(VERSION)`, which
+creates/updates the Software row and a Release with `cartridge_path`.