138 lines
4.1 KiB
Markdown
138 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
go build -o c65gm
|
|
```
|
|
|
|
Or install to your GOPATH:
|
|
|
|
```bash
|
|
go install
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Quick Start (Recommended)
|
|
Compile and assemble directly to a .prg file:
|
|
|
|
```bash
|
|
./c65gm myprogram.c65 # Creates myprogram.prg
|
|
./c65gm -i myprogram.c65 -o game.prg # Creates game.prg
|
|
```
|
|
|
|
### Command Reference
|
|
|
|
#### Build (compile + assemble to .prg)
|
|
```bash
|
|
./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)
|
|
```bash
|
|
./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
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
Run tests with verbose output:
|
|
|
|
```bash
|
|
go test -v ./...
|
|
```
|
|
|
|
Run tests for a specific package:
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
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.
|