Chapter 9 of 10
Find a workbench or a reference
There are three ways to write the Earth or Mars program. In BASIC you can read the question in a numbered line. In C you can find the function that asks it. In assembly you can see the machine instruction that handles a key. All three editors open from Develop. Each sends work to the same CoCo you see in the emulator window. Save a guest program you want to keep before loading another.
Choose an editor
- BASIC Development… opens numbered BASIC source. Use it to try a short program, bring a listing back from the guest, or stop before a particular statement.
- C Development… opens a project folder. Choose this when your work includes C source, headers, libraries or data files that must be built together. A Makefile gives the build tools their instructions.
- Assembly Development… opens assembly source or a project folder. Choose this when you want to work directly with processor instructions, registers and addresses. A single source file is enough to get started.
Build in C or Assemble in assembly creates machine code; Run starts the program in the guest. In BASIC the CoCo already contains the language interpreter, so the editor can load and run numbered lines directly. In all three workspaces, editing a file on the Mac and interacting with the running program use different windows. Choose Input → Focus CoCo Display to answer a guest prompt.
Find a word in the file you are editing
In BASIC, C or Assembly Development, press ⌘F or click the editor’s Find in File magnifying glass. Type the text you want. ⌘G selects the next occurrence; ⇧⌘G goes back. Use Match Case when capitals matter. To search for something you can already see, select it in the source and press ⌘E.
Suppose you want to change a greeting in a personal copy of Earth or Mars. Press ⌥⌘F, find the old wording and enter your replacement. Replace changes the selected occurrence. Replace All in File changes every match in this file, including matches in comments and quoted text. Check the match count first. One Undo reverses the whole Replace All. Escape returns you to the source.
Finding works in an unsaved source buffer and in a read-only C header. Replacement requires an editable file. The change belongs to the Mac source. To see a new greeting on the CoCo, run the edited program. In C, Find in Project is a separate search across files. Press ⇧⌘F or use the magnifying-glass tab immediately to the right of the folder at the top of the left sidebar.
Bring a BASIC program into the editor
If you have been typing a program at the green screen, return to the BASIC prompt and choose Read from CoCo. You now have its listing in the editor. Click Save to keep a Mac source file. The listing contains the program, while variables belong to the current run. In the other direction, Load into CoCo transfers the editor listing and leaves BASIC ready; Run transfers it and starts it. Direct loading is supported at the BASIC prompt in Disk BASIC, Hard Drive BASIC and CoCo SDC. If a guest program is still running, use CoCo Break before replacing it.
Use New for a starter or Open… for a saved source file. Tab accepts a faint suggested keyword ending. Under Editing, Go to Line… finds a numbered line, Check Source can take you to a problem, and Renumber… updates the numbers and recognized references. Use the … menu beside Save to make a copy or export a disk or cassette. The export dialog shows which command to type in the guest. Disk export can also install a DOS bootloader so you can start that disk by typing DOS. Put VOYAGE on a disk follows a program from source into portable media.
A breakpoint is a request to pause before a place in the program. Set one beside a numbered line, then Run. Continue lets BASIC run to its next stop. Step Into advances by a BASIC statement and follows a subroutine; Step Over lets the subroutine finish; Step Out returns to its caller. At a BASIC stop, inspect Variables or add a name under Watches. Their values belong to that point in the program. Stop before the subtraction shows how to tell whether a line has done its work yet.
Follow a C build from source to the guest
Choose New for a project or Open for an existing project directory. The simple starter asks Earth or Mars. Hello Disk is the example to open when you want to read data from disk. Select source files in the project navigator. Use Go to Definition on a name, Back to return, and Find in Project to search across files. Completion suggests identifiers; parameter hints show the arguments a function expects. Headers from the installed libraries can be read in the editor.
Save All writes project edits. Select Debug when you want source stops and named variables. Click Build, read the first error under Issues if the build fails, then choose Run or Launch Disk, according to the project. The menu beside Build also has Rebuild, Clean, Build Disk and Show Build Products. Build History helps recover the output from an earlier attempt. If a source file has changed outside the editor, compare or preserve your draft before using Reload File from Disk; Save Selected Copy… gives it a different destination.
Project Settings divides the decisions into five groups:
- Build chooses Generate from settings or Custom Makefile. Generated projects expose the binary name, addresses, stack and release optimization. For an existing Makefile, leave the build target empty to use Make’s default goal, or specify one defined by the author. Check artifact locations, clean target and parallel jobs here. Review a Makefile before running it on your Mac.
- Sources specifies project modules, include directories, defines and build flags. An include directory is where the compiler looks for a header named by the source.
- Libraries selects bundled libraries or builds project-local library subprojects. A project can depend on its own copy of a library. Check its version and build settings before substituting another copy.
- Resources builds data the program needs from input files and generation rules. A missing data file may let the C code compile yet leave its disk unusable.
- Disk & Run specifies disk contents, any DOS bootloader, and the launch method. Quickload executable starts a binary directly; Mount disk in FD0 supplies a disk and can type the chosen startup commands. Use the latter when the program needs files on that disk. Review the preview before replacing an existing Makefile with a generated one.
At a C source breakpoint, step through C source or select a row in Call Stack. Each row represents one active function call. Select its frame to see its source, then Variables or Watches to inspect the values available in that call. Expand a structure, array or pointer to see its contents. A recursive function can have several rows, each with different locals. Execution resumes from the current stop even while you are looking at a caller. Show Current Frame returns from a selected caller to the active stop; the screenshot above shows an opened project, rather than a paused debug session.
For a guided first session, run the single-key C starter. For a two-file mystery, stop just after Hello Disk opens its data file.
An inherited Makefile can build a correct program without retaining enough information for C debugging. Preserve the matching object files, compiler intermediate files, listing and linker map in its Debug recipe. The debugger can then distinguish an executable function entry from a mapped C statement. An unavailable local is a limit of the retained evidence, not a value of zero. See Keep custom-Make debug evidence.
Stop at the first assembly instruction
Use File → Open Source… for a single file, or Open Project Folder… for a larger program. Select the Target processor. Both machines understand the 6809 instruction set; programs using 6309-only instructions need the Hitachi processor in the running machine as well. Assemble checks the source and creates the binary. Read Build details for the listing and diagnostics, or select a diagnostic to go to its location.
Choose Debug from Entry to stop at the first instruction, or Run to start without that initial stop. Set Stop on an instruction you want to examine, then Continue to reach it. Step lets the machine execute an instruction. An instruction may change one register without producing anything visible on the CoCo screen. To see the moment it happens, open a three-instruction program and follow A.
Project Settings… explains how to edit the project’s settings file. It names the main source and, for linked projects, any additional modules and linker script. A custom Makefile project names its recipe, target and output binary. The app asks before executing that recipe. The native assembler-and-linker route can verify source stops against the assembled bytes; use the machine debugger to inspect the output of a custom recipe.
Export Binary… saves the binary for quickloading later. Export Disk Image… puts the named binary on a disk and shows the full command to load and execute it. Selecting Install DOS bootloader adds DOS as a second way to start it. This workflow targets a BASIC machine; an OS-9 executable uses a different format.
Look inside the machine
To try the machine debugger with a known result, catch a store one instruction before RAM changes.
Debug → Show Debugger examines the shared machine, even if the program has no source file. Pause Execution stops it where it is. Step Instruction advances one CPU instruction. A BASIC line or C statement can require many instructions. Choose the language workspace when you want to follow the listing you wrote.
- Inspector answers “Where is the CPU now?” Follow the program counter (PC) in disassembly, or open an assembler listing in Source view. Inspect registers or set an address breakpoint. In Memory, compare the CPU’s mapped address with physical RAM. The MMU view shows how the machine maps blocks of RAM into the CPU's address space. Navigating is safe; Set PC changes the next instruction, and editing a byte alters the machine.
- Memory Tools answers “What is in this range?” Select an address space and range to disassemble it or export the bytes. OS-9 interpretation can identify calls and module headers when examining OS-9 code.
- Graphics Preview answers “What would these bytes look like as pixels?” Start with the current video page. Switch to a chosen address, select an address space and graphics mode, then inspect a pixel and jump to its byte. Zoom changes the preview alone. The BASIC graphics chapter gives the two-page drawing a purpose.
- Trace answers “What happened just before this instruction?” Set bounds or triggers, start a new trace and reproduce the event. Stop recording, select a sample and compare its before/after registers. Markers, optional screen and scheduler events, and export help you compare two points in time.
Which debugger controls change the machine?
Go, Follow PC, Show in Memory and the MMU's RAM backing buttons change what you inspect. The MMU maps the CPU's address space in 8 KB windows. Its two task columns show programmed banks. Effective read tells you what currently supplies the bytes the CPU reads. A ROM overlay can hide RAM at the same CPU address. Select the RAM backing address to see that underlying memory.
A breakpoint's address is a logical CPU address in this session. Uncheck its Enabled box to pass it without losing its location. Set PC Here redirects execution when the machine resumes. Write in the memory inspector edits a RAM byte. Use a practice session for either change.
In Memory Tools, Start and End are hexadecimal and the ending byte is included. For physical RAM, the assumed CPU origin determines the targets shown for relative branches. Disassemble previews up to 128 rows. Export Binary… writes the whole selected range as raw bytes. A disk BASIC loadable binary also needs its load and execution information; for that use the assembly workspace's export.
For a graphics byte, click a point in the preview or enter its X and Y in Pixel Inspector. Show Byte in Memory opens the corresponding location. Highlight step changes helps locate a changed pixel after stepping.
In Trace, set the maximum sample count and optional start and stop addresses before choosing Start New. This replaces the earlier capture. Starting or stopping the trace leaves the CPU's run state alone. During review, use Go for a sample number and Mark A and Mark B for two points of interest. Choose Export CSV… for the selected sample range before clearing it or starting another capture.
Choose the right kind of help
For a BASIC command or an assembly mnemonic, choose the corresponding Quick Reference under Develop or Help. Search the name, check its syntax and the supported BASIC environment or processor, then open the example in its own editor document. Examples are useful even if your main project is already open.
For a worked lesson to read alongside the machine, use Help → Manual Library…. For a particular game’s controls or an application’s reference card, use the Software Library’s manual or readme. Help → Keyboard & Shortcuts… covers Mac and CoCo keys. About VCC Plus and Licenses & Notices… identify the people and projects behind the emulator, its artwork and the tools you build with.
Work with an assistant
Develop → Connect to ChatGPT… opens the BASIC connection controls. For the same BASIC document, use More file actions → Local Assistant Access…. In C Development choose Assistant… for the open project; in Assembly Development use File → Local Assistant Access…. These controls share the intended document or project. Choose a read-only connection when you want advice. A review-and-run connection permits the actions named in its local consent window; inspect proposed source changes and any request to execute a custom Make recipe before approving them. The connection file is a private access credential. Keep it out of your source repository.
An existing connection keeps its original scope and advertised tools after an app update. If a newly supported feature is absent, inspect the connection's capabilities and export an appropriate new connection from the workspace. Refreshing an assistant client's tool list and approving a larger project scope are separate actions. The connection field guide explains recovery and permission choices.
For C projects edited outside VCC Plus, an assistant can request a project refresh. Clean shared tabs can update without discarding drafts. New files, changed build recipes or a wider support scope can open a native review listing the concrete changes. Approval adopts those inputs; it does not itself run Make or launch the CoCo. Resolve a conflicting unsaved draft locally before asking the assistant to rebuild.
With Allow Disposable Playtests, a C connection can use a separate, owned 512 KB guest, choose MC6809 or HD6309 when advertised, retain its writable test disk, and reopen that disk for save/reload checks. This leaves your shared emulator session separate. The assistant can inspect verified stops and globals, capture the actual framebuffer, and use declared graphics buffers when a project supplies the necessary build evidence. A C statement stop and a function-entry stop provide different debugging information.
Audio capture requires the corresponding permission in the exported connection. It records a bounded following interval of the disposable guest and advances that guest during recording; a picture capture does not advance it. The audio interval releases held keys, so a clip alone does not prove a continuously held movement test. Ask for the actual processor, build, input, images and audio timing in a test report. When a request budget is exhausted, the owned playtest can still be stopped and its disk retained. See Vibe Coding with ChatGPT for the complete workflow.