Read the generated program
Use the PRG header for load address, the assembly for actual instructions, the VICE label file for monitor breakpoints, and the map for ownership and addresses. Compare load and run addresses for copied placements. Check the zero-page policy section for actual claims. For DLLs, inspect the relocation simulation beside the binary and disk payload.
The compiler emits runtime helpers on demand and retains exported entry points, module interfaces, and other required roots. Inspect a representative build before drawing size or cycle conclusions. Optimizer contracts
Read a real map before changing the memory plan
Use the placement demo to connect declarations to the final image. The map's image object shows a load address of $0801 and an entry of $1000. Those addresses differ because the BASIC stub is loaded first and then starts the program at the declared entry.
| Map entry | How to read it |
|---|---|
memory_regions | Reserved C64 and REU address ranges with bank visibility. |
memory_placements | Load and run ranges for placed code or data. direct has matching addresses. startup_copy has two ranges. |
sections | Code, writable storage, and read-only data with ownership, addresses, and symbols. |
zero_page | When configured, shows the allocation policy, actual claims, and restoration scope. |
For hidden, the run address is $e000. The load address is inside the PRG and can move as code changes. Read the current map for that value. If a placement grows, compare its recorded size to its named region. The compile gate rejects an assembled image that crosses a configured ceiling or claim.
Raw entry fixture · Startup-copy fixture · Map fields and region ownership
Prove target behavior
zp64c compile emits a PRG plus .asm, .labels, and .zpmap.json sidecars. Use the assembly to see the generated 6502 instructions, VICE labels to set breakpoints, and the map to inspect section ownership. zp64c asm emits assembly without running 64tass.
The unit suite checks the compiler and runner. The Peddle host suite executes the generated machine code and includes test6502 assertions. The end-to-end suite compiles the demos and uses Bash, Perl, and c1541 to check build and disk artifacts. Full VICE automation uses an external harness. Testing and VICE setup · CLI and sidecars
Pure language assertions belong in the host runner. Hardware smoke tests cover screen, KERNAL, banking, and REU. The section-marker gate checks that ownership markers are byte-neutral. For optimization changes, compare generated size and behavior using the same workload and machine assumptions. Testing and measurement workflow
Measure size and speed with a fixed workload
Start by checking that both programs produce the same behavior. Then record the generated PRG size and compare the assembly for the paths that run. A PRG byte count includes the two-byte load header. Resident RAM, configured stack, zero-page claims, and REU allocations are separate costs. A shorter file may still reserve more memory while running.
Use the repeated-greeting sources to compare output strategies. The console example uses built-in output. The buffered variants keep screen state and do bulk writes. A fair comparison must keep the visible work and stopping condition comparable. In a hot loop, check whether a source change removes repeated DMA setup, copies, or bank switches. Record the behavior and the cost that changed.
Console greeting · Buffered greeting · Baseline and measurement workflow · Optimization contracts
Measure what a zero-page policy costs
Use the short-scalar-call workload to isolate one change. The second source adds the policy below. Both use the same nested calls, argument values, and assertions, including a pointer write that checks evaluation order. The host runner checks the same results before emitting metrics for each successful run.
pub const zeropage_options = .{
.zero_page = .{ .profile = .kernal, .allocation = .scratch },
};
| Policy | PRG bytes | Host CPU cycles | Intercepted calls |
|---|---|---|---|
| Default | 468 | 1,483 | 9 |
| KERNAL with scratch allocation | 523 | 1,586 | 9 |
In this preview build the scratch policy adds 55 file bytes and 103 measured cycles. The fixture measures through its pass hook, so it includes entry work and stops before normal-return cleanup. For a tiny workload, the cost of initializing and managing borrowed cells can outweigh cheaper accesses. Read the map and emitted instructions, then measure a workload with the call frequency you expect in your program. Use the lifecycle runner if the cost of cleanup is part of the question.
Reproduce the two host measurements
These counts cover instructions stepped in the host 6510 fixture. Intercepted hooks, VIC-II stalls, and physical drive or REU timing are outside the measurement. Default-policy workload · Same workload with scratch allocation · Metric columns and lifecycle timing
How ZeroPage fits among C64 toolchains
Memory regions and overlays have precedents. Oscar64 documents source pragmas for sections and regions and a linker-generated overlay flow. cc65's ld65 documents memory and segment configuration with separate load and run addresses. Oscar64 manual · ld65 guide
ZeroPage's combination is a Zig-shaped target subset with source-declared ownership shared by the PRG, heaps, zero page, placements, and DLL loader. Typed far views expose explicit copies to and from C64 RAM. The DLL loader combines named REU slots, typed exports, relocations, window activation, and explicit ownership in one model.