Native code and analysis

Modules l3i::native_code (with hooks, ir, vector_buffer), available with the jit feature, and l3i::analysis, available with the analysis feature. Native code is the guide.

Native code generation#

One NativeCodeGen per runtime owns a shared Luau code generation context with a hard size budget, immutable compilation options (mode, counters, userdata type names, the lowering hooks), and a registry of compiled modules keyed by a 128-bit hash of their bytecode so identical scripts share native code and hash collisions are rejected rather than aliased. The jit feature builds Luau’s CodeGen library and the C++ shim csrc/codegen.cpp that exposes its C++-only parts.

Which functions are compiled natively: never (compile reports Skipped); only modules marked --!native; every module. Clone, Copy, Debug, Eq.

Host choices for native code generation, passed to RuntimeBuilder::native_code. Debug, Default.

Builder methods: fn mode(self, mode: NativeCodeMode) -> Self, fn hooks(self, hooks: impl NativeCodeHooks) -> Self (adds a hook set after the defaults), fn userdata_types(self, names: impl IntoIterator<Item = impl Into<String>>) -> Self.

Outcome of one compilation. The first four are the binder’s: mode is Off; the platform has no code generator or it failed to initialise; another module with different bytecode already has this id; this module ran out of code space before and is not retried. The rest are Luau’s CodeGenCompilationResult. Clone, Copy, Debug, Eq.

A module identity: MurmurHash3 x64 128 of the bytecode with OpenMW’s seed.

Both Clone, Copy, Debug, Eq; NativeCodeStats also Default.

The runtime’s generator, from Runtime::native_code(&self) -> Option<&NativeCodeGen>. Dropped after lua_close, as Luau requires for shared contexts.

Sandbox::load_template compiles each template according to the mode and keeps the result on the Template; source::LoadScope::load_bytecode and load_source compile the chunk they load on any scope the same way.

What assembly prints; the default is host assembly only. Clone, Copy, Debug, Eq, Default.

Block counters summed over every module compiled with counters on. Clone, Copy, Debug, Default, Eq.

The process-wide perf log (Luau::CodeGen::setPerfLog): every function compiled natively afterwards, in any runtime, is reported with its code address and size, for profiler symbolisation.

Lowering hooks#

Module l3i::native_code::hooks: Luau’s HostIrHooks written in Rust. Luau asks two kinds of question while compiling a function: what bytecode type an operation on a vector or annotated userdata produces, so the rest of the function specialises on it; and whether the host wants to lower the operation to IR itself. A *_type answer of bytecode_type::ANY and a lowering answer of false mean “not mine”, and Luau falls back to its generic path. Lowering must obey Luau’s contract for the hook: check tags, take VM exits to pcpos on failure, read operands before writing results. Hooks run inside the code generator: no Lua API, no panics (a panic aborts).

Every method has a “not mine” default. userdata_type values are TAGGED_USERDATA_BASE + index into the compilation’s userdata type names. Implemented for Rc<H> too, so one hook set can be shared between plans.

What the VM being compiled for actually assigned. Lowering hooks take their tags from here rather than from constants, so native code checks the VM’s real tags.

A value:method(...) call site: the register of the first argument and of the results, the receiver’s register, the argument count including the receiver, the result count or LUA_MULTRET, and the bytecode position for VM exits.

A field access and a metamethod operation on userdata operands. All three Clone, Copy, Debug, Eq.

use l3i::ffi::{LUA_TNUMBER, LUA_TUSERDATA};
use l3i::native_code::hooks::{AccessSite, NativeCodeHooks, NativeContext};
use l3i::native_code::ir::{IrBuilder, IrCmd, bytecode_type};

/// Lowers `p.x` / `p.y` on a `Point` (userdata type index 0) to a tag check and an f32 load.
struct PointFields;

impl NativeCodeHooks for PointFields {
    fn userdata_access_type(&self, _: &NativeContext<'_>, userdata_type: u8, member: &str) -> u8 {
        if userdata_type == bytecode_type::TAGGED_USERDATA_BASE && matches!(member, "x" | "y") {
            bytecode_type::NUMBER
        } else {
            bytecode_type::ANY
        }
    }

    fn userdata_access(
        &self,
        context: &NativeContext<'_>,
        build: &mut IrBuilder<'_>,
        userdata_type: u8,
        member: &str,
        site: AccessSite,
    ) -> bool {
        if userdata_type != bytecode_type::TAGGED_USERDATA_BASE {
            return false;
        }
        // The tag comes from the VM being compiled for, never from a constant.
        let Some(point_tag) = context.tag_of::<Point>() else { return false };
        let offset = match member {
            "x" => 0,
            "y" => 4,
            _ => return false,
        };
        let source = build.vm_reg(site.source_reg);
        let userdata = build.inst(IrCmd::LOAD_POINTER, &[source]);
        let tag = build.const_int(i32::from(point_tag));
        let exit = build.vm_exit(site.pcpos);
        build.inst(IrCmd::CHECK_USERDATA_TAG, &[userdata, tag, exit]);
        let at = build.const_int(offset);
        let userdata_tag = build.const_tag(LUA_TUSERDATA as u8);
        let value = build.inst(IrCmd::BUFFER_READF32, &[userdata, at, userdata_tag]);
        let number = build.inst(IrCmd::FLOAT_TO_NUM, &[value]);
        let result = build.vm_reg(site.result_reg);
        build.inst(IrCmd::STORE_DOUBLE, &[result, number]);
        let number_tag = build.const_tag(LUA_TNUMBER as u8);
        build.inst(IrCmd::STORE_TAG, &[result, number_tag]);
        true
    }
}

