subrust

Subrust is an innovative, dependency-free interpreter tailored for a strict subset of Rust programming language. Each program accepted by Subrust is guaranteed to be valid Rust, with identical behavior when run under rustc. This ensures that all code remains reliable and consistent across different runtimes.

Features

• Lightweight and Efficient: Subrust operates with #![no_std], no-alloc, and #![forbid(unsafe_code)], making it highly suitable for resource-constrained environments. It has zero dependencies, which simplifies integration and deployment.

• Deterministic Execution: The interpreter is designed to run user-editable control scripts in a sandboxed manner, ensuring safety and reliability. There are no ambient resources such as clocks or networks, allowing for controlled and predictable execution patterns.

Applications

Subrust provides versatility for various use cases where editable logic is needed without sacrificing safety or performance:

• Edit-time Interpretation, Release-time Compilation: Develop and modify scripts on-the-fly, observing changes instantly. Subsequently, compile the unchanged source with rustc to achieve native performance without including the interpreter in the production binary.

• User-Supplied Scripts: Run scripts from untrusted users safely. The execution environment is entirely isolated, with operations only permitted through hosted functions, ensuring that user logic is limited and controlled.

• Embedded Systems: The no-alloc feature, combined with the prohibition of unsafe code, makes Subrust perfect for deployment alongside firmware, making it ideal for microcontrollers and other embedded systems where memory constraints are a factor.

• Kernel and Bare-metal Operations: Its design allows it to function in environments lacking standard libraries or heap memory, making it suitable for complex embedded policies and applications in kernel spaces.

Usage

Subrust can be utilized as a library or through the command-line tools. Here’s a brief example of how to use it as a library:

use subrust::{CHK_INIT, MEM_INIT};
use subrust::apis::TEST_API;

let src = "fn main() { print_u64(2 + 2); }";
let mut mem = Box::new(MEM_INIT);
let mut chk = Box::new(CHK_INIT);
assert!(subrust::check_source(src, &mut mem, &mut chk, &TEST_API));

Command-Line Interface

A command-line interface is provided for ease of use:

cargo install subrust
subrust check  file.rs [api]   # Type-check source against a host API
subrust run    file.rs         # Execute the main function with host functions
subrust lex    file.rs         # Dump the token stream
subrust ast    file.rs         # Output the parsed abstract syntax tree (AST)
subrust emit   file.rs boot    # Serialize a checked program to a portable image

Example Project

An example project demonstrating the capabilities of Subrust is the HVAC controller, which showcases user-editable control logic while ensuring safe operation under varying conditions.

Language Subsets

Subrust is structured around three nested subsets that progressively enhance functionality, each entirely valid within the overarching Rust framework. This architecture supports a clean and scalable development approach. The roadmap includes plans for expanding support for common types such as Option<T> and Result<T, E>, improving error handling and type safety.

Overall, Subrust combines safety, flexibility, and efficiency, making it an invaluable tool for developers aiming to integrate editable logic into performance-critical applications.