Files
Brian Holman 5534005799 Sync VCC Plus 3.7.1 build 67 source
Refresh reviewed MCP output export, four-drive owned playtests, bounded BASIC readiness, and pinned CMOC 0.1.101 source/patches. Preserve independent source-edition identity, empty libraries, notices and privacy boundaries.

Validated 74 export/privacy checks, pinned dependency sources, and an independent unsigned universal Release build. A subsequent documentation-only correction removes an excluded qualification link; all build inputs remain identical.
2026-11-17 08:42:27 -07:00

9.0 KiB
Raw Permalink Blame History

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.101 compiler in the development source tree.
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 CMOC 0.1.101 development 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

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

CMOC 0.1.101 provides upstream writecocofile --allocate-before-dir: try free granules 33 down to 0, then 34 through 67. The VCC Plus --allocate-forward compatibility alias retains ascending 0-through-67 allocation. Both can continue above the directory. Existing recipes that depend on the earlier VCC Plus layout must select the explicit forward alias; do not assume the identical old option name preserves physical layout. The last allocation option wins.

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

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 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 for capabilities and limits.