122 lines
6.8 KiB
Markdown
122 lines
6.8 KiB
Markdown
# Build and test with VCC Plus
|
|
|
|
Use the official [VCC Plus for Mac download](https://vccplus.brianholman.com/downloads/)
|
|
and the complete [Quadrapassel source repository](https://vccplus-git.brianholman.com/VCCPlusApps/Quadrapassel).
|
|
The public installed app supplies CMOC, Make, Perl, libraries and disk tools for
|
|
this project. Homebrew and a separate emulator/toolchain build are not required
|
|
for the installed C-workspace workflow.
|
|
|
|
## Open the existing project
|
|
|
|
1. Obtain the complete repository in a writable local folder. Do not download
|
|
only `main.c`: the game also needs headers, platform/rules files, text assets,
|
|
generator scripts, the Makefile and `vccplus-project.json`.
|
|
2. Choose **Develop → C Development…** in VCC Plus and open that existing project.
|
|
Keep the supplied settings rather than creating a new Hello Disk project over it.
|
|
3. Select **Release**. The game uses its declared Make recipe and `disk` action.
|
|
4. Choose **Build Disk**. The configured Build target also produces the disk;
|
|
use the action displayed by your installed workspace.
|
|
5. Read the complete result, including diagnostics and the memory-bound check.
|
|
Use **Show Build Products** to find the build's `Quadrapassel.DSK` and `QUAD.bin`.
|
|
VCC Plus builds in a separate work area, so the latest result need not appear
|
|
beside the original source files.
|
|
|
|
Release uses the optimization needed by the bounded memory layout. Preserve
|
|
`--data=0E00`, `--limit=7B00` and the 1024-byte stack reserve. The additional link-map
|
|
check enforces code/constant addresses `$1400..$7AFF` and static-data addresses
|
|
`$0E00..$13FF`.
|
|
Do not weaken these guards to make Debug or a larger edit fit.
|
|
|
|
A fresh anonymous checkout has rebuilt the exact build-05 binary and disk using
|
|
the public VCC Plus 3.6.1 bundled Release toolchain. The pristine disk hash is
|
|
`d05ab25fd90171b048cce54f3af18ca6d0bd81335e138044ff05315e99cbf582`.
|
|
See [BUILDS.md](BUILDS.md) for delivery identities and
|
|
[MEMORY_LAYOUT.md](MEMORY_LAYOUT.md) for the section contract.
|
|
|
|
## Launch without losing another program
|
|
|
|
Save guest programs, source drafts and pending media changes before launching.
|
|
**Launch Disk** uses the built disk and the project's declared `DOS` command;
|
|
attend to the app's normal floppy-replacement and restart confirmations. Use a
|
|
writable test copy and preserve personal score disks.
|
|
|
|
Mounting a different disk does not replace the program in RAM. For a new build,
|
|
start it from a clean Disk BASIC state and actually load it with `DOS`. Verify the
|
|
running artifact as well as the mounted filename. The manual loading alternative
|
|
is `PCLEAR1`, `LOADM"QUAD.BIN"`, then `EXEC`.
|
|
|
|
The game supports **CoCo 3 with 128 KB or more**. 128 KB emulation and physical
|
|
512 KB CoCo 3 play have been verified. Set up the intended machine and record its
|
|
actual RAM/CPU/video configuration when testing a change.
|
|
|
|
## Connect ChatGPT to this C project
|
|
|
|
Open **Assistant…** in the C workspace, review the shared files, and select
|
|
**Use Project Makefile**. Allow disposable playtests when isolated execution is
|
|
wanted. Save a new private connection using the supported export process and
|
|
connect it to your assistant. Do not post its token or connection file in source,
|
|
issues or chat messages.
|
|
|
|
Begin with live discovery and a real capabilities request. Confirm this project's
|
|
files, revision, approved recipe, declared configuration and disk action. Use only
|
|
the tool names and argument schemas returned by the installed connection. The
|
|
[MCP setup guide](MCP_SETUP.md) gives a portable checklist; it does not require
|
|
a machine-specific connection.
|
|
|
|
For an owned disposable run:
|
|
|
|
1. Build the current revision's declared disk action in **Release** and inspect
|
|
its result. Bind later observations to its artifact identity.
|
|
2. Start a fresh owned playtest of that artifact and poll startup as documented.
|
|
A supported retained test disk can be selected only with its matching receipt.
|
|
3. Send ordinary guest input, including release intervals. Capture real guest
|
|
graphics/audio when those capabilities are advertised. Never change guest
|
|
memory/registers to manufacture a score or screen.
|
|
4. Test the affected controls, gameplay, saves and return paths. Use advertised
|
|
read-only inspection when appropriate; do not invent unavailable debug values.
|
|
5. Stop the owned run and retain its writable test-disk receipt. Do not stop
|
|
another person's game or delete its media.
|
|
|
|
Disposable-worker choices depend on the installed app. If a worker advertises
|
|
512 KB, that describes the test configuration, not the game's minimum memory.
|
|
Do not describe a 512 KB run as an additional 128 KB check. Likewise, actual
|
|
joystick states and keyboard aliases are different test evidence. Use supported
|
|
native input or a user-controlled physical test when a capability is absent.
|
|
|
|
Before pointer/keyboard automation, obtain a current idle, unlocked desktop window
|
|
unless the user has already granted one for that work. Keep personal machine
|
|
settings and media separate from disposable tests.
|
|
|
|
## Documentation and references
|
|
|
|
Use **Help → Manual Library…** and discover its search/read tools through the
|
|
project connection. For historical CoCo material, **Archive Library…** has its
|
|
own read-only sharing connection. Verify each access separately before falling
|
|
back to an unrelated source. Public installed CMOC headers/examples are also
|
|
valid API references; emulator internals are outside this game's workflow.
|
|
|
|
Public manual chapters describing the interface and sequence:
|
|
|
|
- [Build a disk from a folder](https://vccplus.brianholman.com/manuals/programming-in-c/disk-project/)
|
|
explains Build, Build Disk, Launch Disk and Show Build Products.
|
|
- [Make the first connection](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/01-first-connection/)
|
|
explains private connection exports and verifying real access.
|
|
- [Build a quiz and give ChatGPT the keyboard](https://vccplus.brianholman.com/manuals/vibe-coding-with-chatgpt/06-capitals/)
|
|
demonstrates opening an existing public C project and its Make/disposable loop.
|
|
|
|
Use standard documented CMOC APIs before new hardware-specific code. The existing
|
|
bounded C graphics renderer is a recorded exception; see [AGENTS.md](../AGENTS.md)
|
|
and [DECISIONS.md](DECISIONS.md) for its scope. Preserve component licenses.
|
|
|
|
## Numbered delivery and save data
|
|
|
|
The recipe's `Quadrapassel.DSK` is a clean staging image. Delivered builds use
|
|
`QUADPSLxx.DSK`, with a two-digit number; each changed delivery gets a new filename
|
|
and starts with empty high scores/default settings. Verify that neither QPSAVE
|
|
file is included before copying to a new numbered filename, compare hashes, and
|
|
record the result in [BUILDS.md](BUILDS.md).
|
|
|
|
Never overwrite an existing numbered or personal disk to deliver a build. Preserve
|
|
mounted media, score disks and backups during cleanup. Score migration is a
|
|
separate requested action, not an automatic part of a game update.
|