lehit 0.2.0

Embeddable Lehit language frontend and Cranelift JIT runtime
Documentation

Lehit

Lehit is an experimental embeddable language frontend and Cranelift-based JIT runtime written in Rust. It parses Lehit source, resolves modules and types, builds typed IR, compiles transactional JIT units, and exposes a universal function ABI to a Rust host.

Pre-release status: APIs and language behavior may change before the first public release. Lehit is not yet a sandbox or a security boundary. Read docs/safety.md before executing untrusted code or registering native Rust types/functions.

What works today

  • Logos lexer and Chumsky parser with source spans and diagnostics.
  • Module graph, aliases, prelude resolution, generics, extensions, and method lookup.
  • Typed IR with move, borrow, initialization, cleanup, and drop analysis.
  • Cranelift JIT compilation for single modules and dependency graphs.
  • Strongly connected script modules compiled as atomic units.
  • Direct and checked execution modes.
  • Universal scalar, borrowed, and leased aggregate calls from Rust, subject to the documented validity/provenance limits.
  • Transactional load/reload and leased JIT units that keep old functions and values alive.
  • Declarative native Rust libraries and #[derive(LehitRegistration)].

Quick start

use lehit::runtime::{AbiCallError, AbiCallStatus, ExecutionMode, RuntimeBuilder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut runtime = RuntimeBuilder::new()
        .with_execution_mode(ExecutionMode::Checked)
        .build()?;

    runtime.load_script(
        "app://entry.lt",
        "as fn(argument: usize) -> i32
         let values: [i32; 2] = [11, 22] return values[argument]",
    )?;
    let function = runtime.function("app://entry.lt", "")?.abi_function()?;
    let mut call = function.abi_call_builder();
    call.push_rust_value_argument(1usize)?;
    assert_eq!(call.call()?.into_rust_value::<i32>()?, 22);

    let mut call = function.abi_call_builder();
    call.push_rust_value_argument(3usize)?;
    assert!(matches!(
        call.call(),
        Err(AbiCallError::Execution(status))
            if status == AbiCallStatus::BOUNDS_VIOLATION
    ));

    Ok(())
}

as fn(...) declares the script entry, which is addressed by the module path and the empty local path "". Without an explicit contract, top-level statements create an implicit fn() -> void; empty and declaration-only scripts have no file entry. See Getting started for the complete rules.

Run the complete embedding and native-registration examples:

cargo run --example embed
cargo run --example native_function

Repository layout

Path Responsibility
src/parsing/ Tokens, parser grammar, AST, spans, and parse diagnostics.
src/semantic/ Declarations, module/type/method resolution, body analysis, and typed IR.
src/runtime/ Workspace lifecycle, type metadata, code generation, JIT, and universal ABI calls.
src/core_lib/ Embedded core://*.lt source modules. The .lt files are the source of truth.
src/rust_lib/ Declarative registration model for Rust-provided modules, types, and functions.
lehit-macros/ Proc macros for native registration metadata.
examples/ Executable host-integration examples.
docs/ Architecture, development, safety, and maintenance guidance.

See docs/architecture.md for the complete pipeline and dependency rules.

Development

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace --all-targets
cargo test --workspace --doc
cargo run --example embed
cargo run --example native_function
RUSTDOCFLAGS="-D warnings -D missing-docs" cargo doc --workspace --no-deps

On filesystems without hard-link support, Cargo's incremental cache can be very slow. Use a local build directory when needed:

CARGO_TARGET_DIR=/tmp/lehit-target CARGO_INCREMENTAL=0 cargo test --workspace --all-targets

Clippy currently has a known warning backlog, so it is advisory rather than a -D warnings gate. New code should not add warnings in files it changes.

Documentation

These pages are also exposed under lehit::guides in generated rustdoc/docs.rs:

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.