Project Files

A project file describes an assembly project in YAML:

name: MyGame
cpu: z80
sections:
  - org: "0x8000"
    sources:
      - "main.asm"
      - "lib/**/*.asm"
  - org: "0xC000"
    phase: "0x4000"
    sources:
      - "copied.asm"
  - org: "0xD000"
    binaries:
      - "sprites.bin"
outputs:
  - format: binary
    file: "mygame.bin"

Field	Description
name	Optional name for the project.
cpu	The target CPU: z80 or z80n.
sections	The sections of code and data to assemble, in order.
outputs	The outputs to produce.

Addresses are decimal ("32768"), or hex with a 0x or $ prefix, and must be quoted.

Sections

Each section is assembled at its org location. Sources are assembled in the order listed; files matched by a glob pattern are ordered case-insensitively within that pattern. Paths are relative to the project file.

Field	Description
org	The location the section is assembled to.
phase	Optional: labels and $ in the section resolve as if the code runs at this location. Use for code that is copied elsewhere in memory before being executed.
sources	Assembly files or glob patterns.
binaries	Binary files whose bytes are placed in the output as-is.

Outputs

Field	Description
format	The output format; see below.
file	The file to write.

Format	Description
binary	A raw memory image, with gaps between sections filled with zeroes.
tap	A ZX Spectrum TAP tape file with a code block per section.
tapbas	A ZX Spectrum TAP tape file with a BASIC loader and a single code block. The loader's RANDOMIZE USR uses the entry point from the END directive.
tzx / tzxbas	As tap / tapbas, in TZX format.
pzx / pzxbas	As tap / tapbas, in PZX format.
z80	A 48K ZX Spectrum .z80 snapshot. The program counter comes from the END directive, falling back to the start of the first section.
symbols	A symbol file with a Name: EQU $XXXX line per label, for emulators and debuggers.

The tape header name comes from the project's name field, falling back to the output file name.

Assembling

With the command line tool:

oakasm assemble MyProject.yaml               # Produce the outputs defined in the project.
oakasm assemble MyProject.yaml Override.bin  # Override with a single binary output.

Building Projects in Code

Project is a plain object, so a compiler or build tool can construct one directly — including from sources that only exist in memory:

using MrKWatkins.OakAsm.Projects;

var project = new Project
{
    Cpu = Cpu.Z80,
    Sections =
    [
        new Section
        {
            Org = new Location(0x8000),
            Sources =
            [
                new AstSource(compiledSource),                   // An already built AST.
                new TextSource("data.asm", "Data: DEFB 1, 2"),   // Assembly text in memory.
                new BinaryDataSource(spriteBytes)                // Raw bytes in memory.
            ]
        }
    ]
};

var result = ProjectAssembler.Assemble(project);   // No project directory needed for in-memory sources.

FileSource and BinaryFileSource load from disk relative to the project directory passed to ProjectAssembler.Assemble; the in-memory source types need no directory at all.