Publish VCC Plus OSS source distribution for 3.6.2 build 60

This commit is contained in:
Brian Holman committed 2026-11-13 00:14:03 -07:00
commit c652a5276d
1192 files changed
+272368

No files matched your search

+108
View File
@@ -0,0 +1,108 @@
# VCCPlusOSS
A source distribution of **VCC Plus for Mac**, installed as **VCC Plus OSS**, a native macOS Color Computer emulator derived from VCC. Designed by Brian Holman · Sponsored by Dezota LLC. Original VCC contributors and component credits are retained in the application.
The portable engine, native interface, device emulation, BASIC/C/assembly workspaces, debugger and MCP services are included. Software and Archive libraries start empty. BASIC and Assembly lookup remain available. The full manual collection, archived publications, software corpus and ROMs are not included.
## Independent installation
The app is **VCC Plus OSS.app**, with bundle identifier `com.brianholman.vccplus.oss.mac`. Preferences, application support, cached library artwork and local companion endpoints are separate from VCC Plus. Both editions can be installed on one Mac. They can intentionally open the same user-selected documents; keep separate writable media copies when testing concurrently. No commercial settings or personal media are imported automatically.
The proprietary software-update client, its service protocol and statistics collection are excluded. Install future OSS versions from this repository's reviewed releases. The engine, devices, development workspaces, debugger, SDK and local MCP services remain available. Downloadable content and external companion applications have their own preparation and trust requirements. The local companion transport is retained with a separate OSS endpoint. A publisher can supply `VCCCompanionTeamIdentifier` in the app Info.plist for mutually trusted, Apple-signed OSS companion builds. Without that setting an ordinary ad-hoc build rejects companion peers; it does not inherit commercial publisher trust or disable signature checks. The emulated DriveWire protocol and local MCP services remain available independently of that cross-app trust setup.
## Build
Requires macOS 14 or later, full Xcode with its command-line tools, and Python 3.10 or later for explicit dependency preparation. Both Apple Silicon and Intel are supported build targets. From this directory:
```sh
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
python3 tools/oss/check.py
# Only the filesystem subset is needed for the app/core build.
python3 tools/dependencies/fetch.py --only toolshed
xcodebuild -project platforms/macos/VCC.xcodeproj -scheme VCCMac \
-configuration Release -derivedDataPath .build/macos \
CODE_SIGNING_ALLOWED=NO build
```
The checked-in project defaults to the shared `source` content profile and local ad-hoc signing. No Apple developer account, Developer ID certificate, notarization service or DMG workflow is required. An unsigned command-line build is shown above; opening the project in Xcode uses its local ad-hoc defaults.
The dependency preparation step downloads pinned upstream source releases or repository snapshots, verifies their recorded checksums, applies recorded import patches and retains upstream notices. Generated dependency trees are ignored by Git. After preparation, the checked-in Xcode project also opens directly in Xcode and compilation can run offline. The shared source profile builds lookup from `BASICReference.json` and `AssemblyReference.json`, stages the source prompt selected by `RuntimeTemplates.json`, and does not discover maintainer datasets or ROMs. The full-manual tree is not needed. They generate two empty SQLite libraries from the included schemas. No SQLite database is stored in this repository.
The source checkout contains no ROMs. You can supply your own CoCo 3 system ROM through **Open ROM…**, or explicitly reconstruct the qualified system and Disk BASIC ROMs from external assembly sources:
```sh
python3 tools/dependencies/fetch.py --only cocoroms lwtools
python3 tools/roms/build.py --output .build/roms \
--bundle-output .build/SourceROMBundle
xcodebuild -project platforms/macos/VCC.xcodeproj -scheme VCCMac \
-configuration Release -derivedDataPath .build/macos-with-roms \
VCC_SOURCE_ROM_DIR="$PWD/.build/SourceROMBundle" CODE_SIGNING_ALLOWED=NO build
```
Preparation downloads pinned source inputs explicitly; assembly and app compilation then run offline. The builder uses fresh assembly-only inputs, builds a minimal LWASM when needed, and checks all four reconstructed outputs against recorded sizes and hashes. Only the CoCo 3 system and Disk BASIC ROMs enter the optional app bundle, with source provenance and original-firmware notices. These are reconstructed upstream firmware. Isolated UI-test products omit ROMs even when a bundle is selected. Without an optional bundle the source build remains ROM-free. SDC, RGB-DOS, DriveWire and optional math ROMs are excluded; users may supply compatible ROMs separately. The ROM-free diagnostic and synthetic core checks require none.
## C and assembly tools
Build the reviewed toolchain from the prepared upstream sources and included patches, without private ROMs or disk-driver inputs:
```sh
python3 tools/dependencies/fetch.py
python3 tools/toolchain/verify-sources.py
python3 tools/toolchain/build-runtime.py --output .build/runtime --architectures arm64 x86_64
mkdir -p platforms/macos/LocalResources
cp -R .build/runtime/Toolchain platforms/macos/LocalResources/SourceToolchainBundle
```
Then rebuild the app with its default source profile. `VCC_SOURCE_TOOLCHAIN_DIR` can explicitly select another source-only runtime directory; private runtime inputs are rejected. This bundles CMOC, LWTools, mcpp, Make, Perl and reviewed libraries. Use only your host architecture for a smaller local build. The source-built runtime retains compiler correctness fixes and debug metadata. Run the toolchain build in a fresh output directory; it never downloads dependencies during compilation. Without staging it, the emulator still builds and the development workspaces explain that compiling requires the toolchain. Installed supported C workflows use the bundled tools; building those tools from source requires developer tools.
## Validate
```sh
xcodebuild -project platforms/macos/VCC.xcodeproj -scheme VCCCoreChecks \
-configuration Release -derivedDataPath .build/checks CODE_SIGNING_ALLOWED=NO build
.build/checks/Build/Products/Release/VCCCoreChecks
xcodebuild -project platforms/macos/VCC.xcodeproj -scheme VCCMac \
-destination 'platform=macOS,arch=arm64' -derivedDataPath .build/tests \
CODE_SIGNING_ALLOWED=NO test
```
The default test command is ROM-free and reports optional-input skips. To exercise the ROM-backed disposable-playtest checks after the assembly preparation above, select the same bundle for the separate XCTest build:
```sh
xcodebuild -project platforms/macos/VCC.xcodeproj -scheme VCCMac \
-destination 'platform=macOS,arch=arm64' -derivedDataPath .build/tests-with-roms \
VCC_SOURCE_ROM_DIR="$PWD/.build/SourceROMBundle" CODE_SIGNING_ALLOWED=NO test
```
The playtest tests inspect the ROM pair selected in the actual built app. Extra-firmware and separately staged compiler fixtures remain optional; a skipped check is not a compatibility pass.
Use `arch=x86_64` for Intel execution; on Apple Silicon this uses Rosetta and does not establish physical Intel qualification. Core checks run serially. Additional offline authored regressions can run with:
```sh
python3 -m unittest discover -s tools/tests -p test_build_content.py
python3 -m unittest discover -s tools/dependencies/tests
```
These do not fetch or execute downloaded programs. Optional tests requiring externally supplied ROMs, datasets or toolchains report skips. Desktop interaction tests require their separate isolated scheme and an idle desktop; ordinary validation does not launch the normal app or alter personal media.
## Local app and ZIP distribution
Xcode's **Sign to Run Locally** (ad-hoc identity `-`, empty development team) works without an Apple developer account. These project defaults build the source edition; no Developer ID certificate, Apple upload, notarization or DMG tooling is part of the workflow. Keep an app intended for distribution separate from your build/test products, and review its source-profile resources before creating a ZIP. A ZIP release and its checksum require their own completed validation; this source repository does not establish that a particular downloaded binary has been qualified.
A downloaded ad-hoc app may carry macOS quarantine. After verifying the app's origin and any published checksum, the recipient can remove quarantine from that particular extracted app:
```sh
xattr -dr com.apple.quarantine "/path/to/VCC Plus OSS.app"
```
This does not notarize the app or verify its contents. Locally built apps normally need no quarantine removal. System-wide security settings do not need to change.
## Source and notices
The original project is [VCCE/VCC](https://github.com/VCCE/VCC). Its `COPYING` and `license.txt` are retained unchanged, together with the original contributor credits in About. This distribution has its own source history; the upstream repository remains the reference for original VCC.
`src/core` and `src/devices` contain shared implementation; `platforms/macos` owns the native host. Retained Windows sources are the original host, not a completed VCC Plus Windows edition. `sdk`, `examples` and `tools/toolchain` support guest development. Reviewed upstream locations, license inventory, source hashes and import patches are in `third_party/manifests`; complete dependency source and original notices are fetched into ignored directories.
Application source is GPL-3.0-or-later; see [COPYING](COPYING). Third-party files and artwork retain their own notices and terms. The original artwork notice in `platforms/macos/Resources/About/ArtworkNotice.txt` applies to the unchanged artwork. Production artwork sources and [artwork attribution](docs/media/ATTRIBUTION.md) are retained under `docs/media`. Required dependency provenance includes supplemental legacy-graphics metadata under `tools/dependencies/manifests`.
`EXPORT.json` records the distribution policy and file fingerprints. This repository has an independent history beginning with its source export. Source refreshes occur at selected milestones and are reviewed as ordinary diffs; routine product releases do not automatically update this repository. The private originating revision and local validation evidence are retained outside this repository by the maintainer. Sanitized technical evidence supporting the paper is selected separately under `docs/`; it is not an internal development transcript. No private repository connection or credentials are required to build this distribution.