Architecture

This part of the book explains how Larva works inside. It is written for people who build a language on Larva, work on Larva itself, or want to know what happens between larva build and a running program. The other books say how to use the tools; these pages say how they are made.

Larva is a compiler platform. It owns everything a program needs except the language it is written in: a typed object model (Larva HIR), the lowering of that model to a low-level IR, an IL and a VM, native back ends (LLVM, a direct x86-64 one, WebAssembly), a native runtime with several garbage collectors, project files, a package manager and native bindings. A language is a language pack: a frontend that turns source text into HIR, and a view that turns HIR back into source text. Larva never parses a language itself.

The pipeline

  hello.ant           Program.ant  …          (source files of any installed language)
      │                    │
      └────────┬───────────┘
               ▼
  ┌──────────────────────────┐   compile request (JSON)   ┌───────────────────────────────┐
  │ language pack (frontend) │ ◄───────────────────────── │ larva (Larva.Cli, SourceBuild)│
  │ lexer, parser, binder    │ ─────────────────────────► │ reads .queen, picks options   │
  └──────────────────────────┘    HIR assembly (.lva)     └───────────────────────────────┘
               │
               ▼                       System.Core.dll, libraries (.dll = PE + .lva section),
  ┌──────────────────────────┐         bindings, dependencies with another GC (own domain)
  │ HIR link (HirLinker)     │ ◄───────────────────────────────────────────────
  └──────────────────────────┘   one closed HIR assembly: the whole program
               │
               ▼
  ┌──────────────────────────┐   classes become structs + vtables, generics get requirements,
  │ lowering (HirLowerer)    │   closures/iterators/async become objects and state machines,
  └──────────────────────────┘   try/catch becomes unwind edges, imports become native calls
               │  Larva IR module (in memory; a .lvo when written)
               ▼
  ┌──────────────────────────┐   borrow check (enforce / warn / off), type check,
  │ IR checks (Compiler)     │   region check, safepoints, bounds facts
  └──────────────────────────┘
               │
               ▼
  ┌──────────────────────────┐   modules joined, imports resolved, link-once code shared,
  │ IR link (Linker)         │   GC domains assigned, entry wrapper chosen
  └──────────────────────────┘
               │
     ┌─────────┼──────────────┬──────────────────┬─────────────────────┐
     ▼         ▼              ▼                  ▼                     ▼
  LLVM      x86-64         WebAssembly        WebAssembly           IL (.lvm)
  (Larva.   (Larva.X64)    via LLVM           own back end          (IlLowering)
   Llvm)       │           (wasm-llvm)        (Larva.Wasm)              │
     │         │              │                  │                      ▼
     ▼         ▼              ▼                  ▼                  the VM
  object file + larva_rt   app.wasm + app.js (larva_rt.js) + app.html (Larva.Runtime)
     │
     ▼
  system linker (MSVC link)  →  app.exe / lib.dll

Every arrow but the first and the last happens inside the larva process, in memory. larva build writes no intermediate file: the HIR, the IR module and the linked program never touch the disk unless a tool asks for them.

You can see the phases with --timings. Each name is one step of the picture:

$ larva build --timings -o hello.exe hello.ant
hello.exe (llvm back end, O3, entry hello::Hello.$Module.Main)
timings: System.Core (compiled library) 83 ms, frontend 1536 ms, HIR link 54 ms, lowering 619 ms, IR checks 226 ms, IR link 93 ms, native (llvm) 1551 ms; total 4173 ms
$ hello.exe
Hello from Larva!

The same build with the other back ends differs only in the last step:

$ larva build --backend x64 --timings -o hellox.exe hello.ant
hellox.exe (x64 back end, entry hellox::Hello.$Module.Main)
timings: System.Core (compiled library) 47 ms, frontend 1070 ms, HIR link 62 ms, lowering 632 ms, IR checks 230 ms, IR link 100 ms, native (x64) 979 ms; total 3132 ms
$ larva build --timings --target wasm-llvm -o hello.js hello.ant
hello.wasm, hello.js, hello.html (LLVM back end, O3, entry hello::Hello.$Module.Main)
timings: System.Core (compiled library) 68 ms, frontend 1077 ms, HIR link 56 ms, lowering 598 ms, IR checks 208 ms, IR link 84 ms, native (wasm-llvm) 1705 ms; total 3808 ms
$ node hello.js
Hello from Larva!

And --check stops after lowering (and the borrow check, when it is on), writing nothing:

$ larva build --check --borrowcheck enforce hello.ant
no errors (1 file; System.Core (compiled library) 40 ms, frontend 934 ms, HIR link 50 ms, lowering 574 ms, borrow check 134 ms; total 1738 ms)

These timings come from a working copy of larva; the installed one is compiled ahead of time and is several times faster in every phase.

The forms of a program

A program changes shape four times. Each form exists for one reason.

The split between HIR and IR is the central decision of Larva's design. Before it, the Antril compiler lowered every feature (classes, closures, async, reflection, boxing) straight to the low-level IR, and every library was read by reparsing the text of its declarations. Now:

• HIR is the truth of the program. Types, members, generics, attributes and typed bodies, with complete metadata. Every frontend, tool and library speaks HIR.
• The language does not decide how code runs. A frontend resolves names, overloads, types and inference and emits typed HIR. How a virtual call is dispatched, how a closure is built, how an async method becomes a state machine: Larva decides, in lowering. Two languages that both have classes get the same object layout and can call each other.
• Libraries are referenced by HIR metadata, not by source. System.Core.dll holds the HIR of the standard library; compiling against it reads a binary table instead of parsing thousands of lines.
• Everything native is extern. The runtime's services are reached through a fixed table of intrinsics, the same in every back end and in the VM.

IR, below HIR, is where memory is explicit: object headers, handles, borrows. That is why the borrow checker, the region checker and the GC domains work on IR: whatever language a program came from, the same rules hold.

The projects of Larva

Larva is a set of libraries with one command on top. Each depends only on the ones in the rows above it:

Larva.Hir depends on nothing so that a frontend can be built on the HIR model and its services (the Antril pack uses Larva.Hir, Larva.Hir.Services and Larva.IR), without the back ends, the runtime or the command.

The language packs are not in this list: each lives in its own repository and is loaded by larva at run time (see Language packs).

One request, four runtimes

Code compiled by Larva can run in four places, and each has a runtime that implements the same object layout and the same table of intrinsics:

Because all four agree, a program gives the same output wherever it runs; the VM is the reference the other three are compared with.

The files Larva reads and writes

What is not implemented yet

These pages describe the code as it is. Where it falls short of the design, the page says so. The main gaps today:

• gc: custom is accepted but not usable: the runtime has hooks for an installed collector, but the library has no IGarbageCollector interface and no GC.Install yet.
• Larva's own WebAssembly back end emits invalid modules for some programs (any program that builds text, for example), and does not support 256-bit integers; use --target wasm-llvm.
• Main(str[] args) cannot be a program's entry, and Main() : i32 prints its result instead of exiting with it.
• Native builds need the MSVC tools: the Linux and macOS builders exist but no command reaches them yet.
• larva build recompiles everything on each build. An incremental cache per assembly is planned.