docs

Documentation

This repository is libmtlc, a reusable native compiler backend, plus Mettle, the reference frontend that drives it. The docs are organized the same way.

The backend: libmtlc

libmtlc owns the IR, the optimizers, code generation for four targets (x86-64 with AVX2, ARM64, NVIDIA PTX, SPIR-V), and linking. Any frontend can build IR and drive it through the public C API in include/mtlc/.

The libmtlc reference is the backend's own documentation set:

• Getting started: the tutorial (build IR, optimize, emit, link) with a complete non-Mettle example.
• API reference: every public function, with ownership, lifetime, error, and thread-safety contracts.
• The IR model: values, instructions, control-flow rules, module tables, and per-consumer IR shape requirements.
• The type system: MtlcType kinds, layout, canonical constructors, and the immortality contract.
• The pipeline: the optimizer pass families, the ML-opt validation gate, each code generator's product and limits, linking.
• Internals: source layout, self-containment invariants, and how to extend the backend.

Driver-facing views of the same machinery:

• Compilation: the mettle driver and its options.
• Linker and build pipelines: which linker runs for each --build combination.
• GPU offload: the PTX and SPIR-V targets from Mettle source.
• GPU architecture and acceptance contract: the GB10 / AArch64 target matrix, frontend/backend boundary, honest gap table, and the gates required before making parity or performance claims.
• ML-driven IR optimization, Translation validation, Profile-guided optimization: --ml-opt, --verify, --pgo.
• Runtime model: what emitted programs assume of the OS.
• Diagnostics: the frontend-neutral diagnostics reporter.
• The --explain-json schema: the machine-readable optimization report editors and analysis tools read.

A second, non-Mettle frontend that exercises the whole public API lives in examples/calc.

The reference frontend: the Mettle language

Mettle is a typed, assembly-inspired systems language. These document the language the reference frontend implements (see the language reference index):

• Lexical structure, Types, Declarations, Expressions, Control flow
• Modules, Imports, Standard library
• Heap allocation, Borrow checker, C interoperability
• Compile-time execution (mettle test / trace), Quick reference, Known limitations

Contributing

See CONTRIBUTING.md for the build/test workflow and the rules that keep the backend frontend-agnostic.