Project configuration

For anything beyond a single file, FantASM supports a project workflow driven by a fantasm.toml file. It gathers every assembler setting, include path and define into one place, so a bare fantasm command builds the whole project. Create one with fantasm init.

Example fantasm.toml

[project]
name = "MyAwesomeGame"
version = "1.0.0"
main = "src/main.asm"
output = "dist/game.nex"

[assembler]
target = "zxnext"
format = "nex"
z80n = true
cspect = true
case_insensitive = false
include_dirs = ["include/", "lib/"]
origin = 0x8000
max_code_size = 65536
warnings = true
verbose = false

[defines]
DEBUG = 1
RELEASE = false
BUILD_ID = "2024-A"

[artifacts]
labels = "dist/labels.txt"
sld = "dist/game.sld"

[tasks]
pre_build = ["echo Preparing assets"]
post_build = ["echo Done"]

Sections

SectionDescription
[project]Core metadata. main is the entry point; name and version are exposed to your source as the __NAME__ and __VERSION__ defines.
[assembler]Mirrors the command-line flags — every field is optional.
[defines]Key/value pairs that become constants in your assembly.
[artifacts]Output paths for generated metadata such as label and SLD files.
[tasks]Optional pre_build / post_build arrays of shell commands.

Precedence & path resolution

  1. CLI beats project. Explicit command-line arguments always override values in fantasm.toml.
  2. Paths are relative to the file. Everything in fantasm.toml resolves relative to the directory containing the project file — not your current working directory.
  3. Auto-detection. Run fantasm with no source argument and, if a fantasm.toml exists in the current directory, it’s used automatically. You can also point at one explicitly with -p, --project.