MOS is an assembler targeting the MOS 6502 CPU.
This documentation is preliminary.
It's just here to make sure current features at least have some documentation. Everything is subject to change and will hopefully improve significantly 😄
# Getting started
Let's dive into the MOS pit 🤘 (...sorry).
# Getting the tools
There are two ways to work with MOS. You can download the CLI executable, but a quicker way is to install the Visual Studio Code extension.
# Visual Studio Code extension
Installing the extension consists of these steps:
- Open Visual Studio Code
- In the
Extensionsmenu, install the extension called
- Open a folder and place an empty
mos.tomlin this folder. This is the main configuration file for
mosand the presence of this file will activate the extension.
- The extension will ask if you want to install the
mosexecutable automatically. Allow it to do so.
- Done! If you'd like to know more, you can find more detailed documentation here.
# Command line
You can download the latest release of MOS here (opens new window).
Extracting the archive will leave you with a binary called
mos. You can put it in some easily accessible place. The rest of the documentation will assume it's in your
The current version of MOS only generates Commodore-compatible
.prg files. So, let's try to build a tiny Commodore program.
# Building a sample application
Let's create a new file called
main.asm and fill it with these contents:
inc $d020 rts
This is a tiny program that changes the border colour on a Commodore 64.
Next, you can build it like so:
> mos build
If everything went well you will see no output, but a
main.prg file will have been created in a directory called
target. You can load this
.prg in your favourite C64 emulator. Run it by typing
sys 8192 in the BASIC prompt. The border colour will change, whoo!
You may be wondering why MOS is compiling
main.asm when no input filename was passed in. Well, you can configure the input filename and many other things by creating a configuration file called
mos.toml. For now, let's just keep the defaults.
# Errors in your code
What happens when there is an error 💥? Well, let's edit
main.asm and change it to this:
inx $d020 rts
inx $d020 is not a valid instruction, and this is what you will see:
> mos build main.asm:1:5: error: unexpected '$d020'
The error indicates that it is located in file
main.asm, on line 1, column 5. In this case, it didn't expect an operand because
inx does not need any.
# What next?
Alright, that was the quickest possible introduction! The remainder of the documentation will go over all the features in greater detail.