Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

Adding a target: follow the C backend

Targets are statically wired Rust crates and explicit dispatch arms, not runtime plugins. There is no universal backend registration function. HIR source emitters, MIR consumers, and artifact serializers have different boundaries. This chapter traces the existing radix-hir-c integration as an engineering checklist; it does not authorize changes to Faber syntax, semantics, types, Norma names, or locale surfaces.

Read the overview, HIR contract, and MIR contract before choosing a boundary. A new target must implement the existing language faithfully or reject unsupported constructs by name; it must not quietly narrow the language or compensate for missing upstream analysis. Language-surface changes require separate approval.

The C route in one table#

LayerExisting C integration
IdentityTarget::HirC, spelling c, required feature hir-c in radix-target.
Leaf crateradix-hir-c/Cargo.toml.
Leaf APICCodegen, COutput, and impl Codegen in lib.rs.
Shared trait/errorCodegen, associated Output, and CodegenError in radix-codegen-shared.
Module re-exportcodegen/c/mod.rs.
Analyzed dispatchgenerate_from_analyzed_with_options and generate_c_from_analyzed in codegen/mod.rs.
Driver outputFeature-gated Output::C and module-owned COutput in radix-module/src/lib.rs.
Text extractionoutput_code in services/emit.rs.
Capability/extensionC row and c extension in services/targets.rs.
Product selectionFaberCliTarget::HirC in cli/emit.rs and target_gate.rs.
Output policycommands/emit.rs and postprocess.rs.
Runtimeruntime/c/faber.h, selected by helpers.rs.

1. Choose the representation, not just the extension#

C is a HIR source emitter. It consumes analyzed source structure and semantic types, produces a C translation unit, and does not invoke a C compiler. A MIR backend instead starts from ValidatedMir and is routed by the driver; see the Cranelift entry points. FHIR/FMIR are artifact formats with codec and reconstruction contracts, not ordinary HIR Codegen implementations.

Do not make the HIR trait pretend it can execute a program, build a native binary, or serialize every representation. Select the existing boundary that owns the required facts.

2. Keep the emitter a leaf#

C's manifest depends on neutral data and utility crates, not the module driver or semantic pass coordinator in normal dependencies. Its dev-dependency on radix-module is for compiling focused fixtures through the real pipeline, not for production re-analysis.

The existing HIR trait contract is:

// Excerpt of radix_codegen_shared::Codegen, not a new interface.
pub trait Codegen {
    type Output;

    fn generate(
        &self,
        hir: &HirModule,
        types: &TypeTable,
        interner: &Interner,
    ) -> Result<Self::Output, CodegenError>;
}

The excerpt uses HirModule from radix_hir, TypeTable from radix_types, Interner from radix_lexer, and CodegenError from radix_codegen_shared. C's output type contains the generated code: String. CCodegen::new builds a NameCatalog from the module and interner; dispatch installs the analyzed module's display tokens before calling generate.

The module layer's wider CodegenAnalysis view also exposes effects, imports, provenance, shape obligations, and carried provider analyses. Consume the facts a target needs through an explicit contract. Do not reconstruct type decisions, resolve imports from the filesystem, or re-enter semantic analysis from a leaf. A backend needing additional facts requires a deliberate engineering change to the boundary, not a hidden global table.

How C divides emission#

The leaf's lib.rs owns the emitter context and program assembly. More focused decisions live in:

CCodegen::generate rejects recovery HIR and emits once to discover whether allocation occurs. If it does, emission runs again with an explicit arena parameter threaded through the generated functions. This is a current C implementation strategy, not a requirement on every HIR backend.

3. Wire identity, features, dispatch, and output together#

