Command Line

fantasm [command] [options] <source> [output]

Both command and output are optional, so the shortest useful invocation is fantasm main.asm. In a directory holding a fantasm.toml, fantasm build is enough.

⛔ fantasm with no arguments at all prints a usage summary and builds nothing, even with a project file beside it. Any argument is enough to start a build — fantasm build, fantasm -n and fantasm --all all assemble — but the bare word does not.

Anything given here beats the same setting in the project file. fantasm --help prints the same list in brief.

Commands

fantasm with no arguments at all prints a short usage and exits, rather than trying to build something.

Where the output goes

fantasm build main.asm            # -> main.bin
fantasm build main.asm game.nex   # -> game.nex

The second positional argument names the output. Left out, the name comes from the source’s stem and the format’s extension.

Naming a source turns off project-file auto-detection. fantasm build one.asm in a directory containing fantasm.toml ignores the file. Pass -p fantasm.toml if you meant to use both.

Choosing the machine

An unknown target is a warning, not an error. -t zx81 builds, having said so once. If a build behaves as though the setting never took, check the spelling.

--ram narrows the paging range rather than describing the hardware, so a bank beyond it becomes an assembly error — --ram 512k allows banks 0–31 and refuses bank 32. Set it to the smallest machine you intend to support and the build tells you when you exceed it, instead of the machine’s owner doing so.

Assembling

⛔ -O and -M take decimal only. -O 0x9000 and -O $9000 are both rejected with Bad value, which is a surprise in an assembler where every other number may be hex. Write -O 36864.

-D is not so restricted, and takes three forms:

fantasm main.asm -D DEBUG=1        # a number, hex accepted: -D BASE=0x4000
fantasm main.asm -D NAME=nightly   # text, assemblable with db and dz
fantasm main.asm -D FLAG           # no value, for IFDEF

--gc-modules is off unless asked for: a wrongly discarded routine is a crash at run time rather than a failure at build time, so it is not something to have on by accident. Pin anything reached only indirectly with KEEP.

Output and artifacts

-e writes only GLOBAL symbols. The file is empty until something is exported — that is intended, and the .sld file is what a debugger reads.

The project file

See The Project File and Building Several Images. --only rather than --target, because --target names the machine.

Turning a setting off

Every option that takes no value has a --no- twin:

--no-z80n  --no-cspect  --no-case-insensitive  --no-warnings  --no-verbose  --no-gc-modules

They exist because the project file could otherwise only ever turn a setting on. With gc_modules = true in fantasm.toml, one build without it used to mean editing the file:

fantasm --no-gc-modules

The last flag given wins, so --gc-modules --no-gc-modules is off.

Diagnostics and output

⛔ -W turns on the unused-label sweep and nothing else. Every other warning is shown whether or not you pass it. The help text reads “Enable warnings (unused labels)”, which is accurate but easy to read as enable all warnings. See Diagnostics.

-n is what a script wants. It suppresses the banner, and also the throttled update notice, which is not something a build log should carry.

Testing

With several targets, counts are reported against the target the tests came from — see Building Several Images.

Standalone actions

--lsp is how an editor drives FantASM. It speaks JSON-RPC over stdin and stdout; the banner is not printed in this mode and logging goes to stderr, so --nologo is not needed. See The Language Server.

init

fantasm init
fantasm init --name starfield --target zxnext --format nex --main src/main.asm

Anything not given is asked for. FANTASM_INTERACTIVE=false suppresses every prompt and takes the defaults instead, which is what a script wants. Without --force, an existing fantasm.toml or source file stops it.

Environment

Exit status

0 on success. Non-zero if anything failed — including, with several targets, if any target failed or was skipped.

← Documentation