VS64 - The C64 Development Environment
The VS64 extension makes it easy to build, debug, inspect and run C64 assembly code from Visual Studio Code. It provides deep integration for the ACME assembler and the CC65 and LLVM-MOS compilers, an integrated project and build system, a resource compiler, and support for the Visual Studio Code task and launch system.
Quick and Start (TL;DR)
The quickest start is by opening the command palette and run the "VS64: Getting Started" command.
If you want to do some manual steps or adjustments, these are the individual things to look at:
Creating Projects Quickly
The "Create Project" commands are a great tool to configure and re-configure a code project. Whenever such a command is issued, the current workspace will be scanned and a fresh project configuration file will be generated based on the existing source files. Afterwards, everything should be ready to build and run.
VS64 supports the ACME Cross-Assembler.
In case you did a manual or custom installation, please make sure you updated the VS64 settings with the correct ACME installation path.
VS64 supports Kick Assembler.
Please make sure you check the VS64 settings for the correct KickAssembler installation path.
VS64 also supports the CC65 6502 C Compiler.
In case you did a manual or custom installation, please make sure you updated the VS64 settings with the correct CC65 installation and include paths.
VS64 also supports the LLVM-MOS C/C++ Compiler.
Please make sure you updated the VS64 settings with the correct LLVM-MOS installation and include paths.
VS64 comes with an integrated resource compiler that turns media files into plain source code to be directly referenced by the code and compiled into the binary. Currently, the supported media formats are:
In order to use the resource compiler, just add your resources files to the "sources" list of the project file.
In addition to the internal 6502 cpu emulator, VS64 also supports debugging using the VICE emulator.
In case you did a manual or custom installation, please make sure you updated the VS64 settings with the correct VICE executable.
The VS64 extension provides a convienient editing, build and run environment. This is done by providing syntax highlighting, seamless integration to the task, build and launch system, an embedded 6502 CPU emulator for fast and precise evaluation of 6502 code and integration of the VICE C64 emulator for advanced system debugging. For further analysis, an integrated disassembler for C64 program files is provided.
For details, please look at the provided example projects for ACME, CC65 or LLVM-MOS.
VS64 provides a meta build system which is based on the Ninja build toolkit. Dependency scanning and the generation of intellisense information is supported.
Support for ACME assember syntax is provided. Syntax highlighting for KickAssembler is partially implemented. The recommended file extension is
The VS64 extension is mainly controlled and configured using a per-workspace project configuration file
The basic structure of the file is like this:
A more extensive project file for CC65 using source and resource files could like like this:
A project file for CC65 could like like this:
To specify resource compiler flags and options, add a section "resources" to the project file using the following syntax:
Project name, also defines the name of the output program file
Project description, for information purposes.
Defines all used source and resource files. The build system will keep track of changes of these files. Resources files will be translated to language-specific to binary data declarations.
Specifies which build toolkit is used. Currently supported are "acme", "kick", "cc65" and "llvm".
Specifies the target system which the binaries should be generated for. Default is the C64, possible settings are dependent on the used toolkit.
Can be used instead of 'sources' in simple projects. Defines the main source file which is compiled and used as the entry point for recursive dependency scanning.
Defines either a "release" or "debug" build. Debug builds are the default if not specified.
Optional project specific compiler defines. The project defines are added to the global defines as specified in the settings.
Optional project include paths for the compiler. The project specific include paths are added and overlay the global include paths specified in the settings.
Optional argument list to be added to the build tool command line arguments. For more fine grained setting, use the 'assemblerFlags', 'compilerFlags' and 'linkerFlags' attributes.
Optional arguments to be added to the assembler command.
Optional arguments to be added to the compiler command.
Optional arguments to be added to the linker command.
Example to use a specific linker configuration for cc65:
Overrides the path to the compiler executable. The default path is specified in the settings.
Optional parameters for the resource compiler. Currently, the following list of parameters is supported:
Optional arguments to be added to the resource compiler command. Use this to force the resource compiler to produce a specific output format, where format can be 'cpp', 'cc', 'acme' or 'kick'.
The VS64 build system supports the IntelliSense editing features of Visual Studio Code. Project settings, include paths and defines are automatically provided to the IntelliSense system.
Further information about IntelliSense can be found here.
Whenever a referenced source file or the project settings file is modified and saved, it is automatically compiled to a C64 (cbm)
If compilation is successful, that program file can either be run/debugged with the embedded debugger based on a defined launch configuration (see Debugger Launch Configuration), or it can be loaded into a VICE emulator session to run an advanced debugging session.
If compilation fails, the ACME outputs are shown in the problems view as well as in the output terminal view.
The VS64 extension comes with a built-in 6502 CPU emulator that allows very fast edit-build-run cycles. The limitation is important to understand: it is not a full C64 emulation. It executes 6502 machine code as fast as possible - and integrates nicely to the Visual Studio Code debugger interface. But it does not emulate any of the C64 custom chips (the VIC, SID, CIA, etc.). To still run C64 code similar to what would happen on a real C64, the bank switching and handling of ROM memory areas is supported. Also, basic startup behavior is supported in a way that actual C64 program files can be loaded and executed.
As another option for debugging, a VICE emulator session can be launched or attached to perform advanced debugging steps in an acurate C64 system emulation.
Supported debugging features:
Debugging support for the CC65 toolkit
Debugging support for the LLVM Toolkit (Elf/Dwarf):
Debugger Launch Configuration
In order to debug a compiled C64 program (
Can be either "6502" to run the integrated 6502 cpu emulator or "vice" to run a VICE emulator based debugging session.
Use "launch" here to run a new emulation session. In case "vice" is selected as debugger type, then a new VICE process is started.
Use "attach" to attach to a running VICE process. VICE needs to have the binary monitor interface enabled, or has to be started with the
Any name you want to use is fine.
Optional name of host running a VICE emulator with enabled binary monitor. If not specified, 'localhost' will be used.
Optional port number of running a VICE emulator with enabled binary monitor. If not specified, the binary monitor default port '6502' will be used.
A 16-bit address in decimal or $hexadecimal form.
Optional task name, can be
Debugger Watch Expressions
The debugger supports different kinds of watch expressions: registers, constant values and addresses. Here are a few examples for direct, symbolic and indirect watch expressions:
To setup the C64 development environment, go to Preferences>Settings to open the settings window.
Build System Settings
Path to Acme installation. Example:
Path to KickAssembler installation. Example:
Path to Cc65 installation. Example:
Path to LLVM-MOS installation. Example:
Global build defines.
Global build include paths.
Global build command line options.
Path to custom Ninja build executable. Example:
Path to custom Python installation. Example:
Path to Java executable. Example:
Path to a Python script to be used as a drop-in replacement for the VS64 resource compiler (rc.py).
Enable auto build before running or debugging.
Path to Vice emulator executable. Example:
Additional emulator command line options.
Set console output verbosity level (error, warn, info, debug, trace).
Can be used to disable recursive parsing of assembly files. Mostly used for debugging purposes. Default and recommendation is to leave it enabled.
Enable the welcome page. This setting is automatically disabled after the welcome page has been shown.
This package includes open source from other developers and I would like to thank all of those: