Assembly in Basic I - Setting up the environment

Using Retro Assembler and MS VS Code

The goal of this short tutorial is to setup minimal development environment to write and test assembly programs for Commander X16. We will use two simple steps to setup our development environment:
1.       Download and install necessary software
2.       Configure the software for automation

We will be setting up on Windows and if there is interest I can prepare a Mac and Linux version too. I am assuming you already have Commander X16 emulator installed on your system and you know the directory where it is located.

Downloading Software

There are many editors out there and the choice is very subjective matter. However, we have to take into consideration other factors like popularity that determines how well certain tool is maintained and how many resources are out there to search when problems arise and of course if there are any existing integrations and support for what we are trying to achieve.
The same is the case with Assembler. There are many available and many are very good, however many are specifically designed for certain platform (e.g. Commodore 64) and do not necessarily support Commander X16 specifics. Some others are not being actively developed and therefore might become problematic in time.

I recently found out about Retro Assembler that is being developed Peter Tihanyi. He is also a member of the Commander X16 community and is actively developing it, which is a huge plus. After checking some of the information on the web site it looks like syntax that his complier supports is also fairly standardized and is therefore relatively easy to transport source code from project built by other compliers. I was using Kick Assembler before, which is great compiler but as far as I can tell it does not support 65C02 or 65816 CPU, which means we can still build code for Commander X16 but can’t take advantage of some of the instructions or addressing modes that these processors add to standard 6502. At the time of writing the Commander X16 is supposed to ship with 65X02 with 65816 still a possibility so it would be good to have this option available down the road.

Based on that I decided to give it a try.

The documentation reveals that it has prebuilt integration with Visual Studio Code and Notepad++. Since I am already familiar with VS Code, that decision was very easy.

OK, enough talk, let’s install some software…

Retro Assembler

Go to the Retro Assembler web site

and look for  “Download the latest version from the Retro Assembler page!”. It should take you to the following page:

At the time of writing it looks like this but it might change in the future of course:

By scrolling to the bottom we can download Zip file containing all the required files. There is no need to install anything but just unzip the file into a folder of your choosing. I have all my Commander X16 files on D drive and I created a new folder for compiler at D:\X16\RetroAssembler

If you look into the folder after unzipping you will see that it contains:

There are two files that are the most important. RetroAssembler.exe is of course the compiler itself and we will be calling it to build binary files from our assembly source files.

The second important file is retroassembler.exe.config file. We will look at it later when we will setup the automatic compilation and starting of the emulator.

Visual Studio Code

Download of VS Code editor is also very simple. Just go to the following web site:

and download the file the installation file. It is executable that is started after download and takes care of installation on your PC.

Now we should have all three required pieces of software on our computer:

  • Commander X16 Emulator
  • RetroAssembler compiler
  • Visual Studio Code editor
This would be good time to write down the locations of all these three components plus think about where do we want to have our source code files. They could of course be stored in the same directory as emulator itself but that is probably not the most practical solution in long term. I am currently using pretty simple setup. I created main directory on my D drive named X16 and have three main subdirectories:

\Emulator36 the location of latest version of Commander X16 emulator
\Src directory where I keep source files in subdirectories per project
\RetroAssembler the location where I unzipped the RetroAssembler so it contains the executable and configuration files

Configure software

Next we need to configure some details to make our development as easy and as automated as possible.


There is not much to configure on the Commander X16 side, we just need to understand some of the options the emulator provides and are listed on Emulator Wiki. Two are specifically interesting for us:
-prg lets you specify a .prg file that gets injected into RAM after start.
-run executes the application specified through -prg or -bas using RUN or SYS, depending on the load address.

I also like to set the appearance of emulator by using:
-scale scales video output to an integer multiple of 640x480
-quality sets image scaling algorithm quality
nearest: nearest pixel sampling
linear: linear filtering
best: (default) anisotropic filtering

For my system, -scale 2 and –quality nearest works best.
Let’s remember these for later when we will be configuring automatic start of emulator from the editor.


Retro Assembler has many options we can configure but let’s just focus on the minimum needed and try to explain why we are using them. The file we will look at is retroassembler-settings.xml and if look at the comment in the beginning it suggests that we don’t edit that file directly. The reason being that with any new update that file might get overwritten and therefore our changes will be lost. So we will follow the guidelines and create a new file with our customizations and save them in file named retroassembler-usersettings.xml.
Let’s dive right into it:

Four settings have following meaning:

CpuType we want to take advantage of additional instructions and addressing modes so we want compiler to recognize code as 65C02. If we in the future get 65816 in Commander X16 we can change this to support even more features of that CPU. I am still hoping we will get it J
OutputFileType by default the output file is of type bin. The only difference between these two types is that files of .prg type contain the target address where to be loaded into memory so we can use simple LOAD and the system will know where in memory to put it.
AfterBuild here we can define a command that will be called after compiler successfully builds the program. We will use this to start a very simple script to copy the finished program into the emulator directory. In my case the copy.bat program contains only one line:
copy /B /Y Program.prg D:\X16\Emulator36
Of course you will have to change the name of the program depending on the source code name you are compiling and the directory wherever you put the emulator. I decided to put a copy.bat script in every root folder of my every project so this settings can stay the same regardless which project I am compiling.
LaunchCommand is the command that is used to launch emulator automatically and start/load the compiles assembly program. As before the path to the emulator might be different depending on where you installed the emulator on your system. The option –prg {0} is responsible for injecting full path to the resulting prg file. Note that we are starting the prg directly from the location where we built it and not the copy of it that was transferred to emulator directory with the “AfterBuild” script.

It is important to mention one setting that we didn’t change because it is affecting the behavior:
LaunchEnabled – stayed set to False in the default settings. Reason for it is that this way we have an option to either just build and copy assembly program or build and start it from the editor. This is done by overriding this setting inside the Visual Studio Code Keyboard shortcut setting.

Visual Studio Code

The final step is to configure the Visual Studio Code. Luckily for us that is mostly preconfigured already. Just go to Settings and open the Extensions search:

And type in Retro Assembler

Click on it and install it.

The last thing remaining is to set up the shortcuts to compile and to compile and start the program. Again the settings can easily be found under File menu:

I chose simple F4 and F5 for my keyboard shortcuts but those are already used so I overwrote the existing ones.

With this I can simply press F4 and my assembly programs get compiled and copied to the emulator directory where I can load them manually from emulator or from another program. If I press F5 it compiles, copies and starts new instance of emulator with injecting the –prg parameter with path to our newly compiled program.
Much more info about the Visual Studio Code integration is available here


Popular posts from this blog

Commander X16 Premium Keyboard

Hello VERA (BASIC vs C vs Assembly)

Direct VERA Access