Files
VCCPlusOSS/docs/development/CMOC_RUNTIME.md
T

80 lines
8.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Self-contained CMOC runtime
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
## Runtime contract
| Tool or directory | Purpose |
| --- | --- |
| `bin/make` | GNU Make 4.4.1: ordinary, recursive, incremental and parallel Makefile builds. |
| `bin/cmoc`, `libexec/cmoc` | Relocatable wrapper/native CMOC 0.1.100 compiler. |
| `bin/cpp`, `bin/mcpp` | Native CMOC adapter and mcpp 2.7.2 preprocessor. |
| `bin/lwasm`, `bin/lwlink`, `bin/lwar` | LWTools 4.25 assembler, linker and archive tool. |
| `bin/writecocofile` | CMOC's native disk-image insertion utility. |
| `bin/perl` | Universal launcher for bundled Perl 5.44.0 and its matching core modules. |
| `bin/install-coco-boot-loader` | Relocatable wrapper running the unchanged upstream loader script with bundled Perl. |
| `share/cmoc` | Target headers/runtime and optional library archives. |
| `libexec/perl/<architecture>` | Independent relocatable interpreter/core-module installation; architecture-specific `Config.pm` and XS modules stay paired. |
| `LICENSES`, `manifest.json` | Retained upstream notices, tool versions, library hashes and native-helper architecture inventory. |
The app selects bundled tools first on PATH and removes inherited Make/Perl overrides. Project recipes may intentionally set their own variables. Makefiles still run ordinary commands: a recipe requiring an additional host compiler, third-party command, GNU-specific tar option or non-core Perl package must supply that dependency. “Full Make” does not imply every possible program a Make recipe can call is bundled. We do not download CPAN packages or provide a host C/XS development SDK.
The compiler wrapper creates a temporary space-free alias for target headers/libraries because upstream CMOC builds some assembler/linker commands through a shell. Application and project-directory names containing spaces work. Keep individual source and product filenames simple relative names; arbitrary shell metacharacters/spaces inside those individual names remain an upstream limitation.
The maintained `cmoc-make-dependencies.patch` escapes generated Make dependency targets/prerequisites and decodes quoted preprocessor paths in both CMOC readers. The adapter quotes raw path characters emitted by mcpp. This covers real SDK header paths inside a relocated `VCC Plus.app`, including parent directories containing spaces, quotes, `#` and `$`. `verify-runtime.py` exercises both `--deps-only` and `--deps`, automatic inclusion/regeneration, changed-header rebuilding and no-op builds on both architectures.
The bundled CMOC 0.1.100 optimizer preserves accumulator-indexed addresses when simplifying byte subtraction and comparisons. The runtime manifest records `vccIndexedByteSubtractionFix: 1`. The change takes effect when a project is recompiled. [Compiler patch and regression](../../tools/toolchain/patches/README.md)
The runtime manifest records `vccAddZeroFlagsFix: 1` for correct logical negation of integer results at `-O2`. Recompile existing guest programs to pick up the fix. [Logical negation regression](../../tools/toolchain/patches/README.md)
App staging adds a deterministic payload hash to the installed manifest. Workspace caches therefore invalidate when the compiler, helpers or headers change, even with the same upstream version.
Native project builds pass `MAKE=make` with the bundled tools first on PATH. This keeps recursive `$(MAKE)` recipes working when the actual application path contains spaces. The runtime regression includes a recursive child Makefile.
### Scoped inline-assembly preprocessing
Ordinary C uses mcpp's standard conforming preprocessing. If explicit `asm { ... }` blocks occur, the adapter obtains a second expansion in mcpp's documented assembler mode and substitutes only those balanced assembly bodies. This preserves immediate/indexed operands such as `#COUNT` and `-COUNT,x` without changing ordinary C token boundaries, string literals, macro stringizing or preprocessing errors. Both passes must identify matching block counts; an incomplete or inconsistent block fails rather than compiling a truncated transformation. Source line markers are retained and translated to CMOC's expected syntax.
The adapter does not globally enable assembler mode or LWASM `newsource`. Five regressions cover assembly macro operands, multiple blocks/include markers, unchanged C/string behavior, invalid C token-paste rejection, error line numbers and actual generated 6809 immediate bytes.
## Included target libraries
The standalone compiler now builds all nine reviewed library archive targets. The installed public runtime includes the following headers/archives; add the relevant `-l` option to the project's Makefile rather than automatically linking everything.
| Library | Link option | Upstream terms |
| --- | --- | --- |
| BGraph | `-lbgraph` | Public domain, original acknowledgments retained. |
| BSound | `-lbsound` | Public domain. |
| BControl | `-lbcontrol` | Public domain. |
| CardGame | `-lcardgame` | Public domain. |
| HiresTxt | `-lhirestxt` | Public domain. |
| AStar | `-lastar` | Public domain. |
| WydeAlloc | `-lwydealloc` | GPL-3.0-or-later. |
| Ebitor | `-lebitor` | GPL-3.0-or-later. |
| VCC Plus Speech/Sound | `-lssc` | GPL-3.0-or-later. Requires Speech/Sound for audible output. |
| VCC Plus Orchestra-90 | `-lorch90` | GPL-3.0-or-later. Stereo DAC access works with the optional composer ROM omitted. |
| VCC Plus GIME graphics | `-lgime` | GPL-3.0-or-later. Two 320 × 192, 16-color pages on a CoCo 3. |
| VCC Plus joystick input | `-linput -lbcontrol` | GPL-3.0-or-later wrapper over public-domain BControl. Samples one CoCo port per call. |
| VCC Plus C compatibility subset | `-lvcccompat` | GPL-3.0-or-later. In a custom Makefile, also set `export VCC_CMOC_COMPAT = 1` to activate its headers. |
| decbfile ROM-backed core | `-ldecbfile` | Public domain; subset described below. |
`tools/toolchain/stage-libraries.py` builds eight optional libraries from unchanged source copies with the bundled compiler and unusable Apple SDK settings. Header names, archive bytes and upstream notices are recorded in the runtime. GPL library linking carries its own obligations; compiler licensing does not automatically determine the license of an otherwise independent user program.
## Validation
```sh
python3 tools/toolchain/verify-sources.py
python3 tests/toolchain/test_cpp_adapter.py
python3 tools/toolchain/verify-runtime.py platforms/macos/LocalResources/ToolchainBundle
```
Runtime verification audits all native helpers for architecture slices and system-only dependencies, relocates the whole payload into a path with spaces, and compiles through bundled Make with invalid Apple developer-directory/SDK settings. It repeats with separately thinned Apple Silicon/Intel helper tools, exercises bundled Perl's Getopt::Long and Digest::SHA XS module, and checks the boot-loader wrapper. Deliberate preprocessing failure must stop Make with the correct line number. Intel execution on Apple Silicon uses Rosetta.
November 3, 2026: all nine library archive builds passed without the SDK preprocessor. The original CoCo Letters project built its 161,280-byte disk using the bundled compiler, interpreter and asset/boot helpers. Full Apple Silicon and separately thinned Intel builds produced identical disk bytes (SHA-256 `da81baceb20967be2822a353ae64369eda7e830102b21a0127052d04fead1470`); a no-op Make and clean parallel rebuild also passed. Its disk booted on both emulated CPUs with 128 KB; title, RGB/Easy/User selection, cursor response, 90,624 read events, zero writes and 2,040 nonzero audio samples passed. This is a smoke test, not exhaustive gameplay qualification.
Perl is dual-licensed GPL-1.0-or-later / Artistic-1.0-Perl; retained component notices include the bzip2 BSD-style license. mcpp is BSD-2-Clause. GNU Make's executable is GPL-3.0-or-later; its separate manual retains GFDL terms. Exact source snapshots, upstream notices and hashes are in `third_party/`. No private input is needed to reproduce the public toolchain.
## C debug metadata
The local [CMOC debug extension](../../tools/toolchain/patches/README.md) is applied to compiler build copies, leaving the pinned upstream snapshot unchanged. Compiling with `-fno-omit-frame-pointer` emits versioned type/scope/storage metadata; unoptimized preserved frames enable locals. The IDE verifies it against the same linked artifacts used for C source mapping. See [C source debugging](CMOC_SOURCE_DEBUGGING.md) for capabilities and limits.