From 22320a33576b4739f57f899d9d45eb4be7bec428 Mon Sep 17 00:00:00 2001
From: Mattias Hansson <mattias@techserio.com>
Date: Sat, 3 Jan 2026 11:41:17 +0100
Subject: [PATCH] Added basic info about compiler.

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/README.md b/README.md
index 886a179..a80fdee 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,93 @@
 # 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)
+
+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
+
+Compile a source file to ACME assembly:
+
+```bash
+./c65gm -in input.c65 -out output.asm
+```
+
+Then assemble the output with ACME:
+
+```bash
+acme -f cbm -o output.prg output.asm
+```
+
+## 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
+
+## Documentation
+
+- `language.md` - Complete language reference
+- `syntax.md` - Syntax guide
+- `commands.md` - Command reference
+
+## License
+
+Copyright (C) 1999, 2025 Mattias Hansson
+Distributed under GPL.