Retro Assembler V2020.1 Released

February 20, 2020Retro Assembler.NET

The assembler project is now built exclusively for .NET Core 3.1 and it's a single portable package for Windows, macOS and Linux, running on X86, X64 and ARM architectures.

With this step, the code base and the release package are simplified. All you have to do is install .NET Core 3.1 once and you're good to go. You may also follow the guide How to Install .NET Core on Linux and macOS (and Windows) if necessary.

The .NET Framework 4.7 version is now discontinued. Microsoft basically deprecated the .NET Framework, with the next version they will merge everything into .NET 5.0. Hopefully at that point Windows Update will install it for everybody on Windows, but until then .NET Core needs to be installed manually to make Retro Assembler work.

For simplicity, the assembler's version number has been changed to the modern style Year.Release, kicking off with 2020.1

Thank you for your support!

See the documentation for details.

Download the latest version from the Retro Assembler page!

Kindle eBook Preservation Without DRM

February 4, 2020BackupeBook

In the past few years I've become an avid reader again, after a long time of neglect. I standardized on eBooks from the Amazon Kindle store and used the Kindle app on various devices, until recently I got myself an eInk Kindle Oasis, the 2019 version. The previous Kindle devices just wouldn't cut it for me compared to an iPad Mini (I'd still vouch for that as the second best option), but this newest one has a pleasant form factor, page turn buttons, warm LED front light (a must have for me), it's comfortable to hold and has nice cover options with magnetic wake and sleep functionality. The battery life is very good, if you use it in airplane mode most of the time like I do. It isn't cheap but it's worth it for me, with removed ads which costs extra, but makes it all better. No more swiping up to read the current book; it's a cheap fix for a major annoyance.

As someone who's been in the IT world since the '90s, I'm a bit paranoid about backups, data preservation, file formats and storage in general. No need to store anything, it's all available on the internet! Just keep it in the cloud! All I can offer to those claims is a bittersweet smile. In this case with eBook stores, it's not unheard of that a publisher decides to take the ball home and previously purchased books become unavailable for further download. Or maybe they replace the old version with an inferior one. Or perhaps you choose to move your data into a completely different ecosystem.

Books in the Amazon Kindle store are DRM-protected, but luckily (currently) there are ways to get rid of the DRM and make it possible to move books from one device to another in the uncertain future, even when the books are no longer available for download.


This tutorial requires having a Kindle eInk device and purchased books on your Amazon account. Technically it may be possible to use the Kindle for Mac/PC app instead of a device, but that may depend on older, specific versions of the app so I will leave it to others to figure it out. I also don't know how this would work with Kindle Fire tablets. The DeDRM FAQ may be able to answer these questions.

The currently used Kindle file format is called AZW3, but later on this may change to AZW4 or something, depending on Amazon's decisions. The then-latest versions of the software described below will likely be able to handle it using the same general method.


Download your eBooks

Find the Manage Your Contents and Devices section on the Amazon website where the Content section will look something like this. Pick a book and in the Actions menu choose Download & transfer via USB. Then you'll have to choose your eBook device to download the file for. This is important, the DRM will be generated for the chosen device, based on its unique serial number.

The resulting file is in Amazon's DRM-protected AZW3 format, or in their legacy AZW format for MOBI files. eBook files can be obtained from the Kindle's file system too, but these days most of them are stored there as KFX, which is harder to work with using additional Calibre plugins, if you want to go down that route. I choose not to, partially because in the books Amazon sends to the device's library, the cover images are converted to grayscale. With this manual download method the cover images are preserved in their original color format.

Configure Calibre

Install Calibre, then go into Preferences and locate Advanced → Plugins. Click the Load plugin from file button and select the DeDRM Calibre plugin zip file. This will be added under File type plugins. Next, you need to configure it and enter the serial number of your Kindle eInk device, which will be used to decipher and remove the DRM protection from the book that is currently tied to the specific device.

After this, when you import a Kindle eBook file into Calibre, the DRM will be stripped by the DeDRM plugin automatically and you can open the book in the Viewer. If Calibre can't open the book and complains about DRM, the plugin either wasn't configured properly, or it can't handle the file you tried to import.

eBook management

The converted eBook files can be found in Calibre's library structure, categorized by author. AZW3 files remain in the same format, while the legacy AZW gets converted to MOBI by default, so it varies what file extension you need to look for. MOBI files can be converted to AZW3 for a consistent library. Beside format conversions, you can update the embedded cover art, meta data, and even the whole book can be edited if necessary.

I opt to store my eBook files myself, outside of the Calibre library structure, by keeping both the original and the DRM-free version of each. The unlocked books then can be transferred to the Kindle device via USB connection into the Documents/Downloads directory, or they can be emailed to the unique Kindle email address of the device, which will download it via WhisperSync. The Kindle device will find it, import it into its library and do the necessary indexing automatically. If down the road you decide to move the books to a different type of device, Calibre will likely be able to convert them to the required file format, or to a commonly used one like ePub.

Retro Assembler V2.4.2 Released

October 19, 2019Retro Assembler

Small update.

See the documentation for details.

Download the latest version from the Retro Assembler page!

Using Retro Assembler with Visual Studio Code

June 6, 2019Retro AssemblerVS Code

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

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.)


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.

