Appendix B
CMOC at the desk
Keep this page open when a familiar C expression behaves differently on the CoCo, or when the compiler succeeds and the guest still does something surprising.
Choose a size before a value
| CMOC type on this target | Bytes | Use in this book |
|---|---|---|
| unsigned char, also called byte in coco.h | 1 | A crate count or a status from the disk library, 0 through 255 |
| signed char | 1 | A small quantity that may be negative, −128 through 127 |
| int or short | 2 | Signed arithmetic from −32768 through 32767 |
| unsigned int, also called word in coco.h | 2 | Cargo totals, 0 through 65535 |
| long or unsigned long | 4 | Larger counters; signed and unsigned ranges differ |
| Pointer to guest memory | 2 | The address of a manifest row in the CoCo's current 64 KB address space |
A numeric 2, the character '2' and the two-byte string "2" have different jobs. The input loop compares a single character. The string contains the character followed by a zero byte. Printing a string asks the library to keep reading until that zero; passing it a single character value would supply the wrong kind of argument.
Choosing a wider destination cannot recover bits already lost in an earlier calculation. The cargo source explicitly casts the first factor to word before multiplication. Read the input types, the type of the calculation and the destination in that order.
Decide who owns the storage
Think about three addresses in Cargo Count. The manifest has program lifetime. A row pointer handed to mealsFor stays valid because that array continues to exist while the helper runs. The parameters and ordinary local variables of the helper belong to that invocation; their storage can be reused after it returns.
An array expression generally supplies a pointer to its first element when passed to a function. In main, sizeof can measure the actual manifest array. In a function receiving only a pointer, sizeof that pointer measures the address itself. Pass a count or capacity separately when the receiving routine needs one. Index zero is the first element; the element count is already one past the last valid index.
CMOC compiles for a much smaller stack than a Mac. Large temporary arrays and deep recursion compete for space. Look at the static 256-byte buffer in the disk reader for one way to reserve a buffer for the life of a program. Static storage is shared across calls; it would be the wrong place for two independent readers that must each keep their own in-progress data.
For storage whose size you choose while a program is running, reserve a static byte array and hand it to vcc_heap_init. Size the array alongside the executable, other globals and stack in the guest's 64 KiB address space. Adding more physical RAM to the emulated machine doesn't enlarge a C pointer. Grow a crew list to see how a program keeps its data when it runs out of space.
Know the language this compiler accepts
CMOC compiles a C-like language for the 6809. Its compiler implementation runs on the Mac. The program you write runs on the emulated processor. The same 6809 code can also run on the HD6309.
- Define structures and typedefs at file scope. Define the structure before accessing its members; a pointer can be declared earlier using an incomplete structure type.
- CMOC supports 32-bit long integers. Code assuming a 64-bit long or a long long needs adapting.
- On this CoCo target, the normal float backend uses routines in BASIC and its five-byte representation. Double is an alias for float in CMOC. Spelling double does not increase precision. An alternative MC6839 math backend needs a separately staged compatible library and its own format; check your toolchain edition before choosing it.
- A POSIX process, Unix path and host stdio stream imply an operating system. Planet Survey opens a stream on a named guest drive. Hello Disk uses decbfile to read the same disk format by sector. Look up the callable functions in Find a call.
If you want your program to run as an OS-9 command with standard output and a process exit status, follow Compile a small C program in NitrOS-9. It takes you from a C file on HD1 through the guest compiler, assembler and linker to a runnable module.
Set up a debuggable build
Use Generate from settings for a personal project whose rules the app maintains. Sources identifies C units and include directories. Libraries supplies the implementation archives and their order. Resources produces data. Disk & Run selects which files to put on a floppy and how to launch. Preview shows the Makefile before replacement. Keep a hand-authored Makefile in Custom Makefile mode.
The Hello Disk Makefile uses an origin of hexadecimal 2800 and a stack allowance of 2048 bytes. Debug selects -O0 and -fno-omit-frame-pointer. The intermediate listing and link map relate guest instructions back to source lines; a preserved frame gives the debugger a base for locals and callers. In Release, optimization can move or eliminate work. A variable that is unavailable in a stopped frame has no dependable value to display there.
In C Step, Into enters a mapped call, Over lets it finish and Out follows the return to the caller. Select a caller in Call Stack to see its source and frame-specific variables. To move execution, use a step or Continue. Selecting a different frame only changes where you look.
Keep custom-Make debug evidence
A successful custom recipe proves that its command completed and its declared products passed validation. C source debugging additionally needs evidence tying those exact executable bytes to your sources. Keep matching linked .o files, the linker .map, assembler .lst, and CMOC intermediate .s files. Use --intermediate when compiling and linking; a Debug compile normally uses -O0 -fno-omit-frame-pointer. Preserve those outputs with the build they describe. A map from a different build cannot establish a source stop.
For a program that packs, relocates or banks code after linking, its project must also declare matching runtime images and physical bank identities. The app does not treat a failed bank verification as an ordinary flat program. A verified function entry can be useful even when no C statement is mapped inside the function, but it does not establish a C stack frame or dependable locals. Check which kind of stop is available before planning a variable inspection.
When an assistant uses the C connection, its build receipt distinguishes verified source debugging, source-only evidence and unavailable evidence. It can inspect structured diagnostics and retrieve the retained build log in pages. A zero Make exit status can still accompany a later product-validation failure. Ask for the failing stage and first actual error rather than treating a clipped preview or an early warning as the whole result. The native Issues and Build History controls remain useful for your own review.
Refresh a project changed outside the editor
The project input inventory distinguishes source, headers, resources and approved support folders from generated products. A directory named generated can contain real source; do not assume its contents are disposable. Explicit resource/generated inputs and output directories should describe the project as its Makefile actually uses it. Merely touching an unchanged file does not create a different content revision.
An assistant's refresh request adopts clean files already covered by the connection. New files or changed recipes and support scope require the native review window. Check the paths and before/after changes there. Approval updates the authorized input set without executing it. If an external edit conflicts with an unsaved editor draft, preserve the draft and resolve the conflict locally; refresh does not silently discard or combine it. Work with an assistant explains connections and disposable tests.
Find a name and complete a call
Use Find in File (⌘F) for text in the selected document. Find in Project (⇧⌘F) searches across the project. When you want the declaration behind a name, put the caret on the identifier and choose Go to Definition. If the navigator offers several definitions, compare the filename, line and any Conditional candidate label. A custom Makefile or preprocessor condition can leave more than one plausible answer. Use Back to return to the place you started.
Choose Complete while typing an identifier. Use the arrow keys and Return to choose a name, Escape to dismiss it, or Undo to reverse the insertion. Once you type the opening parenthesis of a recognized call, the parameter hint shows the current argument. The hint helps you read the call while the compiler remains the check on the finished program. The editor’s Edit menu also offers indentation, comment toggling, and navigation to a matching bracket. These act on source text, even when the CoCo is paused elsewhere.
Recover source or an earlier build
When you return to an interrupted session, choose Recovery in C Development. Each entry gives the date and affected filenames. Choose Restore to bring the draft back into the editor, inspect it, then use Save All when you want to update the project. Export… keeps a separate copy, including when the original project has moved. A record marked Open in another app session can be exported while its owner still has it open.
For a failed or cancelled compilation, open Build History instead. The Source, Build and CoCo status fields describe three different things. Cancelling a build leaves the program already running in the CoCo in place. An older successful build can remain in history even though the edited project now needs rebuilding. Move Selected to Trash… applies to eligible build results. The workspace protects the latest runnable result, the launched result, and results with assigned media.
Decide what to repair
| Symptom | First place to look |
|---|---|
| Include file missing | Compare the exact filename and case with the installed header, then check the include directory. |
| Symbol unresolved at link | Check spelling, target, library choice and archive order. A declaration alone supplies no machine code. |
| No rule for a target | Check the existing Makefile. Leaving a custom project's build target blank uses Make's default goal. |
| Executable starts, words missing | Read the disk result and use DIR on the mounted floppy. Compare the guest filename with the one passed to the open call. |
| Breakpoint doesn't bind after editing | Save the sources, use a Debug build and launch the corresponding artifact. Set the stop on an executable statement. |
| Source changed outside the editor | Preserve an unsaved draft with Save Selected Copy… before choosing whether to reload the on-disk version. Use Build History to identify the earlier artifact. |
For the Mac controls and their recovery options, see the C workbench in the User's Handbook.