Dependencies and date last changed:
This is an extension to let you debug CC65 C code (and ASM code to a small degree) made for the Commodore platforms (well-tested) and NES (experimental), including the Commodore 64, using VICE emulator and Visual Studio Code.
If you're having trouble understanding how this extension is supposed to be used, any other issues setting it up, or any features to suggest, please let me know by creating an issue or messaging me on Mastodon ( @empathicqubit (at) dizl.de ) [if copy/pasting, replace the (at) with @ ] .
Have you found this project useful, or even utter rubbish? The Flying Spaghetti Monster and I would really appreciate your rating on the Visual Studio Marketplace or OpenVSX!
If you'd like to skip some of the below setup, you can use one of the project templates. They are pretty much the same except for one or two files. After you fork them, you can open the project in Codespaces using the devcontainer.json. Keep in mind that a lot of the graphical features in the main panel will only work in VSCode on your computer, not in the web browser, but you can still do basic debugging. If you connect VSCode to Codespaces, all the features will work correctly, it just might be slow since the debugger has to run on the remote machine.
If you'd like to run a project entirely from your computer without Codespaces or devcontainers, you can also do that. This way is probably better if you want to get more serious with your development. To make sure all the features work, you'll want to install VICE 3.8 or later. A modified build of CC65 for Linux, Windows, and Mac OS is already included.
You will need to install VICE 3.8 or later and make. A modified build of CC65 is included. The easiest way to install VICE to your PATH is to use Chocolatey.
# Make sure you use an Administrator shell!
# Skip this command if you have Chocolatey already.
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
# Install the packages
choco install --version 3.8.0 winvice-nightly
choco install make
# This isn't required, but installing it will make C development a little easier.
# If you install this you should also install the llvm-vs-code-extensions.vscode-clangd
# VSCode extension from the Marketplace.
choco install llvm
Make sure these directories are not on your PATH. They will break the Makefile:
C:\Program Files\Git\bin
C:\Program Files\Git\usr\bin
These directories are okay:
C:\Program Files\Git\cmd
You will need to install VICE. The easiest way to do this is with Brew.
brew install vice
Alternatively, use the official release from Sourceforge. You will need to point
the viceDirectory setting to the bin
path. So if you dropped the folder in
Applications, that would look similar to this:
/Applications/vice-arm64-gtk3.8.0/bin
You may also want to add that path to your PATH so you can use tools like c1541
in your Makefile
.
You will need to install VICE 3.8 or later and make. A modified build of CC65 is included.
To install VICE 3.8 before it is packaged for your distribution, you will need to build VICE from source, to do that, download the source from the VICE website, then follow the below steps:
sudo apt install build-essential subversion dos2unix xa65 automake autoconf zip
sudo apt build-dep vice
cd vice-3.8.0
./autogen.sh
./configure
make -j$(nproc)
sudo make install
The last two commands will take a while, but afterwards VICE should be installed.
After installing go to your launch.json and create a new section using the snippet. If you don't have a launch.json, the "create a launch.json file" link in the debug section should create a simple one.
Obsolete settings:
cc65vice.viceDirectory
in your user settings.Required settings for both launch and attach:
launch
will launch, attach
will attach.cc65-vice
for this debugger.Required for attach mode only:
-binarymonitoraddress
option. If you specify
this for a launch, it will force it to use that port instead of a
random one.Required for launch mode only:
Other shared settings:
There are also some user settings to note:
CC65_HOME
directory, and not the bin directory, so the
folder above bin. If your system doesn't have prebuilt binaries, you probably
want to use CC65 on your PATH, and not this.You may have some problems with autostart-warp
working correctly. The way
VICE detects this may be to blame. To turn it off, just add +warp
and
+autostart-warp
to your emulatorArgs
:
{
...
"emulatorArgs": [
"+autostart-warp", "+warp",
"-model", "ntsc"
]
...
}
You will need to tell the linker that you want a debug file and a map file. You would add the following options to your linker:
-g -Wl "--mapfile,build/PROGRAMNAME.map" -Wl "--dbgfile,build/PROGRAMNAME.dbg"
And the following to your compiler:
--debug-tables "FILENAME.tab"
Make sure that the paths on the files are in the same folder and have the same name (minus the extension, of course) as your main program!
If you have included any optimizations (-Osir
) you should probably turn those
off, however, effort has been made to trace some of them.
Please also note the mk.sh and mk.bat. These will help you run make (or anything else with minor modifications) from the proper context outside of vscode, so that you use the builtin cc65 compiler when possible, instead of the one installed on your machine.
You will need node >=13, vscode >=1.42, pnpm >=5.5, Python 3 (to generate the font), and Subversion. Jest Test Explorer extension is also recommended.
For more details about what is needed to build, please look at the Dockerfile
To test:
pnpm install --shamefully-hoist
pnpm build:full
pnpm test
To build, run the following commands:
pnpm install --shamefully-hoist
pnpm build:full
If you want to debug the extension, use the Extension + Server
debug target
in VSCode after running the build commands above at least once. This will start two
debug sessions. You will need to restart the Server if you change any code
called by the main debug session process. Basically anything referenced by
src/dbg/runtime.ts.
You will need to restart the Extension if you change anything in the Extension which is not UI code. All the UI side code is located under src/webviews/index.ts since there is only one screen at the moment. All the non-UI code is under src/ext.
If you change UI code while debugging, it will automatically be reloaded. However you may need to close the webview and restart the cc65-vice session to get it to reappear correctly.
Some other package.json
scripts of note:
dist
. Use this
If something doesn't seem to update.node_modules
and the 3rdparty
directories. Use this if something is really sideways.dist/cc65
tsc
. Called by Ctrl+Shift+B
in
VSCode. This doesn't actually build the project, just quickly verifies that the
code isn't broken. Also used before the Webpack build so each component doesn't
revalidate the syntax, making it faster overall.pnpm jest -- src/__tests__/runtime-other-platforms.test.ts
build:test
for that.vsce package
using pnpm. The project is using a modified
version of vsce that has support for pnpm.All work happens on master
, and releases are merged from pull requests using Google's Release Please. Commit messages should start with fix:
for bug fixes or feat:
for new features, which will appear as bullet points in the changelogs. You can only have one fix:
or feat:
per commit message, and it must be on the first line. Do not manually edit the version or the CHANGELOG, unless your name is empathicqubit
. Breaking changes should use fix!:
and feat!:
. Force pushes occassionally happen on master
because I forget to add the tags to my commit messages.
Download the file vimspector-gadget.json
from the Release page and run a command similar to the following:
.vim/plugged/vimspector/install_gadget.py --enable-custom ./vimspector-gadget.json
An example .vimspector.json
is included in the example projects. Note that you
will need to set build.skip
to true
.
To use Mesen-X with NES, download Mesen-X and set your cc65vice.mesenDirectory
setting to the path where Mesen-X is. The file should be named Mesen.exe
. Then add NES to your targets in your Makefile
:
TARGETS := nes
Keep in mind that stdio is not implemented correctly, so printf and file operations will not work. This is a limitation of the NES platform in CC65.