Introduction
cl65 is a command‑line assembler that forms a core component of the CC65 development package. The CC65 project supplies a complete toolchain for developing software for systems that use the 6502 family of microprocessors, including the MOS Technology 6502, its variants, and derivatives such as the 65816. cl65 accepts source files written in the 6502 assembly language, processes directives, expands macros, resolves symbols, and emits object files in a format that can be linked into final binaries. The assembler supports several target formats, allowing developers to build programs for platforms ranging from early home computers to modern emulators.
While cl65 is traditionally employed by hobbyists and retro‑computing enthusiasts, its robust feature set and cross‑platform availability also make it a viable choice for professional firmware development on legacy hardware. The assembler is written in ANSI C and distributed under an open‑source license, permitting integration into other projects and modification for specialized use cases.
The following sections detail the history of the CC65 project, the key concepts that define cl65’s operation, its major features, typical applications, typical workflows, and community resources that support its continued development.
History and Background
The CC65 project originated in the early 2000s as a response to the dwindling availability of commercial cross‑compilers for the 6502 architecture. The initial effort, led by the original author, was focused on providing a freely distributable C compiler, with the assembler component added shortly thereafter. cl65 was designed to complement the C compiler by offering a modern, efficient assembler that could be used for hand‑crafted assembly modules, small utilities, or entire programs written directly in assembly language.
The name “cl65” reflects its role as the “command‑line 6502 assembler.” The tool has evolved through numerous releases, each adding support for new target architectures, improving macro facilities, and extending the linker's capabilities. The CC65 source repository, maintained on a public code hosting platform, hosts the cl65 codebase along with extensive documentation and test suites.
Over the years, cl65 has been adopted by a diverse community of developers, ranging from independent game designers to researchers studying early microprocessor systems. Its open‑source nature has fostered a culture of collaboration, with contributors submitting bug fixes, performance enhancements, and platform‑specific patches.
Key Concepts
Command Line Interface
cl65 operates entirely through a text‑based command line, accepting options that control the assembly process. Common flags include setting the target platform, defining preprocessor variables, specifying macro directories, and determining the output format. The assembler can be invoked from build scripts, continuous integration pipelines, or directly in a terminal session.
Assembly Language Syntax
cl65 uses a syntax closely aligned with that of the MOS Technology 6502 assembler, yet it incorporates a number of enhancements such as additional directives, support for 65816 pseudo‑operations, and integrated macro processing. Instructions are written in mnemonic form, optionally followed by operand specifiers that indicate addressing modes. Directives, which begin with a period, instruct the assembler to perform tasks such as defining constants, reserving storage, or including external modules.
Object File Formats
After parsing source files, cl65 emits object files in a format compatible with the CC65 linker. The default format is a relocatable binary that contains symbol tables, relocation entries, and optional debug information. For embedded targets, cl65 can produce raw binary or hex output suitable for loading directly onto a target device.
Linking and Library Support
cl65 is tightly integrated with the CC65 linker, which resolves external symbols across multiple object files and libraries. Libraries are typically packaged as archives containing pre‑assembled modules. The assembler automatically records external symbol references so that the linker can supply the appropriate definitions at link time. This mechanism allows developers to modularize code, reusing common routines across projects.
Target Systems
Supported targets include classic home computers such as the Apple II, Commodore 64, Atari 2600, and MSX, as well as embedded platforms like the Nintendo Entertainment System (NES) and the Commodore VIC‑20. Each target defines a set of base registers, memory maps, and device interfaces, influencing how the assembler expands instructions and allocates data.
Compatibility and Extensions
cl65 maintains compatibility with legacy assembly sources, allowing projects written for older assemblers to be assembled with minimal modifications. In addition, cl65 offers extensions such as the ability to include directives for conditional assembly, macro definitions, and in‑source debugging annotations. These features enable sophisticated build processes while preserving readability of the source code.
Features and Capabilities
Macro and Conditional Assembly
The assembler supports a full macro language that allows developers to define reusable code fragments with parameters. Macros can be nested, and the assembler provides mechanisms for expanding conditional blocks based on symbol values or preprocessor definitions. This capability reduces duplication and improves maintainability of large assembly projects.
Debug Information Generation
For target systems that support debugging, cl65 can emit debug symbols alongside object files. The debug information includes mapping from source lines to machine addresses, enabling debuggers to provide source‑level stepping and breakpoints. The debug format is compatible with the CC65 debugger and various third‑party tools.
Cross‑Platform Availability
cl65 is compiled for a variety of operating systems, including Windows, macOS, Linux, and BSD variants. The tool relies on standard C library functions, making it straightforward to port to new platforms. The source distribution includes makefiles and configuration scripts that facilitate building on most Unix‑like systems.
Integration with Other Tools
Because cl65 is a command‑line utility, it integrates seamlessly with build systems such as GNU Make, CMake, and custom scripts. It can be invoked from integrated development environments (IDEs) that support external tools, allowing developers to embed the assembler into a graphical workflow. The assembler also works in conjunction with the CC65 C compiler, enabling mixed‑language projects.
Applications
Retro Computing Projects
Many enthusiasts rebuild or emulate classic computers and consoles, using cl65 to assemble firmware, operating systems, or games that run on the original hardware. The assembler’s support for legacy targets ensures that programs can be assembled for devices such as the Commodore 64 or Apple II without compatibility issues.
Emulation and Virtualization
Software developers create emulators that mimic the behavior of 6502‑based systems. Within these emulators, cl65 can be used to assemble test programs or demonstrations that run in a controlled environment, helping validate the accuracy of the emulation engine.
Game Development
Early video game developers often wrote critical performance sections in assembly to maximize speed on limited hardware. Modern indie developers create titles for retro‑style consoles, using cl65 to assemble core logic, graphics rendering, and sound handling routines. The ability to link with C modules further expands the range of available libraries.
Firmware Development
Certain embedded systems, such as industrial controllers or automotive components, still rely on 6502 derivatives. Firmware for these devices can be written in assembly to guarantee deterministic timing. cl65’s cross‑platform nature allows developers to compile firmware on modern host machines before flashing it to the target hardware.
Educational Use
Educators use cl65 in courses that cover computer architecture, low‑level programming, and systems design. Students write assembly programs to observe how instructions interact with the CPU and memory, gaining hands‑on experience with hardware constraints and optimization techniques.
Usage and Workflow
Installation
The CC65 package, which contains cl65, can be downloaded from the project's official repository. On Unix‑like systems, the package includes a Makefile that builds the assembler and associated utilities. Windows users may use pre‑compiled binaries or build from source using MinGW or Cygwin environments.
Writing Source Code
Source files typically have a .s extension. A minimal program begins with a .org directive that sets the program origin, followed by a sequence of instructions and data declarations. Comments are introduced with a semicolon or the # symbol, allowing developers to annotate code without affecting the assembled output.
Compiling and Linking
To assemble a single source file, the command is of the form: cl65 -t [target] -o output.o input.s. When multiple object files are produced, the CC65 linker ld65 is invoked to resolve external references and produce an executable. The linker accepts libraries specified with the -l option, and can produce binary, raw, or format‑specific outputs such as NES ROM images.
Running and Debugging
After linking, the resulting binary can be executed on a real target or an emulator. Debuggers compatible with CC65 can load the executable and use the debug symbols generated by cl65 to provide source‑level debugging. In an emulation environment, the assembler can be re‑invoked automatically as part of a test harness.
Examples
Below is a concise example of an assembly program that prints “Hello” on a Commodore 64. The source file includes macro usage, data definitions, and a simple loop that writes characters to the screen. After assembling and linking, the resulting binary can be loaded into the C64 via a disk image or via a serial connection to a modern host.
Extensions and Related Projects
cc65 Library
The CC65 project ships with a standard library of routines written in assembly and C. These routines provide facilities for I/O, math, string manipulation, and more, tailored to the constraints of 6502 systems. cl65 can assemble modules from this library, enabling developers to link them into their own projects.
Other Assemblers
Several alternative assemblers exist for the 6502 architecture, including CA65 (part of the CC65 suite but designed as a standalone assembler), the older 6502-Assembler, and proprietary tools used by original hardware vendors. While cl65 remains the most widely used assembler for CC65 targets, developers may choose other assemblers depending on licensing or platform requirements.
Toolchains and IDEs
Integrated development environments such as VICE, 64tass, and Code::Blocks can be configured to invoke cl65 as part of their build processes. These IDEs provide syntax highlighting, debugging interfaces, and project management features that streamline development for 6502 projects.
Community and Support
Documentation
The CC65 project provides extensive documentation covering installation, command‑line options, directive syntax, and linking procedures. The assembler’s manual includes detailed tables of supported addressing modes, pseudo‑instructions, and macro language features. This documentation serves as the primary reference for developers new to the tool.
Forums and Mailing Lists
Developers can participate in discussions on mailing lists dedicated to CC65, where contributors exchange patches, troubleshoot assembly errors, and share tips. These forums also host Q&A sessions for beginners and seasoned professionals alike.
Contributors
Key contributors to the CC65 project include the original author, who remains actively involved in maintaining the core codebase, and a roster of volunteers who provide bug reports, documentation updates, and platform‑specific enhancements. The open‑source model encourages community contributions and fosters a collaborative development environment.
See Also
Related topics include the 6502 microprocessor architecture, the MOS Technology 6502 instruction set, the CC65 compiler suite, and emulation of legacy hardware such as the Commodore 64 and Nintendo Entertainment System.
No comments yet. Be the first to comment!