Publish VCC Plus OSS source distribution for 3.6.2 build 60
This commit is contained in:
commit
c652a5276d
1192 files changed
+272368
No files matched your search
@@ -0,0 +1,339 @@
|
||||
# BASIC development workspace
|
||||
|
||||
> 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.
|
||||
|
||||
## Direct machine operations
|
||||
|
||||
- **Load into CoCo** installs the editor's complete program at a safe BASIC
|
||||
prompt, without running it. It replaces the existing in-memory program and
|
||||
prepares a fresh BASIC execution/variable state. The previous running/paused
|
||||
state of the emulator is preserved; a paused load does not execute guest
|
||||
instructions until Run or Resume completes the interpreter initialization.
|
||||
|
||||
- **Run** performs the same validated replacement and starts a fresh execution
|
||||
through the existing ROM interpreter. It does not add a source breakpoint or
|
||||
require an additional Run action in the emulator.
|
||||
|
||||
- **Read from CoCo** reads the program currently in BASIC memory back into the
|
||||
editor. This includes changes made through the CoCo's own line editor. It reads
|
||||
program source, not variable values or a suspended execution checkpoint.
|
||||
|
||||
Load and Run preflight the entire source, ROM, memory mapping, available space
|
||||
and interpreter state before replacing program memory. They refuse an unsafe
|
||||
state, such as a program still executing or waiting for INPUT. Mounted disks,
|
||||
cassettes, cartridges and machine configuration are retained. Existing media
|
||||
save/export protections remain independent of these program-memory operations.
|
||||
|
||||
Read-back is a canonical listing: keywords use their BASIC spellings, `?` may
|
||||
become `PRINT`, lines are numbered and sorted, and ROM-inserted separators around
|
||||
`ELSE` and apostrophe remarks are handled so that reading and reloading preserves
|
||||
the program. It is not a byte-for-byte copy of the editor's original formatting.
|
||||
Programs containing unsupported binary/non-ASCII text or damaged line links are
|
||||
rejected without replacing the editor's contents.
|
||||
|
||||
## BASIC line breakpoints
|
||||
|
||||
Click the gutter circle beside a numbered statement, or use **Toggle BASIC
|
||||
breakpoint at insertion point** in the toolbar. Breakpoints are explicit; the
|
||||
sample and a new document start with none. **Run** installs the program and its
|
||||
breakpoints together, so even its first line can stop before executing. Changes
|
||||
to the breakpoint set can also attach to an already-loaded matching program.
|
||||
|
||||
At a breakpoint the whole emulator pauses, the source line is highlighted, and
|
||||
**Continue** resumes without reloading BASIC, clearing variables, unwinding
|
||||
GOSUB/FOR stacks or closing files. Continue executes the stopped line once before
|
||||
that breakpoint can stop again. **Run** remains a fresh program transfer, subject
|
||||
to the existing OK-prompt guard; it is not the Continue action. The main emulator
|
||||
Resume action can also leave a BASIC stop.
|
||||
|
||||
These are **line-entry breakpoints**. A colon-separated second statement and a
|
||||
return into the middle of a line do not re-trigger that line's entry breakpoint.
|
||||
The stepping controls below can stop at those individual statements.
|
||||
|
||||
In Earth or Mars, set a breakpoint on the line that prints `M$` and add
|
||||
`M$` as a watch. Run the program and select a planet. At the stop, the watch
|
||||
contains its greeting and the screen still shows the menu. Step once to print
|
||||
the greeting. Continue to switch back to the usual text colors and return to BASIC.
|
||||
|
||||
The editor checks its source against the tokenized program in CoCo memory.
|
||||
Editing the source detaches the live mapping immediately and hides the execution
|
||||
highlight; pending breakpoint numbers apply on the next Run. A core comparison
|
||||
of the line chain, command dispatcher and memory mapping also detaches when the
|
||||
guest program or relevant memory changes. Continue rechecks the source and stop
|
||||
on the emulation queue before resuming. It refuses a stale stop. Explicit CPU
|
||||
stepping, PC changes, binary loading, resets and configuration replacement also
|
||||
end the BASIC debugging attachment. Manual machine-code breakpoints are kept
|
||||
separately.
|
||||
|
||||
Breakpoint selections last for the current editor document/session. New, Open
|
||||
and Read from CoCo clear them; Renumber clears them after changing the labels so
|
||||
old breakpoint numbers cannot silently target different code. Source files and
|
||||
recovery drafts do not currently store breakpoints. Closing the workspace window
|
||||
alone preserves its model and the paused CoCo session.
|
||||
|
||||
The hook uses the shared command dispatcher at `$ADC6`, with the current line at
|
||||
`$0068` and input pointer at `$00A6`. The input pointer must identify the line's
|
||||
first token. The Color, Extended and Disk BASIC dispatch loops have different
|
||||
entry paths but converge here. The implementation validates the qualified
|
||||
bundled CoCo 3 interpreter and dispatcher before enabling this behavior; it does
|
||||
not patch ROM or program bytes. The primary references are the command dispatch
|
||||
sections in [Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf),
|
||||
[Extended BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/extended-basic-unravelled.pdf)
|
||||
and [Disk BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/disk-basic-unravelled.pdf).
|
||||
|
||||
## Statement stepping and Step Over
|
||||
|
||||
At a BASIC breakpoint, **Step Into BASIC statement** (the down-arrow toolbar
|
||||
button) executes until the next statement the interpreter dispatches. A yellow
|
||||
highlight identifies its source line; a stronger orange highlight identifies
|
||||
its next token, including separate statements on the same line. The mapping is
|
||||
emitted by the tokenizer from the original editor source, preserving spelling,
|
||||
spacing, CRLF and source order. Highlighting never edits the document or moves
|
||||
the insertion point.
|
||||
|
||||
**Step Over BASIC subroutine** (the bent-arrow button) follows a `GOSUB` through
|
||||
its `RETURN`, including recursion and `ON … GOSUB`. Nested `FOR/NEXT` loops are
|
||||
not mistaken for subroutine calls. An explicit breakpoint inside the call still
|
||||
wins. On an ordinary statement, Step Over stops at the next statement just like
|
||||
Step Into. `IF` can dispatch an inline THEN/ELSE command as a separate stop;
|
||||
expressions themselves are not individually stepped. REM, DATA, skipped branches
|
||||
and empty separators follow the interpreter's behavior.
|
||||
|
||||
The editor is temporarily read-only while a step is running. **Pause BASIC step**
|
||||
appears during a wait, and the main emulator Pause action also cancels stepping.
|
||||
A step pauses automatically after 600 emulated video frames (about ten seconds),
|
||||
so a nonreturning subroutine or INPUT wait cannot leave an unbounded debugger
|
||||
operation. Continue resumes the existing execution without reloading. After
|
||||
cancellation or the limit, stepping becomes available again at the next BASIC
|
||||
breakpoint; no statement highlight is invented for a mid-statement pause.
|
||||
Use Show CoCo and Continue to supply input normally.
|
||||
|
||||
END, STOP, and runtime errors that return to BASIC finish a step at the OK prompt.
|
||||
The emulator remains paused; Continue lets the prompt accept commands or a new
|
||||
editor transfer. Program,
|
||||
interpreter or mapping changes cancel an active step and detach its source map.
|
||||
Changes to the editor after a stop also detach debugging as described above.
|
||||
|
||||
Step Over observes the qualified interpreter's GOSUB frame push at `$AE9D` and
|
||||
RETURN pop at `$AEDA`, recording and matching frame addresses instead of guessing
|
||||
from the stack pointer alone. The input-loop entry at `$AC7C` identifies a return
|
||||
to the prompt. These routines and the dispatcher are guarded against changes;
|
||||
CoCo 3's normal boot patch to the preceding OK-print routine is outside the guard.
|
||||
The [Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf)
|
||||
GO, RETURN and command-dispatch listings provide the interpreter reference.
|
||||
|
||||
## Step Out and runtime errors
|
||||
|
||||
**Step Out** runs the current `GOSUB` through its `RETURN`, stopping before the
|
||||
next mapped statement in the caller. It handles nested and recursive calls and
|
||||
skips intervening `FOR` frames. Explicit breakpoints still take precedence. The
|
||||
button is unavailable at top level, in an unrecognized stack, or after a
|
||||
mid-statement pause. Pause and the same 600-frame execution bound apply.
|
||||
|
||||
The caller walk starts at the interpreter's current dispatch return address,
|
||||
verifies its BSR/JSR instruction, and walks typed 18-byte FOR and five-byte GOSUB
|
||||
frames within BASIC's RAM bounds. It verifies the saved caller line/pointer
|
||||
against the attached source, then matches the exact frame at `$AEDA`. A changed
|
||||
caller frame cancels Step Out. Different DOS command-loop return addresses are
|
||||
accepted only when their call into the recognized dispatcher is verified.
|
||||
|
||||
Run now attaches error observation even without a source breakpoint. It still
|
||||
runs immediately and never adds a default breakpoint. Unhandled errors finish
|
||||
the ROM's normal reporting and file cleanup, then pause before keyboard input
|
||||
at the OK prompt. A banner shows the ROM's actual two-character error code and
|
||||
source line; **Show Line** selects that numbered source row without modifying it.
|
||||
This is line-level navigation, not a claim to identify the exact faulty
|
||||
expression. Values that remain in BASIC can be inspected at this stop.
|
||||
|
||||
Choose **Continue** to return to the normal prompt before editing and running a
|
||||
corrected program. If source edits have already detached debugging, resume the
|
||||
CoCo from the main window. Continue does not resume the aborted BASIC program.
|
||||
A new transfer, changed source, reset, or detached source mapping clears the old
|
||||
error. The last matching error can remain visible after returning to the prompt.
|
||||
|
||||
`ON ERR GOTO` remains under the ROM's control. Handled errors do not produce the
|
||||
unhandled-error banner or an automatic stop; a breakpoint in the handler still
|
||||
works. Error observation uses the shared `$AC65` reporting path after the error
|
||||
code has been printed, rather than intercepting every error before the guest
|
||||
can handle it. The error routines are guarded alongside command dispatch.
|
||||
|
||||
The additional interpreter references are the
|
||||
[Disk BASIC Unravelled command-loop and error-driver listings](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/disk-basic-unravelled.pdf)
|
||||
and [Super Extended BASIC Unravelled error-trap listings](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/super-extended-basic-unravelled.pdf).
|
||||
|
||||
## Variables and watches
|
||||
|
||||
The collapsible **Variables and Watches** panel reads the stopped BASIC program's
|
||||
numeric and string variables, DIM arrays, and DEF FN entries. It refreshes at a
|
||||
BASIC breakpoint, after statement stepping, and at the stepping stop before the
|
||||
OK prompt. **Refresh BASIC variables** also rereads a safe stop. Continuing,
|
||||
editing the source, resetting or detaching debugging clears the displayed values.
|
||||
An arbitrary CPU pause in the middle of INPUT, expression evaluation or string
|
||||
collection is not a safe BASIC inspection stop.
|
||||
|
||||
Arrays expand into pages of 32 elements. Their displayed bounds are inclusive
|
||||
and begin at zero; multidimensional indices use the source's order. Strings
|
||||
preserve case and quote their contents, with nonprinting bytes escaped as
|
||||
`\xHH`. Numbers decode the interpreter's five-byte floating-point representation.
|
||||
DEF FN entries are identified but never evaluated.
|
||||
|
||||
**Watches** accepts named variables and array elements with literal, nonnegative
|
||||
subscripts, such as `A`, `NAME$`, or `M(1,2)`. BASIC identifies names by their first
|
||||
two characters, so `NAME$` appears as `NA$`. Unknown names say **Not assigned**;
|
||||
unknown arrays say **Not dimensioned**. Wrong subscript counts and out-of-range
|
||||
indices are reported separately. Watches do not evaluate expressions, functions,
|
||||
PEEK or assignments and never create a guest variable. Up to 128 watch names are
|
||||
remembered with the local workspace recovery draft, independently of breakpoints.
|
||||
|
||||
Inspection copies normal BASIC RAM on the emulation queue without executing
|
||||
instructions, modifying memory or accessing device registers. It validates the
|
||||
qualified interpreter, source/program identity, MMU mapping, variable-table
|
||||
bounds and array descriptors. Strings whose descriptors point outside ordinary
|
||||
BASIC RAM are shown as unavailable. A malformed table returns an inspection
|
||||
error instead of guessed values. Asynchronous results are discarded after the
|
||||
source, machine generation or stopped execution position changes. This is
|
||||
read-only inspection; editing values and general expression watches are not
|
||||
implemented.
|
||||
|
||||
## Validation approach
|
||||
|
||||
`BASICBridgeTests` runs against optional, ignored
|
||||
`platforms/macos/LocalResources/ROMs/coco3.rom` and `disk11.rom`. Tests explicitly
|
||||
skip the ROM integrations if those files are absent; no proprietary ROM bytes are
|
||||
checked into the repository. Both guest processors are exercised sequentially
|
||||
because the retained emulator core is process-global.
|
||||
|
||||
The key independent oracle enters an authored fixture through the actual ROM's
|
||||
keyboard/tokenizer, captures the tokenized RAM program, then compares it with a
|
||||
directly loaded version of the same source. The fixture includes strings,
|
||||
`DATA`, `REM`, apostrophe remarks, `?`, function tokens, `ELSE`, disk commands and
|
||||
CoCo 3 commands. Reading that program and reloading the returned source must
|
||||
produce the same bytes. Other checks cover direct execution without queued
|
||||
keystrokes, preserved media and machine generation, rejected source preserving
|
||||
the previous program, and unsupported machines rejecting direct writes. Export
|
||||
checks cover deterministic DSK/CAS output, paused memory/register preservation,
|
||||
running-program preservation, invalid source/names and unchanged media and
|
||||
machine generation. Separate core checks load the exported files through the
|
||||
actual ROM's `LOAD` and `CLOAD`, including programs crossing disk granules and
|
||||
cassette data blocks; cassette checks use the normal transport rather than fast
|
||||
loading.
|
||||
|
||||
The BASIC command references maintained by Color Computer Archive are useful
|
||||
background for command vocabulary and usage:
|
||||
[Color BASIC, Extended BASIC and Disk BASIC references](https://colorcomputerarchive.com/repo/Documents/BASIC%20Commands/).
|
||||
Interpreter storage and execution behavior are documented in
|
||||
[Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf).
|
||||
The bundled Quick Reference provides original local
|
||||
explanations and examples. These source links do not imply that the external
|
||||
manuals are bundled with the workspace.
|
||||
|
||||
### Initial validation — November 4, 2026
|
||||
|
||||
The 13 focused native tests passed on both Apple Silicon and x86_64 under
|
||||
Rosetta: five bridge integrations, six editor/language/recovery checks and two
|
||||
pure core token/validation tests, exercising the final normal-RUN-handler path.
|
||||
The complete 63-check standalone core suite also passed. There were no failures or
|
||||
skips. Each real-ROM bridge case exercised both the 6809 and 6309. The original interpreter's typed
|
||||
program and the directly installed program matched byte for byte; canonical
|
||||
read-back reloaded to the same representation. Paused Load preserved cycle count,
|
||||
and immediate Read followed by Run executed successfully. Execution printed the
|
||||
expected result with no queued paste; disk/tape assignments and machine generation
|
||||
were unchanged. Invalid/oversized source, active loops, INPUT waits and unsupported
|
||||
machines were rejected without replacing the previous program.
|
||||
|
||||
These original checks use authored isolated machine instances and predate the
|
||||
line-breakpoint feature. They do not qualify other ROM revisions.
|
||||
|
||||
### BASIC line-debugging validation — November 4, 2026
|
||||
|
||||
All 40 targeted tests passed on Apple Silicon and x86_64 under Rosetta: ten
|
||||
BASIC bridge integrations, 19 workspace tests and 11 existing core/native debugger
|
||||
checks. The BASIC breakpoint cases run on both emulated processors. They verify
|
||||
stopping before execution, repeated loop stops, Continue without a reset,
|
||||
subroutine return state and variables, colon statements, coexistence with manual
|
||||
CPU breakpoints, rejection of mismatched source and invalid line numbers, and
|
||||
detachment after program-memory edits, PC changes and reset.
|
||||
|
||||
The isolated native UI check verifies both gutter clicks and the accessible
|
||||
insertion-point toggle, Run to a selected line, Continue, unchanged source and
|
||||
machine generation, disabling Continue after editing, and clearing breakpoints.
|
||||
The captured window was visually reviewed for gutter alignment and stopped-line
|
||||
highlighting. That checkpoint covered line-entry debugging; the later sections record
|
||||
statement stepping and variable inspection. No default breakpoint is installed.
|
||||
|
||||
### Statement stepping validation — November 5, 2026
|
||||
|
||||
All 50 targeted tests passed on Apple Silicon and x86_64/Rosetta (Apple Silicon
|
||||
in a 46-test pass plus four final guard/mapping checks): 17 BASIC bridge tests,
|
||||
20 workspace tests, two tokenization/export core checks and 11 existing debugger
|
||||
regressions. The new bridge cases exercise both emulated processors. Coverage
|
||||
includes same-line statements, source order/CRLF and keyword case, FOR/NEXT,
|
||||
IF/ELSE, nested and recursive GOSUB, ON GOSUB, explicit breakpoint precedence,
|
||||
return to the OK prompt after END and a runtime error, an INPUT wait canceled
|
||||
without clearing its program, and the 600-frame bound on a nonreturning call.
|
||||
Self-modifying BASIC detaches and stops rather than highlighting stale source.
|
||||
The editor test verifies that moving the token highlight within one line leaves
|
||||
source text and insertion point unchanged.
|
||||
|
||||
The isolated native check passed Step Into, Step Over, same-line token rendering,
|
||||
Continue after the OK-prompt stop, and pausing an INPUT wait. The existing gutter,
|
||||
Continue and stale-source UI regression also passed. The final window capture was
|
||||
visually reviewed; only the app window is retained here. Xcode emitted internal
|
||||
QoS diagnostics during automated editor lookup; those did not fail the tests,
|
||||
and this validation does not establish their underlying cause.
|
||||
|
||||
## Variables and watches validation — November 5, 2026
|
||||
|
||||
All 53 targeted tests passed on Apple Silicon and Intel under Rosetta: 19 BASIC
|
||||
bridge integrations, 21 workspace checks, two pure core checks and 11 debugger
|
||||
regressions. Each BASIC bridge test exercises both emulated CPUs. Real-ROM
|
||||
fixtures independently create numbers (including negative, fractional, large
|
||||
and small values), mixed-case/empty/binary strings, numeric and string arrays,
|
||||
and DEF FN entries. The inspector recovers their values and source-order array
|
||||
indices without changing RAM, cycle counts, program revision or media. Tests
|
||||
also reject stale source, running/mid-statement inspection and damaged tables.
|
||||
Synthetic RAM checks cover malformed array ranks, lengths, offsets, variable
|
||||
pointers and string descriptors pointing at device addresses. Watch checks cover
|
||||
canonical names, bounds, unknown variables, rejected expressions and recovery.
|
||||
|
||||
The final native checks passed array expansion, adding scalar/string/array
|
||||
watches, value refresh after stepping, clearing values on Continue, and the
|
||||
existing Step Into/Step Over/INPUT-cancellation workflow. The final asynchronous
|
||||
stop guard and layout built for both architectures; all 21 workspace tests were
|
||||
rerun successfully on Apple Silicon. A small disclosure control was replaced by
|
||||
a full-row accessible array button. The breakpoint ruler now draws and clips its
|
||||
own separator within the editor, fixing the vertical line previously extending
|
||||
through the toolbar and footer. Window-only screenshots were visually reviewed.
|
||||
Xcode still reports its internal QoS warning during UI automation; this pass does
|
||||
not identify or claim to resolve that separate warning.
|
||||
|
||||
## Step Out, runtime-error and preset validation — November 5, 2026
|
||||
|
||||
The added real-ROM bridge tests exercise both emulated processors and cover
|
||||
nested/recursive returns, FOR frames, explicit-breakpoint precedence, stale
|
||||
source and top-level refusal, division-by-zero, syntax, DATA, type and disk-file
|
||||
errors, normal ROM error output, and preserved `ON ERR GOTO` behavior.
|
||||
|
||||
An isolated test creates the actual Disk BASIC, Hard Drive BASIC and CoCo SDC
|
||||
preset definitions from private ROMs and authored starter media. Each preset runs
|
||||
`DIR` against its own mounted storage, transfers and reads back source, stops at
|
||||
a breakpoint, inspects a scalar and array, steps into/out of a subroutine, and
|
||||
reports an unhandled error. Optional private `rgbdos.rom` and `sdcdos.rom` are
|
||||
required for that case. No personal working media are opened or modified.
|
||||
|
||||
The native UI test checks Step Out availability, caller return, exact source-row
|
||||
selection, unchanged source, correcting/re-running after an error, and compact
|
||||
window controls. The resize regression verifies a real size change and checks
|
||||
that both the header and full preset guidance stay within the window. The
|
||||
inspector reduces its visible rows in shorter windows while retaining its own
|
||||
scrolling. Representative window captures:
|
||||
|
||||
- Returned to caller
|
||||
|
||||
- Runtime error source navigation
|
||||
|
||||
Validation for this stage: 57 selected BASIC/core/debugger tests passed on Apple
|
||||
Silicon and the same 57 passed on Intel through Rosetta, with no skips. The native
|
||||
Step Out/error-navigation workflow passed in the isolated app. Both build
|
||||
architectures compiled. Xcode's App Intents metadata notice and internal test
|
||||
service/QoS diagnostics are not claimed resolved by this change.
|
||||
Reference in new issue
Block a user