UNDER THE HOOD

Architecture

WeaveC is a drop-in C compiler that enforces memory safety at run time, built on Clang and LLVM. RFC 0036, Deterministic heap reuse, defines the design over the guards of RFC 0035, Guard by default; each RFC’s Implementation amendments override its body.

weavec-cc guards every memory access of the C code it compiles, in LLVM IR, against the runtime’s shadow memory. It removes a guard only where a simple local rule proves it redundant. The locals a guard can reach get redzones in their frame (locals whose lifetimes never overlap share space), globals get redzones, locals are zero-initialised, typed array indexes are checked against their declared bounds and fortified library calls against the object size they carry. The runtime’s allocator leaves at least one byte after every heap object that no object owns, and reuses a released block only after a sweep of the program’s memory finds no pointer to it. A bad access traps with a report.

The code is two C++ libraries, one thin command-line tool and a C runtime. The arrows point from a layer to what it may depend on.

                 ┌──────────────────────────┐
                 │  tools/weavec-cc         │
                 │  (drop-in C compiler)    │
                 └────────────┬─────────────┘
                              ▼
                 ┌──────────────────────────┐
                 │  weavec::Frontend        │  guard passes, unsafe
                 │  lib/Frontend            │  regions, enforcement
                 │                          │  ledger, driver
                 └──────┬───────────┬───────┘
                        ▼           ▼
        ┌────────────────────┐   ┌────────────────────┐
        │  weavec::Core      │   │  Clang / LLVM      │
        │  lib/Core          │   │  (external)        │
        │  the library table │   └────────────────────┘
        │  no Clang/LLVM     │
        └────────────────────┘

runtime/ is C code that weavec-cc links into every enforcing link (see The runtime). It depends on nothing above. The layering rules are strict:

Core includes nothing from clang/ or llvm/. It is the one library built without their include paths, and holds only the library table.
The runtime includes no WeaveC header but its own weavec_rt.h, and the entry points it declares there match the ones the passes declare (scripts/check-hygiene.py checks that each one the passes name is declared).

RFC 0036 is Accepted and being implemented; the roadmap says which stages have landed. This page describes the tree as it is. Earlier designs (the advisory ownership analysis and the weavec tool, checked mode, checks planned from the analysis, unit records and the link step) are described in the RFCs that introduced and retired them.

Architecture

In this guide