cc65cc65 is a complete cross-development package targeted at 6502-based systems. It includes a powerful C compiler, assembler, linker, and a collection of libraries and tools that make it possible to develop software in C (and assembly) for classic machines such as the Commodore 64, NES, Atari XL/XE, Apple II, and many others that use the 6502-family CPU. This article covers cc65’s history, key components, language and platform support, development workflows, optimization strategies, examples, tooling integration, and community resources.
History and Purpose
cc65 began as a project to bring a modern C-based development workflow to 8-bit platforms built around the MOS Technology 6502 family of processors. Over time it evolved from a simple compiler into a full toolchain that understands the constraints and peculiarities of those systems: limited RAM, banked ROM, cycle-counting concerns, memory-mapped I/O, and tight integration with machine-specific runtime conventions. Its goal is not to emulate contemporary desktop C compilers feature-for-feature, but to provide a practical, portable, and efficient way to write usable, maintainable code for retro hardware.
Key Components
- The cc65 C Compiler (cc65): A C compiler tailored for the 6502 architecture. It supports a substantial subset of ANSI C (C89-style), with extensions and pragmas suited to low-level programming and resource-constrained environments.
- ca65 Assembler: A highly flexible assembler that translates 6502 assembly language into object files compatible with the cc65 linker. ca65’s macro system and conditional assembly features are particularly useful for platform-specific code.
- ld65 Linker: The linker combines object files and ROM/RAM segments according to flexible configuration files (.cfg), enabling precise control over memory layout—essential for machines where code and data must reside at fixed addresses or banked ROMs.
- Libraries: A standard library (libc), plus platform-specific libraries providing routines for graphics, sound, keyboard/joystick input, and other hardware services. Libraries are often tailored per target to expose the machine’s native features.
- Tools: Utilities such as c152s (for Commodore ⁄1541 disk image handling), objdump-like utilities, and sample makefiles and templates for building projects.
Supported Targets
cc65 supports many 6502-based platforms. Notable targets include:
- Commodore 64 / C128
- Nintendo Entertainment System (NES)
- Atari 8-bit (XL/XE)
- Apple II / IIe / IIgs (6502/65C02)
- Commodore PET / CBM series
- Oric
- Various custom and hobbyist boards
Support for each target includes tailored runtime libraries and examples to ease hardware interaction.
Language Features and Limitations
cc65 implements a practical subset of C (roughly C89) with some extensions to help low-level programming:
- Primitive types: char, short, int (sizes depend on target but often 8 or 16 bits), pointers, and limited support for larger types via library functions.
- No standard support for dynamic memory allocation on many targets (or limited heap); developers often implement custom allocators or rely on static allocation.
- Function call conventions and stack handling vary by target; cc65 provides attributes and calling convention controls for mixed C/assembly projects.
- Inline assembly is supported via separate assembly modules (ca65) or by writing assembly functions in .s files; direct inline asm inside C source is limited compared to modern compilers.
- Limited or no support for floating-point arithmetic in hardware; software libraries provide floating-point routines if needed, but they are expensive in code size and speed.
Memory Model and Linker Configuration
One of cc65’s strengths is its flexible linker configuration. The ld65 linker uses .cfg files to declare memory areas, segments, and how object code maps into physical memory. Typical considerations:
- Define ROM and RAM areas with start addresses and sizes.
- Map code (.text), zero page (.zp), BSS (.bss), data (.data), and read-only data (.rodata) into appropriate regions.
- Configure bank switching regions for cartridges or larger ROM images.
- Place interrupt vectors at specific addresses required by the target (for example, C64 IRQ/RESET/BRK vectors).
Example snippet from a linker config (illustrative):
MEMORY { ZP: start = $0002, size = $001A, type = rw; RAM: start = $0400, size = $1C00, type = rw; ROM: start = $C000, size = $4000, type = ro; } SEGMENTS { CODE: load = ROM, type = rwx, start = $C000; DATA: load = ROM, type = rw, start = $C000; BSS: load = RAM, type = bss, start = $0400, align = $10; } Development Workflow
Typical cc65 project flow:
- Write C source files using cc65-supported features and platform headers.
- Implement performance-sensitive or hardware-specific parts in assembly (.s) with ca65.
- Compile with cc65 to produce object files (.o).
- Assemble any .s files with ca65.
- Link objects with ld65 using a platform-specific .cfg to produce a binary/ROM/PRG image.
- Test in emulator (VICE for C64, FCEUX for NES, Atari800 for Atari) or on real hardware via flash/cart tools or disk image writers.
- Iterate, optimize, and package.
Makefiles are commonly used to automate these steps; cc65 ships example makefiles.
Optimization Strategies
- Use register-friendly coding patterns; minimize large local arrays on stack.
- Place frequently-accessed variables in zero page for faster access.
- Write time-critical loops in assembly or use inline assembly modules.
- Reduce library footprint by compiling only needed parts or using custom lightweight replacements for standard routines.
- Use compiler options that control optimization levels and code size; sometimes manual assembly yields better results than compiler-generated code.
- Profile with cycle-counting and emulator tools that show CPU usage.
Example: “Hello, World” on Commodore 64
A minimal C example for the C64 might write directly to the screen memory at $0400. Conceptually:
#include <c64.h> void main(void) { const char *s = "HELLO, WORLD!"; char *screen = (char*)0x0400; while (*s) *screen++ = *s++ - 'A' + 1; /* C64 PETSCII conversion */ for(;;) {} } (Actual code should include proper headers and may require PETSCII conversion or use of libc routines provided by cc65.)
Interfacing with Hardware
cc65 provides headers and libraries exposing hardware registers and routines per platform. Accessing I/O typically involves reading/writing memory-mapped addresses or calling system ROM routines. Example patterns:
- Read joystick or keyboard by reading mapped registers.
- Use built-in routines for character output or manipulate VIC-II (C64) registers for custom graphics.
- For NES, write to PPU registers via CPU memory-mapped I/O with careful timing considerations.
Tooling & Integration
- Editors/IDEs: Any text editor works; some plugins exist for syntax highlighting and build integration (VS Code, Sublime, Vim).
- Emulators: VICE (C64), FCEUX (NES), Atari800, AppleWin — used for testing.
- Debuggers: cc65 includes tools and some emulators offer debugger integrations; source-level debugging is limited compared to modern toolchains.
- Cross-platform: cc65 runs on Windows, macOS, and Linux.
Community, Resources, and Examples
A strong retrodev community surrounds cc65. Resources include:
- Official documentation and manual with compiler options, library references, and linker config examples.
- Example projects and demos demonstrating game development, demos, and utilities on supported platforms.
- Forums, Discord servers, and GitHub repositories where developers share code, port libraries, and contribute enhancements.
Pros and Cons
| Pros | Cons |
|---|---|
| Targets many 6502 platforms with tailored libraries | Limited modern C feature support (roughly C89) |
| Precise control over memory layout and low-level hardware | No full inline asm in C; mixed C/assembly needed for some tasks |
| Mature toolchain with active community | Performance and code size constraints inherent to 8-bit hardware |
| Works cross-platform and supports emulators/hardware | Debugging and profiling tooling is limited vs. modern ecosystems |
Advanced Topics
- Bank switching techniques for large ROMs and how to configure ld65 to support them.
- Writing reentrant or position-independent code for shared libraries across banks.
- Building asset pipelines (graphics/sprites, sound data) and converting modern assets into platform formats.
- Creating hybrid projects: core logic in C, performance-critical routines in hand-tuned assembly.
Conclusion
cc65 is a focused, pragmatic toolchain that brings C development to classic 6502-based systems. It balances portability and low-level control, making it ideal for retro game development, demos, and hobbyist projects where resource awareness and precise memory control matter. With active community support and extensive examples, cc65 remains the go-to choice for modern development on vintage 6502 platforms.
Leave a Reply