The IR builder#

Module l3i::native_code::ir. IrCmd, IrCondition, IrBlockKind and HostMetamethod are enums generated by build.rs from the headers of the exact Luau build (IrData.h, CodeGenOptions.h), so a Luau bump that renumbers the IR cannot silently desynchronise this layer; their variants are Luau’s own names (IrCmd::LOAD_POINTER, IrCmd::CHECK_USERDATA_TAG, IrCmd::STORE_DOUBLE, IrCondition::Equal, IrBlockKind::Internal, HostMetamethod::Add).

Bytecode type tags a *_type hook may answer with (LuauBytecodeType): NIL 0, BOOLEAN 1, NUMBER 2, STRING 3, TABLE 4, FUNCTION 5, THREAD 6, USERDATA 7, VECTOR 8, BUFFER 9, INTEGER 10, ANY 15, TAGGED_USERDATA_BASE 64 (userdata type index i is TAGGED_USERDATA_BASE + i), TAGGED_USERDATA_END 96, OPTIONAL_BIT 128.

An IR operand: a register, constant, block, instruction result or VM exit. An opaque 32-bit handle; IrOp::NONE is the empty operand. Clone, Copy, Debug, Eq, Hash.

Luau’s IR builder for the function being compiled, valid for one hook invocation.

The vector buffer writer#

Module l3i::native_code::vector_buffer.

The writef32x3 lowering, part of the default hook set: a statement call v:writef32x3(buffer, offset) becomes three native f32 buffer stores. Any other shape (results wanted, wrong arity, a non-buffer or non-number argument, an offset that is not an in-range integer) exits to the interpreter, whose __namecall shim from Runtime::install_vector_buffer_writer applies the exact library semantics.

Analysis#

Module l3i::analysis, feature analysis: Luau’s type checker, linter, autocomplete and the standalone parser over the C++ shim csrc/analysis.cpp. Nothing here touches a VM: an Analysis is a Luau::Frontend fed by a host SourceProvider.

What the checker asks the host for.

A module’s source and whether it is a requireable module or a top-level script. Clone, Debug, Eq.

How unannotated code is treated: no inference; unannotated symbols are any (the default); inferred. Clone, Copy, Debug, Eq, Default.

Per-module configuration, the .luaurc fields the checker reads: enabled_lints is a bitmask of 1 << code (0 keeps Luau’s defaults), lint_errors reports lint warnings as errors, type_errors (default true) reports type errors at all. Clone, Debug, Eq, Default.

A provider that serves a runtime plan’s modules as typed strict stubs and everything else from an inner provider, so require("@dream/...") in a checked script resolves to the plan’s declared types. Made by RuntimePlan::analysis_sources; fn new(plan: Rc<RuntimePlan>, inner: P) -> Self and fn inner(&self) -> &P.

Which constraint solver Luau uses; New is the default.

A definitions file (.d.luau) loaded into the global scope: declare extern type, declare name: T, export type. A runtime plan renders one with RuntimePlan::type_definitions. name is the package errors are reported under. Clone, Debug, Eq.

Clone, Debug, Eq, Default.

A Luau::Frontend over a host source provider.

A source range, 0-based lines and columns, end exclusive. Clone, Copy, Debug, Eq, Default.

Internal is the analysis itself failing (an exception inside Luau); text is its message. Clone, Copy, Debug, Eq.

code is Luau’s error or lint code; name the lint warning’s name (LocalUnused), empty otherwise. Clone, Debug, Eq.

The result of checking one module. fn errors(&self) -> impl Iterator<Item = &Diagnostic> is the type errors, lint errors, parse errors and internal failures (what would fail a build); fn is_clean(&self) -> bool. Clone, Debug, Default, Eq.

Luau’s AutocompleteEntryKind and AutocompleteContext; type_text is the entry’s type as Luau prints it, empty for keywords.

Parses source standalone (Luau::Parser::parse) without a frontend, optionally encoding the AST as Luau’s JSON.

use std::collections::HashMap;
use l3i::analysis::{Analysis, AnalysisOptions, DiagnosticKind, Mode, ModuleConfig, SourceCode, SourceProvider};

struct Sources {
    modules: HashMap<&'static str, &'static str>,
}

impl SourceProvider for Sources {
    fn read_source(&self, name: &str) -> Option<SourceCode> {
        self.modules.get(name).map(|text| SourceCode { text: (*text).to_owned(), is_script: name == "main" })
    }
    fn resolve_module(&self, _requirer: &str, required: &str) -> Option<String> {
        let name = required.trim_start_matches("./");
        self.modules.contains_key(name).then(|| name.to_owned())
    }
    fn module_config(&self, _name: &str) -> ModuleConfig {
        ModuleConfig { mode: Mode::Strict, ..ModuleConfig::default() }
    }
}

fn main() -> l3i::Result<()> {
    let mut modules = HashMap::new();
    modules.insert("util", "--!strict\nlocal M = {}\nfunction M.double(n: number): number return n * 2 end\nreturn M");
    modules.insert("main", "--!strict\nlocal util = require('./util')\nlocal unused = 1\nlocal text: string = util.double(21)\nprint(text)\n");
    let analysis = Analysis::new(Sources { modules }, AnalysisOptions::default())?;
    let report = analysis.check("main", true);
    assert!(!report.is_clean());
    assert!(report.diagnostics.iter().any(|d| d.kind == DiagnosticKind::TypeError && d.span.begin_line == 3));
    assert!(report.diagnostics.iter().any(|d| d.kind == DiagnosticKind::LintWarning && d.name == "LocalUnused"));
    Ok(())
}