Command-line reference
FantASM is driven from a single fantasm command:
fantasm [command] [options] <source> [output]If you don’t name a command, build is assumed — so fantasm main.asm game.nex and fantasm build main.asm game.nex do the same thing.
Commands
| Command | Description |
|---|---|
build | Assemble the source file. The default when no command is given. |
init | Initialise a new FantASM project. Runs interactively if you pass no flags. |
init options
| Option | Description |
|---|---|
--name <name> | Project name written to fantasm.toml. |
--target <target> | Default target machine. |
--format <format> | Default output format. |
--main <file> | Main entry-point filename. |
-f, --force | Overwrite existing files without prompting. |
Global options
| Short | Long | Description |
|---|---|---|
-h | --help | Show the help message and exit. |
-t | --target <target> | Target machine: zx16, zx48, zx128, zxnext. |
-f | --format <format> | Output format: bin, hex, sna, nex. |
-N | --z80n | Enable Z80N (ZX Spectrum Next) CPU extensions. |
-c | --cspect | Enable CSpect EXIT and BREAK instructions. |
-I | --include <dir> | Add a directory to the include search path. |
-D | --define <CONST=VAL> | Define a constant, e.g. -DDEBUG=1. |
-e | --export-labels <file> | Export labels to a file. |
--sld <file> | Write Source Level Debugging (SLD) data to a file. | |
-O | --origin <addr> | Set the initial assembly origin. |
-M | --max-code-size <size> | Limit the size of assembled code. |
-i | --case-insensitive | Case-insensitive labels and constants. |
-W | --enable-warnings | Enable warnings (e.g. unused labels). |
-v | --verbose | Verbose output. |
-n | --nologo | Hide the program name and version banner. |
-p | --project <file> | Load configuration from a project TOML file. |
-V | --version | Print the version and exit. |
--lsp | Start the Language Server for editor integration. | |
--ram <size> | RAM variant (2mb, 1mb, 512k); default is the target maximum. | |
--check-updates | Check online for a newer FantASM release and exit. |
Command-line arguments always take precedence over values in a fantasm.toml project file.
Examples
# Assemble for the Next, emitting a .nex
fantasm main.asm game.nex -t zxnext
# Build with Z80N + CSpect debugging, an include path, and a define
fantasm main.asm game.nex -N -c -I lib/ -DDEBUG=1
# Run the unit tests embedded in the source
fantasm build main.asm --test
# Start the language server (for your editor)
fantasm --lsp