Crate sui_bytecode 

Bytecode compiler and VM for the Nix evaluator.

This crate provides an alternative evaluation backend for sui-eval. Instead of tree-walking the rnix AST, expressions are compiled to a stack-based bytecode and executed by a virtual machine.

Architecture

Nix source --> rnix parser (CST) --> Compiler --> Chunk (bytecode)
                                                       |
                                                       v
                                                 VM --> VMValue

Phase 1 + 2 Coverage

Currently supports:

• Literals: int, float, bool, null, string, path
• Arithmetic: +, -, *, /, unary -
• Comparison: ==, !=, <, >, <=, >=
• Logical: !, &&, ||, -> (with short-circuit)
• Strings: literals, interpolation
• Variables: let/in with local binding
• Functions: lambda, apply, pattern destructuring with defaults
• Lists: construction, ++ concatenation
• Attribute sets: construction, . selection, ? has-attr, // update, or default
• Control flow: if/then/else, assert
• Upvalue capture: Lua 5.x-style closures over non-local variables
• with scopes: dynamic variable lookup via with-scope stack
• rec attribute sets: self-referencing bindings
• inherit and inherit (source): in both let and attrset
• Dotted attribute paths: { a.b = 1; a.c = 2; } merging
• Dynamic attribute keys: { ${expr} = value; }
• Builtins: 50+ functions (type checks, list ops, attrset ops, string ops, arithmetic, control flow, conversion)
• import with file caching
• Thunks / lazy evaluation (MakeThunk/Force opcodes, blackhole detection)
• Lazy attrset values (non-trivial values wrapped in thunks)
• derivation / derivationStrict (native implementation via sui-compat)
• builtins.getFlake (path-based flake references)
• builtins.scopedImport (with-wrapping approach)
• VM-level dispatch for interner-dependent builtins (attrNames, listToAttrs, removeAttrs, hasAttr, getAttr, catAttrs)
• Deep-force at VM boundary (recursively forces thunks in attrsets/lists)

Not Yet Implemented

• String interpolation contexts

Re-exports

pub use bridge::BuiltinBridgeFn;

pub use bridge::BuiltinBridgeGuard;

pub use bridge::PathMaterializerFn;

pub use bridge::PathMaterializerGuard;

pub use bridge::call_builtin_bridge;

pub use bridge::materialize;

pub use bridge::materialize_path;

pub use bridge::set_builtin_bridge;

pub use bridge::set_path_materializer;

pub use builtins::BuiltinRegistry;

pub use chunk::Chunk;

pub use compiler::Compiler;

pub use error::CompileError;

pub use error::VMError;

pub use opcode::OpCode;

pub use value::StringKeyedValue;

pub use value::VMBuiltin;

pub use value::VMThunk;

pub use value::VMValue;

pub use vm::FlakeResolverGuard;

pub use vm::set_flake_resolver;

pub use vm::vm_fallback_count;

pub use vm::VM;

Modules

bridge

Builtin bridge: tree-walker builtins callable from the VM. Builtin bridge: allows the bytecode VM to call tree-walker builtins.

builtins

Built-in function registry for the VM. Built-in function registry for the bytecode VM.

chunk

Bytecode container (instructions + constant pool). Bytecode container — holds instructions and a constant pool.

compiler

AST-to-bytecode compiler. AST-to-bytecode compiler.

error

Error types for compiler and VM. Error types for the bytecode compiler and VM.

intern

String interning for attribute names and identifiers. Re-export the shared interner crate.

nanbox

NaN-boxed value representation for the VM stack. NaN-boxed value representation for the VM stack.

opcode

Bytecode instruction set. Bytecode instruction set for the Nix evaluator.

value

VM-specific value representation. VM-specific value representation.

vm

Bytecode interpreter / execution engine. Bytecode VM execution engine.

Structs

EvalResult

Result of bytecode evaluation: the value plus the interner needed to resolve symbol-keyed attrsets.

Interner

A string interner that maps strings to Symbol handles.

Symbol

An interned string handle — a cheap, copyable, comparable token.

Enums

EvalError

Unified error type wrapping both compile and runtime errors.

Functions

clear_compile_cache

Clear the thread-local compilation cache.

eval

Compile and execute a Nix expression string via the bytecode VM.

eval_full

Compile and execute a Nix expression, returning the value and interner.