The nanofil command line: the impure driver that reads a C or IR file, runs it through the compiler's stages and prints the result.

Commands

A FILE ending in .c or .i goes through the C frontend, one ending in .nfb is NFB, and any other FILE is IR text. A .c file is preprocessed with the predefined macros and include paths of $FILCC (default filcc).

cc runs the whole pipeline; c_pp lexes with c_lex. IR text enters at the middle end, and a module in plain mode goes to amd64.pl instead of pizlonate and filc_amd64.

-O

-O before the command runs the middle end (opt.pl) after loading. Without it the IR goes to the backend as loaded, which is the reference the optimized path is checked against. With -O, difftest also runs every run line on the unoptimized module and fails unless each optimized outcome refines the original one (translation validation), and prints how many allocs promote removed.

--registers=stack|temps|pointers independently selects reference emission or validated whole-function register homes for scalars with validated register operands and frame cells, on a frame with a home per scalar temporary (docs/perf.md items 3, 5a-loads and 3d), in the Fil-C backend. Pointers is temps with pointer address words as homes too, their lowers staying in the frame record (docs/perf.md 5b-2). The default is pointers with -O and stack without it; NANOFIL_REGISTERS supplies the same choice to build harnesses, -O --registers=temps keeps scalar homes only, and -O --registers=stack keeps the reference emission. The modes local, function, operands, cells and flow were retired in October 2026 (docs/perf.md, register modes) and are refused. The plain backend is unchanged. Options precede the command.

--operands=rewrite|regions selects, under temps or pointers, how each straight-line region's operands are chosen once the homes are in registers: rewrite, step 3b's forwarding of copies, or regions, which selects each region's registers again from the values the validated stream computes, operating on homes directly, with lea and three-address forms (docs/perf.md item 19). Both are checked by the same operand checker. The default is regions; NANOFIL_OPERANDS supplies the same choice.

--registers-limit=N (or NANOFIL_REGISTERS_LIMIT), opt-in, emits each function of more than N checked IR instructions by the reference (stack) emission when registers are temps or pointers, to save compile time on very large functions (docs/perf.md, compile time).

--branches=reference|selected independently selects the reference branch on a stored boolean, or a branch on the flags of a compare that only the branch reads, with jumps to the next block left to fall through (docs/perf.md). The default is selected with -O and reference without it; NANOFIL_BRANCHES supplies the same choice, and -O --branches=reference keeps the reference branches.

--memcpy=call|inline independently selects the reference call for every memcpy and memmove, or, for a constant 1 to 16 bytes to a function the module does not define, an inline copy in front of that call, taken only when the runtime's checks would pass and neither object has aux (docs/perf.md item 7a). The default is inline with -O and call without it; NANOFIL_MEMCPY supplies the same choice, and nanofil-cc passes call for -fno-builtin, -fno-builtin-memcpy, -fno-builtin-memmove and -ffreestanding.

--bounds=split|merged|sign|or selects the bounds check's shape: split, the default, tests ptr < lower and ptr > upper - Size with a branch each; merged tests both with one unsigned comparison of ptr - lower; sign and or test (ptr - lower) | (upper - Size - ptr) with one branch (docs/bounds.md). NANOFIL_BOUNDS supplies the same choice.

--share=none|block|null|upper shares parts of heap checks of one object under split bounds and local selection: block leaves out the null test of a check whose lower an earlier check in its block tested, null also when that check is in a dominating block, and upper also reuses the upper a check of the same object just loaded (src/check_share.pl, docs/perf.md item 17). The default is upper with -O, except with --checks=reference, and none otherwise; NANOFIL_SHARE supplies the same choice.

--lowers=own|shared selects the frame's GC roots: own, the default, gives every pointer temporary its own lowers[] entry; shared lets a flight use its lower root's entry, kept while the flight is live, and validates every frame (src/lower_roots.pl, src/lowers_check.pl, docs/lowers.md). NANOFIL_LOWERS supplies the same choice.

--inline=none|small|wide independently selects no inlining, or, with -O, inlining of small static functions before promotion (src/inline.pl, docs/perf.md item 4), or that and more: always_inline, single-call-site and non-leaf callees, callees first (item 20). The default is wide with -O; without -O nothing inlines. NANOFIL_INLINE supplies the same choice, and nanofil-cc passes none for -fno-inline and -O0. A trap inside an inlined function reports its caller's name, as filcc -O2 does without -g.

--simplify=none|full independently selects, with -O, the cheap middle end after copy propagation (src/simplify.pl, docs/perf.md item 8). The default is full; NANOFIL_SIMPLIFY supplies the same choice.

--checks=reference|reuse|renew|guard|hoist|schedule|half|forward|combined|hull|getter|extended independently selects the reference checked IR, a check before every access, check reuse after pizlonation, reuse followed by renewal of dominated checks, both followed by range guards for checks in loops, both followed by hoisted bounds, a limit taken before a loop for its full checks of a root defined before it, or both followed by scheduled checks, which check early the bytes every path ahead needs and renew what they cover; a scheduled check may trap before stores that precede the failing access, or both followed by half checks, which test only the bound an earlier check of the object does not already establish, or reuse that also serves pointer loads and covers a check by the hull of its object's live facts, then renewal, which moves no trap, or that followed by half checks (combined), combined with renewal by the hull of two checks (hull), with facts kept across repeated getters of local globals (getter), or both (extended) (src/check_reuse.pl, src/schedule.pl, src/half_check.pl, docs/m7.md, docs/bounds.md, docs/schedule.md, docs/half.md, docs/forward.md). The default is combined with -O and reference without; NANOFIL_CHECKS supplies the same choice. With any but reference, cc, compile and difftest's pizlonation comparison use that module.

GNU vector types and the SSE through AVX2 intrinsics (docs/vector-access.md) are on; --no-vectors (or --vectors=off) turns them off, refusing every vector type, and --vectors (or --vectors=on) turns them back on; the last one given wins. NANOFIL_VECTORS=0 or 1 supplies the same choice.

difftest

expected.txt holds the interpreter's result for every run line whose outcome a native run can reproduce: a known return value, or for a Fil-C module a trap, written just trap. harness.c prints the same lines from native code; for a Fil-C module it makes one call per process, chosen by argv[1], since a trap ends the process. mode holds plain or filc. Other outcomes are reported on stdout and left out of the comparison.

For a Fil-C module, difftest also runs every run line on the pizlonated module and fails unless each outcome is the same, traps and their reasons included.

release_stacks: collect garbage and return unused stack memory to the system between the stages of a large compile. SWI grows its stacks between collections and keeps them grown, and its stack limit counts what is allocated, not what is live: gnulib's test-intprops.c, whose main has 87,000 blocks, never has more than about 210 MB live, yet the frontend leaves the trail at 250 MB and the middle end the global stack at 1 GB, and the next collection, which must shift them first, exceeds the default 1 GB limit. A host without these predicates skips them.