cc65 Projects

BitMagic can debug a program built with cc65. It does not build the project; you build it as normal and point a project file at the outputs. This support is experimental and far less tested than the native .bmasm workflow, so expect rough edges.

What BitMagic needs

Build with cc65 and ld65 the way you already do, with two additions:

• Pass --dbgfile <name>.dbg to ld65 so it writes a debug file.
• Keep the object files (.o), the linker config (.cfg) and the debug file around, because BitMagic reads all three.

Project file entry

Add an entry to files with type cc65:

{
    "files": [
        {
            "type": "cc65",
            "config": "x16.cfg",
            "debugFile": "build/game.dbg",
            "objectFiles": [ "build/*.o" ],
            "includes": [ "x16.lib" ],
            "sourcePath": "src",
            "outputs": [
                { "filename": "GAME.PRG", "startAddress": 2049, "default": true, "hasHeader": true }
            ]
        }
    ]
}

Field	Purpose
config	The .cfg passed to ld65. Parsed to map segments to output files.
debugFile	The ld65 --dbgfile output. Source lines and symbols come from here.
objectFiles	The .o files. Wildcards accepted.
includes	Extra inputs. .lib is treated as a library, .mac as external source, anything else as an object file.
sourcePath	Where the source referenced by the objects lives.
basepath	Base path for this entry, under the project basePath.
outputs	The binaries ld65 produced. Exactly one should be default: true (or the first is used). hasHeader is whether the file has a two-byte load address.
filemap	path / replace pairs that rewrite source paths from the debug file so they resolve on your machine.
defaultOutputFile	The output name to run.

Mixing with BitMagic source

A project’s files array can hold both cc65 and bitmagic entries, so a cc65 program and a .bmasm module can be debugged together.

Reporting problems

Because this is experimental, odd .o, .cfg or .dbg files can trip up the parser. If a build doesn’t load, or debugging behaves oddly, check the issue tracker or open a new one with the files that triggered it.