95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# 001 — Architecture
|
|
|
|
- **Status:** Draft
|
|
- **Normative language:** `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` are to be
|
|
interpreted as described in RFC 2119.
|
|
|
|
## 1. Overview
|
|
|
|
libVCT is decomposed into modules with explicit responsibilities and boundaries. This file defines
|
|
the module map, the data flow between stages, the three public interfaces, and the boundaries that
|
|
carry the design's weight.
|
|
|
|
## 2. Modules
|
|
|
|
| Module | Responsibility | Allocation | Visibility |
|
|
|---|---|---|---|
|
|
| `vct.ir.hir` | HIR AST node types, the trait attachment point, builder/emitter API | arena | **public** |
|
|
| `vct.ir.vir` | VIR SSA/CFG types, VIR type system, instruction set | arena | internal |
|
|
| `vct.traits` | Attribute / Request / Relationship definitions and queries | arena | **public** |
|
|
| `vct.comptime` | Comptime evaluator / constant-folding engine | arena | internal |
|
|
| `vct.hir.opt` | HIR pass framework and passes, parallel cascade | arena | internal |
|
|
| `vct.lower` | HIR → VIR lowering and SSA construction | arena | internal |
|
|
| `vct.vir.opt` | VIR pass framework and heavy passes | arena | internal |
|
|
| `vct.backend.c` | VIR → C17 emitter (out-of-SSA, compiler-friendly C) | arena + GC | **public entry** |
|
|
| `vct.backend.llvm` | VIR → textual LLVM IR emitter | arena + GC | **public entry** |
|
|
| `vct.driver` | C compiler invocation, flag assembly, `.o` emission, LTO, cosmopolitan | GC | **public** |
|
|
| `vct.cli` | Thin command-line wrapper | GC | **public** |
|
|
| `vct.diag` | Diagnostics, source maps, error reporting | GC | **public** |
|
|
| `vct.context` | Context and arena ownership, `Config` | GC + arena | **public** |
|
|
| `vct.test.hirbuild` | Fluent HIR test-builder harness | arena | **public** |
|
|
|
|
## 3. Data flow
|
|
|
|
The default pipeline is:
|
|
|
|
```
|
|
frontend --build--> HIR
|
|
--hir.opt (parallel, cascading)--> annotated HIR
|
|
--lower--> VIR (SSA/CFG)
|
|
--vir.opt--> optimized VIR
|
|
--backend.c--> C17 source --driver--> .o (default path)
|
|
|
|
optimized VIR --backend.llvm--> textual LLVM IR (caller links LLVM)
|
|
```
|
|
|
|
Each stage consumes the previous stage's output and is specified independently:
|
|
[003 — HIR](003-hir.md), [004 — HIR Optimizer](004-hir-optimizer.md),
|
|
[005 — Lowering](005-lowering.md), [006 — VIR](006-vir.md),
|
|
[007 — VIR Optimizer](007-vir-optimizer.md), [008 — C Backend](008-c-backend.md), and
|
|
[009 — LLVM Backend](009-llvm-backend.md).
|
|
|
|
## 4. Public interfaces
|
|
|
|
libVCT exposes exactly three interfaces to embedders:
|
|
|
|
1. **HIR builder (frontend-facing).** Construct nodes, set types and values, attach
|
|
frontend-supplied traits (such as `is_static` and optimization hints), and finish a module. See
|
|
[003 — HIR](003-hir.md).
|
|
2. **Trait query (VIR-facing).** Read attributes and walk relationships. This is the **only**
|
|
channel through which VIR obtains facts. See [002 — Traits](002-traits.md).
|
|
3. **Backend (driver-facing).** Consume optimized VIR and emit C or textual LLVM IR. See
|
|
[008 — C Backend](008-c-backend.md) and [009 — LLVM Backend](009-llvm-backend.md).
|
|
|
|
The native D API is the full-feature surface. A thin `extern(C)` C API (opaque handles for
|
|
`Context`/`Module`/`Builder`/`Config`) is the primary v1 public surface and is a shim over the D
|
|
API; no logic lives in the shim. See [013 — Build & Packaging](013-build-packaging.md).
|
|
|
|
## 5. Load-bearing boundaries
|
|
|
|
- **`vct.traits` is the contract.** Both HIR and VIR depend on it. VIR depends on nothing else from
|
|
HIR except **node identity**. A change to the trait vocabulary is a cross-cutting change and is
|
|
versioned accordingly (see [013 — Build & Packaging](013-build-packaging.md)).
|
|
- **`vct.lower` is the SSA construction site.** Phi-nodes, dominance, and the memory model all land
|
|
there; it is the most algorithmically dense module. Its correctness invariants are specified in
|
|
[005 — Lowering](005-lowering.md) and [006 — VIR](006-vir.md).
|
|
|
|
## 6. Memory and ownership model
|
|
|
|
- A `Context` owns one or more **arenas**. An arena is the unit of reclamation; the default is one
|
|
arena per `Module`, freed wholesale.
|
|
- All IR and optimizer objects are **arena-owned and non-GC**. Passes mutate in place under epoch
|
|
guards (see [002 — Traits](002-traits.md)).
|
|
- **GC is permitted only on cold paths**: the driver, diagnostics, and CLI.
|
|
- The arena interface is exposed so embedders can supply their own backing memory; a default bump
|
|
allocator ships in-tree.
|
|
|
|
Full lifecycle, ownership, and threading rules are specified in
|
|
[013 — Build & Packaging](013-build-packaging.md).
|
|
|
|
## 7. Threading
|
|
|
|
libVCT is thread-safe when each compilation unit has its own `Context` and arenas. There is no
|
|
shared mutable global state. Intra-module parallelism is internal and bounded by the `-j` setting.
|
|
The determinism guarantee in [000 — Overview](000-overview.md) applies regardless of thread count.
|