Page 1 of 4
bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Mon Jan 19, 2026 10:17 pm
by WillisBlackburn
I've spent the past couple of weekends vibe-coding this:
https://github.com/willisblackburn/bug65
It's a rough and ready simulator and debugger for Visual Studio Code that works with the cc65 compiler suite. The simulator, which runs within the debugger itself, acts like the sim65 simulator that comes with cc65 and supports its "paravirtualization" APIs. All you need to do is install the extension, compile for the sim6502 target, add a "bug65" configuration to launch.json, and run. You can interact with the program through the "bug65" terminal window.
Very brief demo:
https://drive.google.com/file/d/1rMMdu- ... sp=sharing
My objective was to debug unit tests. My project code is in assembly language, but I write unit tests in C and run them in sim65. Until now, whenever I've had some problem I've added BRK statements to the code and print the registers and various ZP variables in the BRK handler. This replaces that process.
What works:
- Breakpoints
Step over/in/out
Registers and flags display
Watch variables (but only numbers)
C local variables (sometimes)
sim65 paravirtualization APIs
What doesn't work:
- C local variables (sometimes)
Watch expressions, non-numeric watches, or really anything that requires knowledge of C types
Conditional breakpoints and logpoints
sim65 counter and control peripherals
I spent some time trying it to work better with C, but after a couple of days of frustration, I'm starting to think that cc65 just doesn't support what I'm trying to do. For example, I can't figure out how to get the values of C local variables reliably. The debug info generated by the compiler includes "csym" objects that are obviously the locals, and each one specifies an offset relative to the C stack pointer. But they don't have any type information (they all say type=0, which is void), nor does there seem to be a way to figure out what the C stack pointer was at the start of the scope, vs. where it is now. If anyone knows anything about this, please let me know.
If you try it and it works, or doesn't work, let me know. Feel free to fork or file bugs in the GitHub project.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 12:02 am
by BigDumbDinosaur
I spent some time trying it to work better with C, but after a couple of days of frustration, I'm starting to think that cc65 just doesn't support what I'm trying to do.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 12:46 am
by WillisBlackburn
You may find the vbcc compiler a better choice for this project. It’s significantly more advanced than cc65 and was developed by someone who is a compiler expert.
A better compiler would be welcome. Does it have an assembler, run on an ARM Mac, and generate debug data?
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 12:50 am
by WillisBlackburn
Now that I'm (temporarily?) done hacking on the debugger, I've gone back to my original project. And guess what, the debugger is actually really useful for my purpose, debugging my own assembly language code. Here you can see it's showing me the registers and flags, some zero page values (in watches), the call stack (mixed C/assembly), and stuff on the 6502 stack that's not one of the call stack return addresses.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 3:35 am
by BigDumbDinosaur
A better compiler would be welcome. Does it have an assembler, run on an ARM Mac, and generate debug data?
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 7:54 am
by BigEd
(Edit: noting that this is a bit of a tangent to the thread)
Better to link to the vbcc home page - for one thing, there's a newer version. Also you'll find description of features and platforms and links to the sources.
http://www.compilers.de/vbcc.html
It looks like it's a command line set of tools and there are prebuilt binaries for Windows and Linux. As such, I'd expect building for Mac wouldn't be a problem.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 9:42 am
by BigDumbDinosaur
Better to link to the vbcc home page - for one thing, there's a newer version. Also you'll find description of features and platforms and links to the sources.
In any case, I’ve done a little fooling around with vbcc on Linux and like what I have seen—and I’m not too much into C development.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 11:28 am
by vbc
You may find the vbcc compiler a better choice for this project. It’s significantly more advanced than cc65 and was developed by someone who is a compiler expert.
A better compiler would be welcome. Does it have an assembler, run on an ARM Mac, and generate debug data?
It has an assembler and linker, and it can be built for Mac. Source code for the compiler is available at
http://www.compilers.de/vbcc.html, for the assembler at
http://sun.hasenbraten.de/vasm/, and for the linker at
http://sun.hasenbraten.de/vlink/. Building the executables and replacing the linux binaries from the 6502 is reported to work.
While vbcc supports source level debugging (e.g. DWARF) for some targets, it is currently not implemented in the 6502 backend due to lack of debuggers on the supported 6502 target systems. The linker can create symbol lists as understood by certain emulators.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Tue Jan 20, 2026 9:22 pm
by barnacle
I'm missing something obvious trying to play with vbcc:
- Linux Mint/Cinnamon
- Extracted to /home/barnacle/Projects/vbcc6502/vbcc6502_linux which contains /bin, /config, and /targets
- echo $PATH
/home/barnacle/Projects/vbcc6502/vbcc6502_linux/vbcc/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
I want to build for a generic 65c02, to a terminal output (I expect to have to provide a cout() somewhere). Do I need to build a config file in line with the ones in the config directory? And if so, how do I select it?
Thanks,
Neil
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Wed Jan 21, 2026 1:11 pm
by vbc
I want to build for a generic 65c02, to a terminal output (I expect to have to provide a cout() somewhere). Do I need to build a config file in line with the ones in the config directory? And if so, how do I select it?
As the 6502 distribution supports many target systems, it does not provide a default config file. You have to specify the config file with +<cfg> (where <cfg> is a file located in vbcc/config). Or if you create one named vc.config, this will be used by default.
If you want to build for new hardware, you will have to create a new config, best by copying and modifying an existing configuration. Apple1 might be a good starting point (make a copy of config/apple1 and of target/6502-apple1). You probably will have to adapt the startup code and __read/__write (see libsrc/6502-apple1), the linker file (target/6502-apple1/vlink.cmd), and the config file (config/apple1).
You can also have a look at vbcc.pdf=>C Library=>65816/Simulator/Standalone=>Adapting to other systems. This section talks about adapting a 65816 config, but most of it applies just the same here.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Wed Jan 21, 2026 8:07 pm
by barnacle
Thanks. After I posted, i found the section on config, but hadn't got any further yet.
Neil
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Fri Jan 23, 2026 1:46 am
by WillisBlackburn
I downloaded the vbcc source and was, after looking at the makefile, able to build it on my ARM Mac. But, I too got to the point where it was wanting a config file, and I didn't have one. The source vbcc.tar.gz doesn't have a config directory. A few comments:
1. A for effort! It's tough to write a compiler from scratch.
2. Nice that floats are supported.
3. The documentation is very good.
4. Unfortunately, it's required because the executable itself doesn't provide any help. Tried -h, --help, etc. If you used a library to parse the command line options, you could get the help for free.
5. GitHub maybe? Just putting an unversioned source archive on a web site makes it hard to know when there have been updates and what the changes were.
6. The "no commercial use" license seems unreasonably restrictive for a compiler.
Ultimately by downloading one of the binary distributions I was able to find the config files and get vc to compile something, but I didn't carry on after that because the vbcc source distribution doesn't include the assembler or linker.
It *looks* promising. But in its current state it's difficult to use, at least for me as a Mac user. There are lot of developers with Macs, by the way! I would probably be willing to invest more time in it if there was a Mac distribution that just worked, or if I could clone the entire repo down from GitHub and build it all in one go. The restrictive license would still be an issue, though.
If anyone tries the debugger, let me know.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Fri Jan 23, 2026 7:16 am
by barnacle
I have managed to modify a config file copy to work (I put it in the same directory as the source) so now it builds 65c02 and (I hope) to use the memory map of my SBC. Still need to find out how to make romable code (i.e. more reading).
produces an ascii 'binary' file - I suspect there's a flag to produce intel hex - and
gives an assembler listing of the C parts only (i.e. not the boiler plate startup code).
My
vc.config
Code: Select all
-cc=vbcc6502 -I$VBCC/targets/6502-dnb/include -quiet %s -o= %s %s -O=%ld -c02
-ccv=vbcc6502 -I$VBCC/targets/6502-dnb/include %s -o= %s %s -O=%ld -c02
-unsigned-char
-mask-opt
-mainargs
-as=vasm6502_oldstyle -quiet -nosym -vobj3 -nowarn=62 -opt-branch -ldots -Fvobj %s -o %s -c02
-asv=vasm6502_oldstyle -nosym -vobj3 -nowarn=62 -Fvobj -opt-branch -ldots %s -o %s -c02
-rm=rm %s
-rmv=rm %s
-cpr=vcpr6502 -quiet %s %s
-cprv=vcpr6502 %s %s
-ld=vlink -m -b wozmon -Cvbcc -T$VBCC/targets/6502-dnb/vlink.cmd -L$VBCC/targets/6502-apple1/lib $VBCC/targets/6502-apple1/lib/startup.o %s %s -o %s -lvc
-ldv=vlink -m -b wozmon -Cvbcc -T$VBCC/targets/6502-dnb/vlink.cmd -L$VBCC/targets/6502-apple1/lib $VBCC/targets/6502-apple1/lib/startup.o %s %s -o %s -lvc
-l2=vlink -m -b wozmon -Cvbcc -T$VBCC/targets/6502-dnb/vlink.cmd -L$VBCC/targets/6502-apple1/lib %s %s -o %s
-l2v=vlink -m -b wozmon -Cvbcc -T$VBCC/targets/6502-dnb/vlink.cmd -L$VBCC/targets/6502-apple1/lib %s %s -o %s
I have no idea what the wozmon stuff is, but I don't have wozmon so that can probably go.
My
vlink.cmd looks like this at the moment.
Code: Select all
MEMSTART =? 0x300;
MEMEND =? 0x7F00;
STACKLEN =? 0x100;
MEMORY
{
zero : org = 0x0 , len = 0x100
ram : org = MEMSTART, len=MEMEND-MEMSTART-STACKLEN
}
SECTIONS
{
zpage (NOLOAD) : {*(zpage) *(zp1) *(zp2)} >zero
text : { *(text) *(rodata) *(.ctors) *(.dtors) } >ram
data : { *(data) } >ram
bss (NOLOAD) : { *(bss) } >ram
__BB = ADDR(bss);
__BE = ADDR(bss) + SIZEOF(bss);
___heap = MAX(ADDR(data) + SIZEOF(data), ADDR(bss) + SIZEOF(bss)) + STACKLEN;
___heapend = MEMEND-STACKLEN;
STACKSTART = ___heap;
}
Should we move this to its own thread, or has it taken over this one sufficiently that the OP is happy to keep it here?
Neil
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Fri Jan 23, 2026 2:29 pm
by vbc
I downloaded the vbcc source and was, after looking at the makefile, able to build it on my ARM Mac. But, I too got to the point where it was wanting a config file, and I didn't have one. The source vbcc.tar.gz doesn't have a config directory.
Yes, this only the source snapshot. The target-specific distributions contain config files.
4. Unfortunately, it's required because the executable itself doesn't provide any help. Tried -h, --help, etc. If you used a library to parse the command line options, you could get the help for free.
Actually I think this is the first time I get this request. But I agree at least some kind of usage info would not hurt (although I think the documentation will still be needed most of the time). I will probably put that on my todo list.
5. GitHub maybe? Just putting an unversioned source archive on a web site makes it hard to know when there have been updates and what the changes were.
I don't like github, but some kind of better curated source distribution is on my todo list. Of course the problem with todo lists ...
6. The "no commercial use" license seems unreasonably restrictive for a compiler.
It is possible to acquire a license for commercial use.
Ultimately by downloading one of the binary distributions I was able to find the config files and get vc to compile something, but I didn't carry on after that because the vbcc source distribution doesn't include the assembler or linker.
I think I posted the links to the sources for vasm and vlink in a previous post.
It *looks* promising. But in its current state it's difficult to use, at least for me as a Mac user. There are lot of developers with Macs, by the way! I would probably be willing to invest more time in it if there was a Mac distribution that just worked, or if I could clone the entire repo down from GitHub and build it all in one go.
I would be happy to include Mac binaries in the target distributions. The problem with Mac is that last time I looked it seems you have to have a Mac and/or some developer subscription to build binaries suitable for public distribution. Maybe I will include the sources and a compile script with the binary distributions. But I would not be able to test if it works on a Mac.
Re: bug65: cc65 simulator + debugger for Visual Studio Code
Posted: Fri Jan 23, 2026 3:11 pm
by vbc
I have managed to modify a config file copy to work (I put it in the same directory as the source) so now it builds 65c02 and (I hope) to use the memory map of my SBC. Still need to find out how to make romable code (i.e. more reading).
To run from ROM you can add a memory region "rom", analogous to the "ram" you currently have in vlink.cmd. Then modify the entry for the data section like this
Now you can define some more symbols in the linker file:
Code: Select all
__DS = ADDR(data);
__DE = ADDR(data) + SIZEOF(data);
__DC = LOADADDR(data);
The startup code has to be extended to fill the RAM from __DS to __DE with the contents from ROM starting at __DC.
I don't know if you need some additional hardware initializations or interrupt vectors.
Code: Select all
...
-ld=vlink -m -b wozmon -Cvbcc -T$VBCC/targets/6502-dnb/vlink.cmd -L$VBCC/targets/6502-apple1/lib $VBCC/targets/6502-apple1/lib/startup.o %s %s -o %s -lvc
I have no idea what the wozmon stuff is, but I don't have wozmon so that can probably go.
The -b option selects the output format. wozmon is the format for the monitor in the Apple1 (the ascii file you got). If you run vlink -v (or check the vlink.pdf) you get a list of available output formats. ihex selects Intel hex format. Maybe rawbin or one of the s-records variants may be useful, too.
Should we move this to its own thread, or has it taken over this one sufficiently that the OP is happy to keep it here?
I am fine either way. Maybe move it to the existing vbcc thread?