Use C's complete path as the review checklist:

  1. Neutral identity: review Target, Target::ALL, canonical spelling and parsing, availability spellings, required_feature, is_available, and target-policy methods in radix-target. Identity must not depend on backend implementation crates. A new enum arm must get an explicit policy answer, not fall through a permissive wildcard.
  2. Cargo availability: the module's hir-c feature enables the optional leaf dependency and forwards the identity feature. Forwarding continues through radix-program, radix, and faber. Check radix-module's manifest and radix-target's manifest too. hir-c is outside full-targets but explicitly in faber's default feature list. A generic “default-off everywhere” description would be wrong.
  3. Analyzed dispatch: expose the leaf under its feature and route Target::HirC to generate_c_from_analyzed. That adapter constructs the emitter, supplies display tokens, invokes the trait, and wraps the leaf's output in the module's Output::C. The leaf and module have distinct COutput carriers; the adapter copies the code field, not the carrier type. Preserve an unavailable-target error arm in builds without the feature.
  4. Driver family: inspect generate_output in driver/mod.rs. C belongs to the HIR group that calls shared analyzed dispatch, not the MIR-lowering group. The driver also handles CLI entry and target qualification before ordinary dispatch; adding an emitter arm alone does not admit every entry form.
  5. Artifact consumption: update output payload handling, text extraction, extension metadata, and any reflection/binary handling actually needed by the output family. C is text; native objects are not text strings.
  6. Product surface: review CLI target conversion, the product compiled-in gate, and reported capabilities. Match reported support to real routes. Target selection and an emitter trait implementation do not automatically create a package builder or run command.

The C capability row currently reports file check/build support and no run/package support. Package planning also rejects C through its unsupported-target branch. Do not advertise package support until graph linking and artifact assembly genuinely exist.

4. Fail closed with structured facts#

Shared dispatch rejects poisoned HIR, applies shared gates, and checks availability. These checks do not replace leaf-specific subset checks. C's unsupported helper returns CodegenError with named arguments:

issue     = c_target_unsupported
construct = the unsupported construct's name
target    = c

The driver converts emission failures into diagnostics; C test support checks CODEGEN001 plus the issue/target/construct facts and requires no output on rejection. Tests should not match localized message fragments. Shared gates or earlier analysis can reject before the C leaf, so not every failed C compile necessarily carries c_target_unsupported.

Target-specific rejection is not permission to approximate accepted constructs. C must account for unspecified operand evaluation order, integer overflow, aliasing, trapping, and allocation. Its exact arithmetic and store helpers are implemented in the runtime header; do not replace them with unchecked signed C arithmetic simply because the target compiles it. This manual does not establish that every accepted construct is free of defects.

5. Separate runtime delivery and external tools from emission#

helpers.rs tracks runtime use and selects #include "faber.h" when needed. The header is static inline support; the emitter writes program-specific declarations, functions, and entry code. build.rs includes runtime/c among the embedded runtime roots; embedded_runtime.rs materializes those sources at the product boundary. The leaf does not launch GCC or Clang.

A downstream C build must provide the header include directory. The runtime uses compiler extensions such as __int128; it is not a promise of support for every ISO C implementation. Float programs may require linking the host math library. Emission, host compilation, execution, and sanitizer checks are separate proofs. External-tool orchestration belongs at the product/harness layer, not in a reusable compiler leaf.

6. Prove the narrow boundary you changed#

C has public, focused examples of complementary proof styles:

ProofExisting location and what it establishes
Emitted shapeemit_test.rs, including scalars_program_is_pinned, compares generated C with committed text.
Named rejectionreject_test.rs and test_support.rs assert failure identity and absence of output.
Semantic hazards in shapecontrol_test.rs pins break/switch behavior; other companion tests focus on their own constructs.
Host runtime behaviorruntime/c/tests/faber_test.c exercises the header independently of HIR dispatch.
Production-source constraintstests/hygiene.rs checks the leaf's production budgets.

For an emitted-shape-only edit, a single named Rust test is a useful first proof, for example cargo test -p radix-hir-c scalars_program_is_pinned. A changed runtime operation additionally needs the relevant runtime case and a single end-to-end emitted-program comparison, including output, status, and trap behavior where applicable. A feature-wiring edit needs enabled and disabled builds and capability assertions. Do not substitute a broad corpus sweep for a specific missing boundary proof, or count an output snapshot as execution proof.

These are validation recommendations, not claims that builds or tests ran for this documentation change. Platform/toolchain support beyond inspected code and focused executable evidence remains unverified.