docs: add libVCT public specification set (000-015)
This commit is contained in:
@@ -0,0 +1,117 @@
|
||||
# 000 — Overview
|
||||
|
||||
- **Status:** Draft
|
||||
- **Normative language:** `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` are to be
|
||||
interpreted as described in RFC 2119.
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
libVCT (the **Vox C Transpiler Library**) is a compiler library written in D. Given a program's
|
||||
IR, libVCT optimizes that IR, transpiles it to C17, and drives a system C compiler to produce an
|
||||
object file. An alternate backend emits textual LLVM IR instead of C.
|
||||
|
||||
libVCT is a **library**, not a compiler. A frontend embeds it, builds IR through its builder API,
|
||||
and receives either C source or LLVM IR back. libVCT never links object files into an executable;
|
||||
that is the caller's job, with the single opt-in exception of `-mangled` mode
|
||||
(see [010 — Driver & CLI](010-driver-cli.md)).
|
||||
|
||||
## 2. The two-stage IR thesis
|
||||
|
||||
libVCT is organized around **two IRs**:
|
||||
|
||||
- **HIR**: a high-level, tree-shaped AST. The frontend constructs it; libVCT annotates it *in
|
||||
place* with **traits**. HIR performs discovery and small, cheap folds.
|
||||
- **VIR**: a low-level SSA/CFG instruction IR. VIR performs the heavy transformations and
|
||||
performs **no discovery**; it is a strict consumer of the traits HIR produced.
|
||||
|
||||
The design thesis: because HIR hands VIR a complete, annotated "dictionary" of facts, VIR can skip
|
||||
analysis and go straight to transformation. HIR's cheap folds cascade and parallelize per function,
|
||||
and the VIR that results is smaller and faster to optimize. The intended result is LLVM-class
|
||||
codegen quality at materially lower compile time.
|
||||
|
||||
## 3. Goals
|
||||
|
||||
1. **Codegen quality is the headline.** Generated code quality takes priority over compile speed.
|
||||
2. **Two-stage optimization.** HIR performs small folds and trait derivation; VIR performs large
|
||||
transformations.
|
||||
3. **Trait-driven VIR.** VIR never re-analyzes. Every fact it uses is an attribute, relationship, or
|
||||
request supplied by HIR.
|
||||
4. **Parallel, cascading HIR.** HIR passes run per function in parallel and cascade to a fixpoint.
|
||||
5. **Compiler-friendly C.** The C backend always emits C written to be pattern-matched by GCC and
|
||||
Clang.
|
||||
6. **Deterministic output.** The same input and configuration produce byte-identical output,
|
||||
regardless of thread count.
|
||||
|
||||
## 4. Non-goals (v1)
|
||||
|
||||
- **Linking.** libVCT produces object files; linking is the caller's job. The sole exception is
|
||||
`-mangled` mode.
|
||||
- **Windows / MSVC.** v1 is Linux/POSIX-first and supports GCC and Clang only.
|
||||
- **LLVM bitcode.** The LLVM backend emits textual `.ll` only; the caller runs `llvm-as`.
|
||||
- **LLVM debug metadata.** There is no `!llvm.dbg` in v1. Debug mapping exists on the C path via
|
||||
`#line` directives.
|
||||
- **A hand-authored VIR.** VIR is internal and intentionally hostile to hand-authoring. A textual
|
||||
form exists solely for tools and round-trip tests; it is not a supported authoring surface.
|
||||
- **Consuming LLVM IR or Vox's existing IR.** libVCT owns its IR definition.
|
||||
|
||||
## 5. Glossary
|
||||
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| **HIR** | High-level IR: the frontend AST, annotated in place with traits. |
|
||||
| **VIR** | Vox IR: a low-level SSA/CFG instruction IR. |
|
||||
| **Trait** | The union of an Attribute, Requests, and Relationships attached to a node. |
|
||||
| **Attribute** | A fact about a node (type, value, mutability, …). |
|
||||
| **Request** | An attribute-derived suggestion from HIR to VIR. |
|
||||
| **Relationship** | A directed edge between nodes, traceable up and down. |
|
||||
| **Cascade** | The chain of HIR rewrites triggered by a single fold. |
|
||||
| **Lowering** | The "middleman" that translates annotated HIR into VIR SSA. |
|
||||
| **Remark** | An optimizer decision record emitted for diagnostics. |
|
||||
|
||||
## 6. Conformance
|
||||
|
||||
An implementation conforms to this specification if it satisfies every `MUST` and `MUST NOT`
|
||||
requirement in every specification file listed in §8. `SHOULD` requirements may be violated only
|
||||
with a documented, deliberate reason. `MAY` requirements are optional.
|
||||
|
||||
Where this specification and an implementation disagree, this specification is authoritative. Where
|
||||
a later specification file refines an earlier one, the later file is authoritative for its subject.
|
||||
|
||||
## 7. Determinism guarantee
|
||||
|
||||
For a fixed `Config` and a fixed input, libVCT **MUST** produce byte-identical output on every run,
|
||||
independent of thread count. This guarantee binds every stage: HIR optimization, lowering, VIR
|
||||
optimization, and both backends. Determinism is a correctness property, not an optimization.
|
||||
|
||||
## 8. Specification index
|
||||
|
||||
| File | Subject |
|
||||
|---|---|
|
||||
| [000 — Overview](000-overview.md) | Purpose, thesis, goals, glossary, conformance, determinism. |
|
||||
| [001 — Architecture](001-architecture.md) | Modules, data flow, public interfaces, boundaries. |
|
||||
| [002 — Traits](002-traits.md) | Attributes, requests, relationships, representation, staleness. |
|
||||
| [003 — HIR](003-hir.md) | HIR node model, builder contract, textual format, `defer`. |
|
||||
| [004 — HIR Optimizer](004-hir-optimizer.md) | Pass framework, cascade, parallelism, comptime, budgets. |
|
||||
| [005 — Lowering](005-lowering.md) | HIR → VIR translation, SSA construction, memory model. |
|
||||
| [006 — VIR](006-vir.md) | VIR SSA/CFG model, type system, instructions, invariants. |
|
||||
| [007 — VIR Optimizer](007-vir-optimizer.md) | Pass framework, analyses, pipeline, request handling. |
|
||||
| [008 — C Backend](008-c-backend.md) | VIR → C17: out-of-SSA, compiler-friendly C, layout, ABI. |
|
||||
| [009 — LLVM Backend](009-llvm-backend.md) | VIR → textual LLVM IR. |
|
||||
| [010 — Driver & CLI](010-driver-cli.md) | Pipeline orchestration, flags, C compiler invocation. |
|
||||
| [011 — Diagnostics](011-diagnostics.md) | Diagnostics service, source maps, channels, ICE policy. |
|
||||
| [012 — Testing](012-testing.md) | Test layers, fixture harness, oracle, fuzzing, matrix. |
|
||||
| [013 — Build & Packaging](013-build-packaging.md) | Toolchain, artifacts, API surfaces, memory ownership. |
|
||||
| [014 — Worked Example](014-worked-example.md) | End-to-end trait/request walkthrough (normative). |
|
||||
| [015 — Open Questions](015-open-questions.md) | Deferred items and future work. |
|
||||
|
||||
## 9. How to read this specification
|
||||
|
||||
Each file is a self-contained specification of one subject. Cross-references name the target file
|
||||
directly (for example, "see [002 — Traits](002-traits.md)") so that the set can be read out of
|
||||
order.
|
||||
|
||||
Specifications state **observable and required behavior** (what a component must do and what
|
||||
guarantees it must uphold) rather than prescribing internal implementation. Where a component's
|
||||
internal design is load-bearing for correctness (for example, the SSA construction algorithm in
|
||||
[005 — Lowering](005-lowering.md)), the required properties are stated normatively and the named
|
||||
algorithm is given as the reference method.
|
||||
Reference in New Issue
Block a user