Guide · Chapter 14 of 14

Inspect, test, and compare

Read generated artifacts and verify execution on the host 6510 runner and VICE.

Jump to a section

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 entryHow to read it
memory_regionsReserved C64 and REU address ranges with bank visibility.
memory_placementsLoad and run ranges for placed code or data. direct has matching addresses. startup_copy has two ranges.
sectionsCode, writable storage, and read-only data with ownership, addresses, and symbols.
zero_pageWhen 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.

Open the complete source

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.

Policy added to the second source
pub const zeropage_options = .{
    .zero_page = .{ .profile = .kernal, .allocation = .scratch },
};
PolicyPRG bytesHost CPU cyclesIntercepted calls
Default4681,4839
KERNAL with scratch allocation5231,5869

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.

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.