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.
Emulator
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.
-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.
RetroAssembler
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:
It is important to mention one setting that we didn’t change because it is affecting the behavior:
| 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
Comments
Post a Comment