c65gm/README.md

c65gm

A high-level 6502 cross-compiler targeting the ACME Cross-Assembler. c65gm provides a more expressive language for writing 6502 assembly programs, with features like functions, type-checked variables, control flow structures, and compile-time optimizations.

What It Does

c65gm compiles high-level source code into ACME assembler syntax for the 6502 processor (Commodore 64 and similar platforms). It provides:

• Type system: BYTE and WORD variables with scope resolution
• Functions: Named functions with parameters and call graph analysis
• Control flow: IF/ENDIF, WHILE/WEND, FOR loops, SWITCH/CASE
• Memory operations: PEEK/POKE/PEEKW/POKEW with zero-page optimization. Access registers as variables.
• Operators: Arithmetic (ADD, SUB), bitwise (AND, OR, XOR)
• Preprocessor: File inclusion, macros, conditional compilation, Starlark scripting
• Standard library: C64 screen/kernal routines, memory management, string handling, graphics (Koala), FAT16 filesystem, and more (accessed via #include <file>, path set by C65LIBPATH environment variable)
• Optimizations: Constant folding, self-assignment detection
• Safety features: Compile-time detection of overlapping absolute addresses in function call chains

Requirements

• Go: Version 1.25.1 or higher (tested with 1.25.5)
• Acme: Tested with release 0.97 ("Zem")

The project uses Go modules with these dependencies:

• github.com/armon/go-radix - Prefix tree for command lookup
• go.starlark.net - Embedded Starlark scripting support

Building

Build the compiler binary:

go build -o c65gm

Or install to your GOPATH:

go install

Usage

Quick Start (Recommended)

Compile and assemble directly to a .prg file:

./c65gm myprogram.c65                    # Creates myprogram.prg
./c65gm -i myprogram.c65 -o game.prg     # Creates game.prg

Command Reference

Build (compile + assemble to .prg)

./c65gm build -i myprogram.c65 [-o output.prg] [--keep-asm] [--no-cbm]
./c65gm myprogram.c65                    # Default build to myprogram.prg
./c65gm -i myprogram.c65                 # Same as above
./c65gm -in myprogram.c65                # Legacy syntax, still works

Compile (to .asm only)

./c65gm compile -i myprogram.c65 [-o output.asm]
./c65gm myprogram.c65 -o output.asm      # .asm extension triggers compile mode
./c65gm -i myprogram.c65 -out output.asm # Legacy syntax

Help

./c65gm help
./c65gm -h
./c65gm --help

Key Features

• Self-contained: No external build scripts needed
• Flexible syntax: -i/-in and -o/-out are equivalent
• Smart defaults: Output extension determines mode (.prg = build, .asm = compile)
• ACME integration: Automatically finds and runs ACME assembler with -f cbm by default
• Backward compatible: Legacy -in/-out flags still work
• Customizable: Use --no-cbm to disable CBM format, --keep-asm to keep intermediate files

Running Tests

Run all tests:

go test ./...

Run tests with verbose output:

go test -v ./...

Run tests for a specific package:

go test ./internal/compiler
go test ./internal/commands

Examples

See the examples/ directory for sample programs:

• hires/ - High-resolution graphics demo
• multicolorbm/ - Multicolor bitmap demo
• memlib_demo/ - Memory library usage
• switch_demo/ - SWITCH/CASE statement examples

Building Examples

cd examples/hires
c65gm hires.c65                     # Creates hires.prg
c65gm -i hires.c65 -o demo.prg      # Creates demo.prg
c65gm compile -i hires.c65          # Creates hires.asm only

The example directories also contain cm.sh scripts showing the old build method.

Documentation

• language.md - Complete language reference
• syntax.md - Syntax guide
• commands.md - Command reference

Editor Syntaxes

• Kate: copy XML to ~/.local/share/org.kde.syntax-highlighting/syntax/
• Sublime: copy .sublime-syntax to Packages/User/

License

Copyright (C) 1999, 2025 Mattias Hansson Distributed under GPL.