Using Retro Assembler with Visual Studio Code

June 6, 2019

Visual Studio Code is perhaps the best programming environment to use Retro Assembler with. I have a frequently updated Extension in the VS Code Marketplace that offers multiple themes, syntax highlighting and command execution integration. Here is a screenshot of the latest Blue theme, showing a code file used for highlighting testing.

This application is available on all major operating systems and can be downloaded from https://code.visualstudio.com/

Setting it up is easy. After you installed it, click on the Extensions icon on the left side, or choose View -> Extensions. Enter Retro Assembler into the search field and install the extension from the marketplace. Choose one of the offered color themes for the assembler. You can change this later in Preferences -> Color Theme

(The Preferences menu option will be referenced below, so I better clarify that it's under File in Windows and Linux, and under the application name Code on macOS.)

For best practices select the installed Retro Assembler Extension on the Extensions page and read the Details page. (In an ideal world this is where this guide would finish.)

Settings

Go into Preferences -> Settings and search for Retro Assembler. Or you can just open its section up directly under the Extensions tree branch. You'll find 3 editable fields.

Retroassembler: Path

You have to enter the full path to the Retro Assembler executable file that you already installed somewhere. On Windows use the "retroassembler.exe" file from the Windows directory, and on other systems you need to enter the command "dotnet ~/retroassembler/Portable/retroassembler.dll" substituting the actual directory path from your system. If you followed my .NET Core installation guide, you can use that command alias ra (or similar) that you created for this.

Retroassembler: Args

Optional command line arguments that will be passed in for the assembler when you compile the selected code file. Refer to the documentation.

Retroassembler: Mainfile

If you are working on a bigger assembly project with multiple files, perhaps even in a deeper directory structure, you can enter the full path to your main code file that should always be compiled, instead of the currently edited file.

This whole Settings is saved as a JSON file and can be edited directly by clicking on { } on the right side. Here are my settings, for inspiration, in case you also need to disable visible white spaces, use tabs, and enjoy a cleaner editor interface in general.

{
    "retroassembler.path": "C:\\RetroAssembler\\retroassembler.exe",
    "retroassembler.args": "-x",
    "retroassembler.mainfile": "",
    "workbench.colorTheme": "Retro Assembler Blue",
    "window.zoomLevel": 0,
    "editor.fontFamily": "'Lucida Console', Consolas, monospace",
    "editor.fontSize": 13,
    "editor.insertSpaces": false,
    "editor.detectIndentation": false,
    "editor.renderIndentGuides": false,
    "editor.multiCursorModifier": "ctrlCmd",
    "editor.minimap.enabled": false,
    "editor.renderWhitespace": "none",
    "editor.renderControlCharacters": false,
    "breadcrumbs.enabled": false
}

Keyboard Shortcuts

Go into Preferences -> Keyboard Shortcuts and search for retroassembler. You'll find 2 editable commands. Bind your desired keyboard shortcuts to them.

Retro Assembler: Build

This opens the Terminal and compiles the currently edited file, or the Mainfile if set in Settings.

Retro Assembler: Build & Start

This opens the Terminal and compiles the currently edited file, or the Mainfile if set in Settings. It also passes in the -L command line argument to the assembler, which can start the compiled binary file with an emulator. In the compiled source code file you need to have a line similar to this example:

.setting "LaunchCommand", "C:\\Emulator\\emulator.exe {0}"

I personally prefer to bind these to shortcuts Alt+1 and Alt+2, respectively.

File Naming Conventions

Visual Studio Code is a great editor but needs a little help with the file type detection. There wouldn't be much use to see 6502 instruction highlighting in a Z80 assembly code file, so you need to tag your files with the CPU type you use in them. You can do this by adding a secondary file extension between the file name and the .asm (or .s, .inc) extension, like this:

Get to work!

Now you're ready to code for some good old CPUs. Just edit and save your files as usual, then press the keyboard shortcut you set up for Build or Build & Start to compile your selected file. You will see in the terminal window slotted somewhere inside the IDE whether your code compiled correctly or it has some error you need to fix. You can Alt+Click the VS Code link of the error report to open the referenced file and jump to the problematic line of code.