Directives

Directives control the assembler rather than emitting instructions. They’re case-insensitive, and may optionally be prefixed with !. This page covers data, assembly control, symbols and conditionals; macros, structs and enums have their own page.

Data definition

Directive	Aliases	Description
`DB`	`BYTE`	Define 8-bit bytes.
`DW`	`WORD`	Define 16-bit words (little-endian).
`DS`	`BLOCK`	Define a block of memory, e.g. `DS 100, 0`.
`DH`	`HEX`	Define data from a hexadecimal string.
`DZ`	`STRZ`	Define a zero-terminated ASCII string.

scores  db 10, 20, 30
vector  dw $8000
buffer  ds 256, 0          ; 256 bytes of zero
name    dz "PLAYER"        ; NUL-terminated

Assembly control

Directive	Description
`ORG <addr>`	Set the assembly origin.
`BANK <bank> [, <slot>]`	Map a 16 KiB bank into the address space and place emitted bytes there. On `zxnext` an optional slot (0–7) sets the origin to `slot * 8192` and routes bytes into that bank for any slot; on `zx128` the origin is `0xC000`.
`PAGE <page>, <slot>`	(Next) Map an arbitrary 8 KiB page into an 8 KiB slot (0–7) and assemble there — including odd pages that 16 KiB `BANK` cannot express. Warns on machines that page in 16 KiB.
`INCLUDE "file"`	Include another source file.
`INCBIN "file"`, `BINARY "file"`	Include a binary file verbatim.
`GLOBAL <label>`	Mark a label as global, for export.
`END`, `ENDM`, `ENDE`, `ENDS`	Terminate a `MACRO`, `ENUM` or `STRUCT` block.
`!target <target>`	Set the target machine from source (`zx16`, `zx48`, `zx128`, `zxnext`).
`!format <format>`	Set the output format from source (`bin`, `hex`, `sna`, `nex`).

Include search paths are configured with -I, --include or the project file’s include_dirs.

Symbols & conditionals

DEFINE <name> <tokens> (or #define) — a text-replacement macro.
IF / IFDEF / IFNDEF / ELSE / ENDIF — conditional assembly (the #-prefixed forms are also accepted).

#define VERSION 2

IF VERSION >= 2
    call new_routine
ELSE
    call old_routine
ENDIF

Messages & options

!message "text" [, <expr> …] — print a message during assembly; supports expressions.
!opt <option> <value> — set an assembler option from source: verbose, cspect, z80n, maxcodesize, case-insensitive, target, format.
!nex <command> <value> / !sna <command> <value> — set output-header fields; see Targets & output formats and the NEX format reference.