Raz Manual/Compiler

Compiler

Compiler Architecture

The current self-hosted frontend, validation pipeline, RIR boundary, and C++17 backend.

Raz Gen2 Manual·Compiler

The active Gen2 compiler is written in Raz and emits C++17. The component boundaries below describe the current implementation and may change as the frontend is completed.

Compilation pipeline

CLI
  → module/include resolution
  → macro expansion
  → build-definition rewriting
  → lexer and parser
  → semantic validation
  → RIR lowering and verification
  → C++17 lowering and emission
  → generated-C++ structural validation
  → output file
Stage Source location Responsibility
CLI driver src/driver/main.raz Reads inputs/options, resolves dependencies, runs the pipeline, and writes generated C++.
Source inclusion src/source/includes.raz Expands source files, normalizes paths, and detects cycles.
Module resolver src/source/modules.raz Resolves dotted Raz module imports against configured roots.
Macro expander src/source/macros.raz Extracts and expands parameterized source macros.
Lexer src/core/lexer.raz Produces identifiers, literals, keywords, delimiters, and operators.
Parser and AST src/core/parser.raz, src/model/ast.raz Parses the supported source subset into the compiler model.
Semantic analysis src/validation/semantics.raz Resolves names, checks types and calls, and rejects mutation of immutable bindings.
RIR src/validation/lowering.raz, rir.raz Lowers the frontend representation and verifies RIR invariants.
C++17 backend src/targets/cpp17/ Maps types and operations to emitted C++17.

Compiler responsibilities

  • Recognize valid Raz source according to a single authoritative grammar.
  • Report invalid constructs at the earliest appropriate phase.
  • Perform semantic checks required by the approved language rules.
  • Lower valid programs through a verifiable representation into C++17.
  • Preserve source and diagnostic information when includes, modules, or macros transform input.

Planned architecture direction

  • Keep the user-facing compiler driver separate from the core language frontend and backend. Each source module should have a clear responsibility and remain independently maintainable.
  • Review hard-coded standard header emission. Optional standard and native dependencies should normally be explicit through module/header imports; any unavoidable backend scaffolding must be small and documented.
  • Define target, platform, and environment information explicitly. Do not add hidden compiler behavior without a defined source-language or build-system contract.

Architecture items to resolve

  • Centralize token IDs instead of duplicating numeric literals.
  • Maintain one authoritative keyword, grammar, and type table.
  • Clarify the division between Raz validation and checks delegated to GNU C++.
  • Resolve the unreachable/inconsistent extern branch.