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.mdbefore 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 ;
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:
docs/getting-started.md— recommended runtime workflow.docs/native-registration.md— Rust functions, native layouts, derive attributes, and safety.docs/compiler-api.md— parsing facade and semantic pipeline.docs/testing.md— validation layers and test placement.docs/architecture.md— components, data flow, invariants, and module boundaries.docs/development.md— setup and change recipes.docs/safety.md— JIT, ABI, allocator, provenance, and execution-mode contracts.docs/maintenance-roadmap.md— prioritized technical-debt plan.CONTRIBUTING.md— contribution checklist.
License
This project is licensed under the Apache License 2.0. See the LICENSE file for details.