wehub-resource-sync
e7738de6d2
CI / Deep Native Runtime Cases (1/6) (push) Has been skipped
CI / Native Preflight (push) Failing after 1s
CI / Native Runtime Cases (1/2) (push) Failing after 0s
CI / Native Runtime Cases (2/2) (push) Failing after 1s
CI / Native Metadata Reports (push) Failing after 0s
CI / Native Direct Backend Artifacts (push) Failing after 0s
CI / Native Sanitizer Smoke (push) Failing after 1s
CI / Command Contract Snapshots (push) Failing after 1s
CI / Deep Conformance Suite (push) Has been skipped
CI / Graph Build Perf (push) Failing after 1s
CI / Deep Native Preflight (push) Has been skipped
CI / Deep Native Runtime Cases (2/6) (push) Has been skipped
CI / Deep Native Runtime Cases (3/6) (push) Has been skipped
CI / Conformance Suite (push) Failing after 1s
CI / Workspace Checks (push) Failing after 0s
CI / Deep Native Runtime Cases (5/6) (push) Has been skipped
CI / Deep Native Runtime Cases (6/6) (push) Has been skipped
CI / Deep Native Runtime Cases (4/6) (push) Has been skipped
CI / Deep Graph Build Perf (push) Has been skipped
114 lines
4.4 KiB
Markdown
114 lines
4.4 KiB
Markdown
# Backend Contract
|
|
|
|
Zero backend selection is a compiler contract below the typed program and MIR.
|
|
The parser, checker, ProgramGraph, canonical source, and semantic facts must not
|
|
depend on a backend family.
|
|
|
|
## Selection
|
|
|
|
Backend selection has these dimensions:
|
|
|
|
- target: a supported Zero target name such as `linux-musl-x64`;
|
|
- backend family: `direct` or `llvm`;
|
|
- backend emitter: an implementation-specific emitter such as `zero-elf64`;
|
|
- artifact kind: `exe`, `obj`, or `llvm-ir`.
|
|
|
|
`direct` is the default backend family. A missing `--backend` means `direct`.
|
|
`--backend direct` also selects the direct family without selecting a specific
|
|
direct emitter. Direct emitter names such as `zero-elf64` remain exact direct
|
|
backend requests.
|
|
|
|
`llvm` is a known experimental backend family. It is explicit-only: it is not
|
|
the default backend and not release eligible. Direct emitters remain the
|
|
supported release path. LLVM can emit deterministic textual LLVM IR when
|
|
selected with `--backend llvm --emit llvm-ir`. Native LLVM executable artifacts
|
|
are buildable only for supported host targets with a ready clang toolchain.
|
|
LLVM lowering currently supports scalar code, direct calls, branches, loops,
|
|
primitive fixed arrays, byte views, readonly strings, and primitive `std.mem`
|
|
helpers. Native LLVM object output, unsupported targets, and unsupported MIR
|
|
constructs must report a structured backend blocker; they must not fall back to
|
|
direct emitters.
|
|
|
|
Textual LLVM IR artifacts that reference Zero runtime helpers must report that
|
|
dependency in `objectBackend.linking.targetLibraries` and
|
|
`objectBackend.linkerPlan.staticLibraries`. Emitting the `.ll` file still does
|
|
not compile or link the runtime object.
|
|
|
|
`zero size --backend llvm` is a metadata report, not a build fallback. It may
|
|
report LLVM target triple, optimization level, retained runtime/helper facts,
|
|
and direct-vs-LLVM comparison rows without writing a native artifact.
|
|
|
|
Unknown backend names are command errors. Known-but-unavailable backend names
|
|
are buildability errors.
|
|
|
|
## MIR Input
|
|
|
|
Backends consume Zero MIR. They do not lower from source tokens, parser trees,
|
|
checker scopes, or generated textual views. MIR input must carry enough facts
|
|
for backend diagnostics to explain the unsupported construct, target, object
|
|
format, selected backend, and failing stage.
|
|
|
|
MIR verification remains backend-independent. Backend-specific buildability
|
|
checks may reject a verified MIR program when the selected backend cannot lower
|
|
the selected feature or artifact kind.
|
|
|
|
## Readiness
|
|
|
|
Target readiness answers whether the selected target, backend family, emitter,
|
|
artifact kind, and MIR subset are buildable.
|
|
|
|
Readiness JSON must include:
|
|
|
|
- `target`;
|
|
- `emit`;
|
|
- `objectFormat`;
|
|
- `backend`;
|
|
- `stage`;
|
|
- `languageOk`;
|
|
- `buildable`;
|
|
- structured diagnostics with optional `backendBlocker`.
|
|
|
|
The `backendBlocker` fields are:
|
|
|
|
- `target`;
|
|
- `objectFormat`;
|
|
- `backend`;
|
|
- `stage`;
|
|
- `unsupportedFeature`.
|
|
|
|
## Diagnostic Stages
|
|
|
|
Backend diagnostics distinguish these stages:
|
|
|
|
- `backend-selection`: the backend family is known but unavailable;
|
|
- `target-selection`: the backend family does not support the target;
|
|
- `lower`: MIR contains a feature the backend cannot lower;
|
|
- `buildability`: the backend cannot build the selected artifact kind or entry
|
|
shape;
|
|
- `toolchain`: an external backend toolchain is required but missing;
|
|
- `emit`: a backend invariant failed after buildability accepted the program.
|
|
|
|
`BLD002` is used for unknown backend names. `BLD004` is used for ordinary
|
|
backend blockers. Code generation invariant failures remain `CGEN004`.
|
|
|
|
## Target Facts
|
|
|
|
`zero targets` exposes backend families separately from direct emitter facts.
|
|
`directBackend` remains the detailed direct-emitter record. `backendFamilies`
|
|
reports the default family, known families, currently available families, and
|
|
the no-fallback policy.
|
|
|
|
LLVM facts may claim textual IR emission and host executable output only when
|
|
Zero can build the selected artifact through the LLVM path for that target.
|
|
LLVM facts must also carry `backendLifecycle` so tools can distinguish explicit
|
|
experimental readiness from supported release eligibility.
|
|
|
|
## Fallback Policy
|
|
|
|
Backend fallback is never implicit:
|
|
|
|
- direct requests do not fall back to LLVM;
|
|
- LLVM requests do not fall back to direct;
|
|
- removed C backend flags do not act as a debug or compatibility path;
|
|
- graph and source entry points follow the same backend contract.
|