The Command Line Tool

Install the oakasm tool globally:

dotnet tool install --global MrKWatkins.OakAsm.Tool

Assembling

Assemble a project file to a binary:

oakasm assemble MyProject.yaml Output.bin

Assembly errors are reported with source positions and the tool exits with a non-zero exit code. If the project's ORG directives leave gaps between blocks of code, the gaps are filled with zeroes in the output file so every byte is at the correct offset from the first block.

Disassembling

Disassemble a ZX Spectrum file (currently .z80 snapshots) to assembly:

oakasm disassemble HungryHorace.z80              # To the console.
oakasm disassemble HungryHorace.z80 -o Out.asm   # To a file.

Disassembly starts from the snapshot's program counter and follows jumps, calls, DJNZ loops and RST vectors to discover reachable code.

Option	Description
`-o`, `--output`	Write the disassembly to a file instead of the console.
`-e`, `--entry-point <ADDRESS>`	Extra entry point to disassemble from. Can be repeated.
`--exclude-before <ADDRESS>`	Exclude routines before this address. Defaults to `$4000`, the start of RAM on the ZX Spectrum.
`--no-follow-jumps`	Only disassemble linearly from the entry points.

Addresses are decimal, or hex with a 0x or $ prefix.

Disassembly Projects

Disassembly is iterative: run it, work out what an address is, record it, run again. A disassembly project keeps that knowledge in a YAML file so the generated assembly can be regenerated at any time — pass it to disassemble in place of the input file:

oakasm disassemble HungryHorace.yaml

input: "HungryHorace.z80"
entry_points:
  - "0x6000"
exclude_before: "0x4000"
labels:
  "0x6000": start
  "0x6C40": print_score
data:
  - start: "0x7000"
    end: "0x77FF"
output: "HungryHorace.asm"

Field	Description
`input`	The file to disassemble, relative to the project.
`entry_points`	Extra entry points, merged with any from the input file such as a snapshot's program counter.
`exclude_before`	Exclude routines before this address. Defaults to `$4000`.
`labels`	Labels for known addresses; used for the definition and everywhere the address is referenced.
`data`	Ranges known to contain data. They are output as `DEFB` rows and never disassembled as code — recording these stops data being misread as garbage instructions.
`output`	The file to write, relative to the project. Written to the console if not set.

Command line options override the project's settings. Output is deterministic, so rerunning after editing the project shows only the changes your new knowledge produced.

Formatting

Reformat an assembly file to a consistent style:

oakasm format Main.asm                           # To the console.
oakasm format Main.asm -o Main.asm               # In place.
oakasm format Main.asm -c Formatting.yaml        # With a configuration file.

Option	Description
`-o`, `--output`	Write the formatted assembly to a file instead of the console.
`-c`, `--config`	A YAML formatting configuration file controlling case, number formats and spacing.
`--cpu`	The CPU the assembly targets: `Z80` (default) or `Z80N`.