Getting started programming the MOS Technology 6502 8-bit microprocessor.

This microprocessor was used in popular video game consoles and home computers of the 1980s and early 1990s, such as the Atari 2600, Atari 8-bit computers, Apple II, Nintendo Entertainment System, Commodore 64, Atari Lynx, BBC Micro and others.

This assumes a Debian-based system.

sudo apt install cc65 cc65-doc

The following programs are installed (descriptions taken from https://cc65.github.io/doc/):

Of course we'll start with the ubiquitous “Hello, world”.

hello.c

#include <stdio.h>
 
int main()
{
  printf("Hello, world!\n");
 
  return(0);
}

We can target our native platform (Linux) using the gcc compiler we're already familiar with:

gcc hello.c -o hello

This gives us the following binary output:

To target the 6502 processor, we use cl65 instead:

cl65 hello.c

This produces two output files:

The default target is Commodore 64, but you can specify a different platform with the -t argument. The Apple II, for example:

cl65 -t apple2 hello.c

Output:

To see all of the available platforms, use –list-targets:

cl65 --list-targets

If you want to test your binary, use sim6502 as your target:

cl65 --target sim6502 hello.c

Test using sim65:

sim65 hello

Hello, world!

You can get some additional info with the -v (verbose) argument:

sim65 -v hello

Loaded 'hello' at $0200-$0AE6
File version: 2
Reset: $0200
Hello, world!
PVExit ($00)

The compile and link utility (cl65) simplifies the process of building a binary by combining multiple build steps into one. For this section, we'll perform those steps individually.

We'll start with another “Hello world!” example, but with a few tweaks to the hello.c source:

hello.c

#include <stdio.h>
 
extern const char text[];
 
int main() {
  printf("%s\n", text);
 
  return (0);
}

You'll notice that our “Hello world!” text doesn't appear in the source. Instead, we have a const char text[] declaration. The extern qualifier is a hint: We'll actually define our text in a separate assembly file:

text.s

.export _text
_text:  .asciiz "Hello world!"

With both files in place, we're ready to compile using cc65. I'm targeting Commodore 64 and I've also added a -O argument to optimize the output:

cc65 -O -t c64 hello.c

This will generate a hello.s assembly file:

hello.s

;
; File generated by cc65 v 2.18 - Ubuntu 2.19-1
;
	.fopt		compiler,"cc65 v 2.18 - Ubuntu 2.19-1"
	.setcpu		"6502"
	.smart		on
	.autoimport	on
	.case		on
	.debuginfo	off
	.importzp	sp, sreg, regsave, regbank
	.importzp	tmp1, tmp2, tmp3, tmp4, ptr1, ptr2, ptr3, ptr4
	.macpack	longbranch
	.forceimport	__STARTUP__
	.import		_printf
	.import		_text
	.export		_main
 
.segment	"RODATA"
 
L0003:
	.byte	$25,$53,$0D,$00
 
; ---------------------------------------------------------------
; int __near__ main (void)
; ---------------------------------------------------------------
 
.segment	"CODE"
 
.proc	_main: near
 
.segment	"CODE"
 
	lda     #<(L0003)
	ldx     #>(L0003)
	jsr     pushax
	lda     #<(_text)
	ldx     #>(_text)
	jsr     pushax
	ldy     #$04
	jsr     _printf
	ldx     #$00
	txa
	rts
 
.endproc

Now we can take our two assembly files (the one we created from scratch, and the one we generated) and build object files from them using the macro assembler:

ca65 hello.s
ca65 -t c64 text.s

Finally, we use the linker to create our executable:

ld65 -o hello -t c64 hello.o text.o c64.lib

Here's a Makefile, if you'd like to simplify those steps:

Makefile

TARGET = c64
 
COMPILER = cc65
ASSEMBLER = ca65
LINKER = ld65
 
default:
	@echo 'Targets:'
	@echo '  build'
	@echo '  clean'
 
build: hello
 
hello: hello.o text.o
	$(LINKER) -o hello -t $(TARGET) hello.o text.o $(TARGET).lib
 
hello.o: hello.s
	$(ASSEMBLER) hello.s
 
text.o: text.s
	$(ASSEMBLER) -t $(TARGET) text.s
 
hello.s: hello.c
	$(COMPILER) -O -t $(TARGET) hello.c
 
clean:
	@rm -f hello.s
	@rm -f *.o
	@rm -f hello

The 8-bit Workshop IDE provides a quick and easy way to test your binary.

1. Go to https://8bitworkshop.com/
2. Click the “Open 8bitworkshop IDE” button.
3. Open the systems dropdown list in the upper-left corner of the screen and select “Computers”, “Commodore 64”
4. Click the menu button next to the systems dropdown and select “Upload”.
5. Browse to your hello binary and click “Open”.
6. The IDE will ask if you'd like to open 'hello' as your main project file. Click “Open As New Project”.

The binary will be loaded and you should see output similar to this:

If you'd like to learn more, here are some sites to visit:

• The cc65 repo has lots of sample code.
• The cc65 website has a lot of information, including links to detailed documentation and the repo wiki.
• 8bitworkshop is a treasure trove of information about programming for old systems, including books and an online IDE where you can write code and see it emulated in real-time.