Home / Docs / Specification
16. Native backend
Status: Normative, v0.2 (ADR 0055).
1. Scope and refinement
una buildcompiles a package ahead of time into an executable through Cranelift and the system linker (cc). The executable runspub main() -> Unitof the entry module, the moduleuna runwould run (spec/13 §5). (v0.4, ADR 0124 step 3.) Onaarch64-apple-darwinthe linker is the one built intouna(§6), anduna buildruns no other program; on Linux (aarch64-unknown-linux-gnu,x86_64-unknown-linux-gnu) it stays the system linkerccuntil ADR 0124 step 4.- The supported targets are
aarch64-apple-darwin,aarch64-unknown-linux-gnuandx86_64-unknown-linux-gnu. Each host builds for itself; there is no cross-compilation in v0.2. (Informative, v0.4.0, #1903: the archives of release v0.4.0 are those ofaarch64-apple-darwinandaarch64-unknown-linux-gnu, the targets ofscripts/release-targets.txt; onx86_64-unknown-linux-gnu,unais built from source.) - The backend compiles every construct the interpreter runs, including kinds, lists,
OptionandResult, failures, handlers and host capabilities. - Refinement. The backend refines the UAM (spec/11 §1): for every program and host behavior, the executable's output, failure, abort and trace MUST be ones the UAM produces. The interpreter is the reference.
- Input. Its input is the Core IR of a package that checks at tier 1.
una buildrefuses a package with errors, asuna rundoes: it reports them and writes no executable.
2. una build
-
una build [path]checks the package at tier 1, asuna checkdoes (spec/13 §5). That includes U3012 for eachusesofmainthat no host capability, or no grant of[run] grantswhen it is listed, can provide. It then embeds[run] grantsin the executable as its default grants. -
It writes the executable to
target/una/<name>under the package root.<name>is the[package] nameofuna.toml, or the module name for a single file.--out <file>writes it to<file>instead. -
A package without an entry, or an entry without
pub main() -> Unit, is a usage error (exit code 2), as foruna run. So is a failure of the system linker, whose output goes to stderr. (v0.4, ADR 0124 step 3.) The internal linker's refusal of Una's own inputs (§6), the runtime built intounaamong them, is U8001, exit code 3; its refusal of the runtime file of a development build is a usage error; and an executable it cannot lay out is U7015, exit code 1; in both cases no executable is written. A failure to write the executable's file stays a usage error. -
Exit codes follow spec/13 §5 (ADR 0036):
0when the executable is written,1when the checks report errors,2for a usage error,3for an internal compiler error (U8001). -
With
--json,una buildprints, with keys in this order:json{"schema":"una.build/1","tier":1,"status":"built","target":"aarch64-apple-darwin","output":"target/una/hello","diagnostics":[]}statusisbuilt, orrejectedwhen the checks reported errors, whichdiagnosticsholds; thenoutputisnull.targetis the host target.
-
Without
--json,una buildprintsbuilt <output>on stdout. -
Slices. Until the backend compiles the whole language (#26), a construct it does not compile yet is a usage error, exit code 2.
una buildnames the construct on stderr, as in "the native backend does not compile calls of functions yet", and writes no executable. -
(ADR 0124 step 2.) The runtime. A release
unalinks the runtime library built into it, from the same commit and the same build, without debug sections, whose SHA-256 its build recorded (native.runtime_sha256of the report, spec/13 §6). It reads no file and no variable for the runtime:UNA_RT_LIBand alibuna_rt.ain any place have no effect, so a runtime older thanunacannot be linked. Before each link it checks the embedded bytes against that digest; bytes that are missing or differ are U8001, exit code 3, and no executable is written. Untilunalinks by itself (ADR 0124 step 3), it writes the runtime for the system linker into the private directory of the link, created for that build with mode 0700, as a new file of mode 0600, and removes it with the directory after the link, on every path except an end ofunaby a signal, which it does not catch (an interrupt included). A later build that writes its executable into the same directory removes such a leftover directory,.<name>.<process>.<serial>.una-tmp, when it is a directory owned by the same user and older than one hour; it touches nothing else. A development build (spec/13 §5), which has no runtime built in, reads it fromUNA_RT_LIB, else fromlib/libuna_rt.abeside theunabinary, next to the binary, or in../lib(ADR 0059 rule 2 and its amendment). -
(v0.4, ADR 0124 rule 27 and Question 7.)
--debuggable. Onaarch64-apple-darwinevery executable runs under the hardened runtime: macOS loads no library thatDYLD_INSERT_LIBRARIESnames into it, and no debugger or profiler may attach to it.una build --debuggableadds the entitlementcom.apple.security.get-task-allowto its signature, so that a debugger may attach; nothing else changes. With the system linker the flag has no effect.
3. The executable
-
Output contract. The executable follows the human contract of
una run(spec/13 §5):- the lines the program prints go to stdout as it prints them;
- U6001 (a failure of
main), U6003 (call depth, stack or memory exhausted), U6004 (a header value with a control character, spec/24 §1) and U6005 (host text that is not valid UTF-8, spec/14 §3) go to stderr, with exit code 1; - exit code 0 when
mainreturns. - (v0.2, #259.) A failure to write output exits with code 2, as in
una run. A closed stdout or stderr is not one: what the executable writes there is discarded, as/dev/nulldiscards it, and the exit code is the one an open stream would give. A broken pipe (EPIPE), a reader that went away, is a failure to write.
It has no
--jsonoutput in v0.2.Its rendering of U6001, U6003, U6004 and U6005 on stderr is compact: the first line, the code, the position and the failure are those of
una run, followed byat <file>:<line>:<column>and anote:line instead of a source frame. The comparison of §5 covers stdout, the exit status, the failure and the trace, not that rendering. -
Grants. The executable has the grants model of
una run(spec/13 §5):- Its grants are the
[run] grantsembedded at build time, together with its own--grant <spec>flags, which take the grant specs of spec/13 §5. - Before
mainstarts, it checks everyusesofmainagainst those grants. Ausesthey do not grant is U3012 on stderr, with exit code 1, and nothing runs. - Relative paths, those of embedded grants included, resolve against the executable's current directory, with the path rules of
una run. - (Edition 0.4 preview, ADR 0116.) For a package whose
ita.unahas adrivesection, the executable runs the driver of spec/26 §2, checks theusesofinit,stepandon_stopas it checks those ofmain, and takes--stop-after-iterations <n>asuna rundoes (spec/13 §5). Every executable takes--virtual-timeasuna rundoes (spec/13 §5, spec/26 §8): its clock is then the virtual one. - (Edition 0.4 preview, ADR 0116.) Executables take
--deadline <seconds>, from 1 to 31,536,000, and--stop-grace <seconds>, from 1 to 86,400 (default 10), asuna rundoes, and follow the host stops of spec/26 §6: an executable whosemainsaysdiverges, or that runs a driver, installs handlers of SIGINT and SIGTERM, and any other keeps their default actions. U6007 goes to stderr in the compact form of rule 1, with exit code 1, and the trace file is written. - A
--deadlineor--stop-gracethat is not a number or is out of its range, a--grantvalue that is not a grant spec, a--max-depth,--max-memory,--max-responseor--http-timeoutthat is not a number, a--max-memory,--max-responseor--http-timeoutof0, an--http-timeoutover 86400, a--max-depthwhose stack cannot be allocated, and a--workers,--task-depth,--io-threads,--file-threadsor--serve-threadsthat is not a number or is out of its range (spec/27 §3, spec/31 §6 rule 1), and--virtual-timewith aserve:grant and no--serve-script(spec/31 §6 rule 14), and the cases of--serve-scriptand--serve-outin spec/31 §8 rule 6, are usage errors, exit code 2, as foruna run. Key files are read after the check ofuses, asuna runreads them, and an unreadable or invalid one is then a usage error too.
- Its grants are the
-
Depth and memory.
--max-depth <n>bounds the call depth as in spec/11 §7, with the same default, on a stack capped at 1 GiB. Exceeding it, or running short of stack before it, aborts with U6003; the executable never overflows its stack. (v0.2, ADR 0061.)--max-memory <MiB>bounds the heap of the run as in spec/11 §7, with the same default, and exceeding it aborts with U6003,this call exceeds the memory limit of N MiB. (v0.2, ADR 0113, 2026-10-15.) The copies atogetherblock makes check the budget before each allocation, and a refusal aborts with U6003 at the block,this call exceeds the memory limit of N MiB. A task whose stack cannot be mapped aborts with U6003 at the block,a task of `together` could not run. The threads of a program that holds a task construct or afor everstart beforemain(spec/27 §1 rule 4), so no task waits on a thread's start: when one of them cannot start, or a stack of the pool that is filled with them cannot be mapped, the run stops beforemainwith U6003, exit code 1, no position and the messagethe threads and stacks of this run's tasks could not be made. (ADR 0117, amendment of 2026-10-25.) The stack each task uses counts toward--max-memory(spec/27 §4). An export of more than 4294967295 objects aborts with U6003 at the block, and a retain past 4294967295 references to one value ends the process with U6003, exit code 1, when the run's heap and stacks hold at least (2^32 − 1) × 8 bytes, else with U8001, exit code 3, with one line on stderr, no site and no trace file. A panic of the runtime during a copy is U8001, exit code 3. -
Traces.
--trace <file>writes the trace of spec/11 §5 to<file>as a JSON array of events. Without the flag the executable records no trace. (Edition 0.4, ADR 0117 rule 10.) The file is made beforemainstarts, a file that cannot be made being a usage error, and each event is written as it is,]closing the array when the run ends (spec/27 §8).
4. Runtime representation
The representation is not observable; these rules fix what the runtime library una-rt, which every executable links, provides.
- Values. Heap values (records, variants with payloads, lists,
Text, arbitrary-precision integers, closures) are reference counted, non-atomically.- A value is freed when its last reference is released.
- Values are immutable, and the language has no mutable aliasing, so no reference cycle can form, and nothing leaks.
Textis UTF-8.
Int. AnIntis a tagged 63-bit integer in a machine word, and an operation whose result does not fit promotes it to an arbitrary-precision integer.- A value whose range a refinement proves MAY be a plain machine integer, with no tag and no check.
- Arithmetic is mathematical, with Euclidean division and remainder, as in spec/11.
- Failures are returned values, a tag and a payload. Nothing unwinds.
- Capabilities are passed explicitly, as Core IR passes them (spec/09). Handlers and
withcompile to environment passing, and a capability is never a runtime value a program can store.- (v0.2, ADR 0066.) A function with constrained type parameters also takes a hidden type descriptor for each of them, and is still compiled once (spec/20 §7).
- Host capabilities (spec/14 §3) have the interpreter's semantics, grants, path rules and failures.
- (v0.2, ADR 0065.) Tasks. Each task of a
togetherblock runs on its own thread with its own heap; values are copied at the fork and the join, so reference counts stay non-atomic (spec/19 §8). - (v0.2, #30.) Updates in place. Within the freedom of spec/17 §7 rule 3, an update MAY happen in place when the code gives up the value at its last use and its reference count shows nothing else holds it. Otherwise the value is copied.
- Which updates:
appendandseton a list, and a record or variant rebuilt from one of its kind that dies there, as a field edit is. (v0.2, ADR 0069.) Alsosetandremoveon a map, kept in Rust's standardBTreeMap(spec/21 §5). (v0.2, ADR 0070; implemented after v0.2.0 (#261).) Also a text rebound to an interpolation that begins with it, which appends in place (spec/22 §6). (v0.2, ADR 0072.) Also an argument that moves into its callee, which the callee may update in place. - Never moved: a value something borrows from, which is a
whenscrutinee, alet (...)tuple or a list a loop visits. Nor a value atogethertask captures. - Arguments (v0.2, ADR 0072). An argument moves into the callee when the caller never reads its binding again, including in the code that a failure of the call reaches (a handling clause, or what follows an
attempt), and when it is not passed twice in that call. Any other argument is borrowed, and the callee copies it to update it.- A function of the package owns each parameter it consumes: one that reaches an update in place, an owned parameter of another function, or a loop state that does, directly or through an alias. The owned parameters are a least fixpoint over the package (borrow inference). Its other parameters are borrowed.
- At a call, an argument for an owned parameter moves when it can, and is retained otherwise. The callee releases an owned parameter at the end of its body, or moves it at its last use.
- (v0.2.) A lambda owns every parameter, and so does the lambda that a function used as a value stands for, whose call of the function moves its arguments into the function's owned parameters and releases the others. So a call through a function value moves or retains each argument as a call of a function does.
foldmoves its state into the step, andmap,filter,first_whereandfoldretain each item they give it. A call through a function value whose target only borrows costs one retain at the caller, when the argument is still needed there, and one release in the lambda. - The parameters of a handler's operations are borrowed.
- Not observable: in-place updates change no output, failure, abort or trace.
- Which updates:
- Trusted base.
una-rtis in the Trusted zone (charter §3). Its onlyunsafecode of the repository isffi.rs(ADR 0058), and its heap budget (§3, ADR 0061) depends on thecapallocator crate, whoseunsafecode is outside that boundary and is trusted with it (ADR 0061 amendment of 2026-10-06).
5. Equivalence testing
The repository's CI runs every runnable program of its suites twice: in the interpreter, and as a native executable built on the CI host. This covers the examples, the conformance cases that run, and the adversarial programs of the reviews.
The output, the exit status, the failure and the trace (--trace) MUST be identical. A divergence fails CI. (v0.2, ADR 0065.) A run that starts concurrent tasks is compared as spec/19 §8 rule 4 says: the lines that tasks print may interleave in any order, and the trace is identical unless a task after a failed one had started. (Edition 0.4 preview, ADR 0116 rule 19.) Two runs on the real clock read Clock.now at different moments, so their comparison sets those readings aside. Under --virtual-time in both engines, it does not: the readings MUST be identical too (spec/26 §8). (Edition 0.4, ADR 0117 rule 12.) Under --virtual-time, a run with first of MUST give the same winner, output, failure and trace in both engines, which run its branches in index order, each to its end, up to the first that returns (spec/27 §6); under the real clock, a run in which the winner of a first of decides the outcome is compared only for being an outcome the UAM allows under some timing. Under --virtual-time, a run with tasks and start MUST give the same output, exit status, failure and trace in both engines, which follow the schedule of spec/27 §8; an executable built with check elision refuses --virtual-time. Under the real clock, the events of started tasks are in the order of real time, so a run with them is compared task by task: each task's events and lines in its own order, the instance ids of installations up to one renumbering of the run (spec/27 §8 rule 4), the same set of tasks, and the same exit status and failure.
6. Linking
(v0.4, ADR 0124 rules 22 to 29 and 34, step 3.) On aarch64-apple-darwin, una build links the executable with una-link, inside una.
- Inputs. The program's object, which
una buildcompiles and never writes to disk, and the runtime archive built intouna(§2 rule 8), read in place. No object, archive or library that a package or a user names is ever an input. - Resolution. The program's object is read first, then each member of the runtime whose symbol table entry defines a symbol undefined at that point, to a fixed point; among members that define a symbol, the first in archive order wins. Two strong definitions of one symbol are U8001 naming both inputs, unless both are private to the linkage unit (private extern), which keeps the first; a weak definition yields to a strong one.
__mh_execute_headeris the only symbol the linker defines, and an input that defines it is U8001. A symbol that no input defines is bound to/usr/lib/libSystem.B.dylibwhen the export list of libSystem built intounaholds it (supply-chain/libsystem.lock, generated from the macOS 12.1 SDK'slibSystem.B.tbd; that each of its symbols is exported by the libSystem of macOS 13 is assumed from that SDK and not yet checked on a macOS 13 system, which themacos-oldestgate of ADR 0124 rule 31 is to do), and is U8001 naming it otherwise. Code and data thatmain, the initializers and what an input marks as never stripped do not reach through relocations are not written, so an executable that never usesHttpholds no TLS stack (ADR 0074 H7). - Relocations. The supported types are those the scan of the inputs finds (
scripts/scan-relocations.sh):ARM64_RELOC_UNSIGNED,SUBTRACTOR,BRANCH26,PAGE21,PAGEOFF12,GOT_LOAD_PAGE21,GOT_LOAD_PAGEOFF12,POINTER_TO_GOT,TLVP_LOAD_PAGE21,TLVP_LOAD_PAGEOFF12andADDEND. Any other type is U8001 naming the type, the input and the section. AnARM64_RELOC_UNSIGNEDpointer is allowed only in__DATAor__DATA_CONSTat an 8-aligned place, where it becomes a chained fixup; a pair ofSUBTRACTORandUNSIGNEDis resolved at link time anywhere. Every relocation's place, with its width, lies inside its own section, every defined symbol inside its section, and input sections do not overlap; a violation is U8001. A branch beyond ±128 MiB, a page reference beyond ±4 GiB, an image of 4 GiB or more, and an__eh_frameof 16 MiB or more are U7015. Relocations of debug sections, which the executable does not contain, are ignored. - The executable. A Mach-O executable for macOS 13 and later, position-independent, whose segments are
__PAGEZERO,__TEXT(read and execute),__DATA_CONST(read-only after the fixups),__DATA(read and write) and__LINKEDIT, none both writable and executable, and whose stack is not executable. It links/usr/lib/libSystem.B.dylibalone, every import bound at load through chained fixups (DYLD_CHAINED_PTR_64), with no lazy binding; calls to libSystem go through stubs that load a read-only GOT slot. Its load commands are those of ADR 0124 rule 25 and no other: noLC_RPATH, no source version, nothing that names the building machine. It carries__unwind_infoand the__eh_framerecords of its functions, so the runtime's panics are caught at its boundary; no debug information; and a symbol table of the functions and data it holds. Its last bytes are an ad-hoc signature with the hardened runtime: one CodeDirectory of version 0x20500, flagsadhoc,linker-signedandruntime, SHA-256 hashes of its 4 KiB pages, the identifier the output's file name, and, with--debuggableonly, an entitlements blob. ItsLC_UUIDis the first 16 bytes of the SHA-256 of the file with the UUID and the signature zeroed, as a version-4 UUID. A user who distributes it may replace the signature with their own. - Determinism. The executable is a function of the inputs' bytes, the version of
una, the output's file name and--debuggable: no path, user name, time or random value is written, so two builds of one package from two directories write the same bytes (the tests build it from two directories, and the release check from two installations), and two output names change only the signature. - The verifier. Before it is written, every executable is read back and refused with U8001 unless: its header names an arm64 position-independent executable whose stack is not executable; no segment is writable and executable and
__DATA_CONSTis read-only after the fixups; its load commands are those of rule 4; every chained fixup lies 8-aligned inside its page of a writable segment, a rebase reaching the image and a bind an import; every import is in libSystem's list; its UUID is its digest; and its signature's code limit is its offset and its page hashes match its bytes. - Development builds. A development build of
una(spec/13 §5) also readsUNA_LINKER:cclinks through the system linker as before ADR 0124 step 3, for the tests that compare the two, andinternalthe internal linker. A releaseunaignores the variable.