How to Install .NET Core on Linux and macOS

Updated on February 28, 2020Retro Assembler.NETLinux

If you want to use Retro Assembler to code on Linux (even on a Raspberry Pi) or on macOS, you have to install .NET Core on your computer. Normally you'd just go to and follow the instructions, but if you need help, I'll try to provide some here.


Installing on Windows

Installing on macOS

Installing on Linux

Here are the commands you'll need to enter into the Terminal:

#Download the Ubuntu 19.10 related packages for the package manager.
wget -q -O packages-microsoft-prod.deb

#Install it for the package manager.
sudo dpkg -i packages-microsoft-prod.deb

#Install this utility.
sudo apt-get install apt-transport-https

#Update the package manager.
sudo apt-get update

#Install the .NET Core Runtime.
sudo apt-get install dotnet-runtime-3.1

Installing on Raspberry Pi and on other ARM based SBCs

Here are the commands you'll need to enter into the Terminal:

#Install some possibly missing packages that will be needed.
sudo apt-get install libunwind8 gettext curl wget

#Make the dotnet directory where the .NET Core Runtime will be installed.
sudo mkdir /usr/share/dotnet

#Extract the files from the downloaded file.
sudo tar -xvf dotnet.tar.gz -C /usr/share/dotnet/

#Set up a symbolic link to this directory so it will be found on path
#when you type in the command "dotnet".
sudo ln -s /usr/share/dotnet/dotnet /usr/local/bin

This works perfectly, the only caveat is that you'll need to perform this manual install with every updated .NET Core version you want to use.

Testing in the Terminal

Run this command to check whether the .NET Core Runtime has been installed successfully. It will list the currently installed version's details.

dotnet --info

Now you can run Retro Assembler with this command:

dotnet retroassembler.dll

Optional, but it is recommended to edit the command shell's startup file with a command alias to run Retro Assembler with ease, as if it was a Linux/Mac native command line application.

Open your user's home directory and edit the hidden file .bashrc on Linux, or .bash_profile on macOS. The latter usually doesn't exist and you have to create it. Then enter this line into the bash file with your chosen file path:

alias ra='dotnet ~/PATH/retroassembler.dll'

This will allow you to just enter the command ra and run the assembler from either the Terminal or from Visual Studio Code.

Retro Assembler V2.4.1 Released

May 31, 2019Retro Assembler

It's a small but useful update for those who use the Visual Studio Code Extension, which is recommended for the best coding experience.

The display format of errors and warnings got tweaked a little to display a clickable link that allows Visual Studio Code to open the referenced source code file at the problematic line number.

Unfortunately in such links Visual Studio Code doesn't correctly recognize paths with spaces in them (yet), but I chose the best option (quotes around the filename) that will likely be handled by it in the future.

I also added a new output file format called SBIN which is similar to the PRG format, but the file data length is also saved into the header, making it typically 4 bytes long.

The rest of the important changes are in the Extension which is now elevated to version number 1.1.0

See the documentation for details.

Download the latest version from the Retro Assembler page!

Retro Assembler V2.4 Released

April 4, 2019Retro Assembler

I had a couple of small bug fixes to do and in the same time I took the opportunity to update some directives, add new ones and work on the documentation a bit.

See the documentation for details.

Download the latest version from the Retro Assembler page!

Retro Assembler V2.3.1 Released

February 13, 2019Retro Assembler

This is just a smaller bug fix for Linux. I noticed that the Windows version doesn't run on Ubuntu Linux using Mono, mainly because of the Gnome Terminal's default TERM environment value. It's set as xterm-256color while Mono apparently needs it to be set as xterm, otherwise it fails when the Console is accessed. This can be remedied from the user's login script like in .bashrc but I fixed it from software for the application's thread.

Then there was another bug that happens only with the x86-64 version of Mono, it always worked fine on ARM. That issue has been fixed too.

Either way, I still recommend using the .Net Core version on Linux and macOS.

See the documentation for details.

Download the latest version from the Retro Assembler page!

Retro Assembler V2.3 Released

November 13, 2018Retro Assembler

As it happens, while I was working on an assembly project, I ran into some shortcomings that I tried to fix in this new release.

There was no way to just allocate bytes in memory, without actually writing data into the virtual memory. This normally isn't a problem in Commodore 64 projects, but in Gameboy projects the code is in ROM and the RAM is separated from it. Even though the ROM builder would ignore those bytes, words and arrays that you'd put between $c000-$dfff, it's not too elegant to write the code that way. Now it's possible to just allocate bytes these ways:

      RAM          .org $c000
      ButtonState  .byte ?
      Buffer       .storage $20

Other changes, some were made in version 2.2.1

See the documentation for details.

Download the latest version from the Retro Assembler page!

Retro Assembler V2.2 Released

October 1, 2018Retro Assembler

The new version is out with a quite a lot of goodies. It took a while to implement all this, but it was worth it.

If everything goes right, this will be the first time current users will be notified about a version update by the assembler itself. Exciting times!

See the documentation for details.

Download the latest version from the Retro Assembler page!

Check out the Archive for more posts!