Build

  • Command Line — Every option, what it does, and the ones that surprise people — -u turning on one sweep rather than all warnings, the machine being a device rather than a target, and the --no- forms that exist because a project file could otherwise only turn a setting on. Also init, the environment variables and the exit status.
  • The Project File — fantasm.toml: getting one, what each table does, and what happens when the command line and the file disagree. Covers [project], [assembler], [defines], [lint], [artifacts] and [tasks], the precedence rules, and how a project keeps settings of its own in the same file without being told they are misspelt.
  • Output Formats — bin, hex, sna and nex — what each one is, which of the three places naming a format wins, and how to get code into a bank of a .nex so it is still there when the program runs. Also --reloc, for running a bin at an address it was not assembled for.
  • Building Several Images — target, for a program that is more than one file: a payload and the loader that incbins it, or a release and a debug variant. Declaring targets, depends and build order, --only and --all, what happens when one fails, per-target recipes and per-target test counts.
  • Building in Pieces — -f obj, for assembling one part of a program on its own and joining the parts with fantasm link. What separate compilation buys, section with its flags and placement options, extern as the other half of global, why an object has no origin, what an object build refuses, and the archive an ar makes. A call across pages is left as it was written, paging the target in being yours.