Tutorial · Chapter 1 of 23

Build and read a first PRG

Start with one observable result, then follow the source to the program that runs on the C64.

Jump to a section

Read the program before installing tools

Three lines do the work. Clear the console, print a greeting, and set the border color. c64 is the built-in module that supplies those operations. The formatter accepts an argument tuple. Here the empty tuple means the message contains no values to insert.

hello.zp64
const c64 = @import("c64");

export fn main() void {
    c64.console.clear();
    c64.console.print("HELLO FROM ZEROPAGE\n", .{});
    c64.vic.border = 5;
}

The entry function is main. It returns void because its effect is visible on the machine. ZeroPage lowers the program to 6502 assembly. It includes console support because the program prints text, and leaves out features such as REU DMA and DLL loading because this source never uses them.

Run it and change one thing

Use the pinned tools from Setup. When the program runs, expect HELLO FROM ZEROPAGE and a green border. Change the border value from 5 to 2, rebuild, and check that the text stays the same while the border turns red.

Open the complete source

The default PRG starts at $0801 and carries a BASIC line that enters the generated machine code. That is why the disk and emulator can start it with the normal BASIC run flow. A raw image needs an explicit entry supplied by the host.

Recognize the first three failure points

What you seeWhere to look
zp64c is missingBuild the host compiler. Setup gives the expected zig-out/bin path.
The compiler cannot find 64tassCheck the assembler path with zp64c tools.
The emulator runs an older greetingCheck the path supplied to VICE and the build output path. Rebuild the same file you boot.

Once you can change a visible result, choose the byte and word types that will hold the survey's state.