Quick Usage

LightVM initialization is very flexible and allows you to configure the capabilities and debugging features according to your application needs.

Using TypeScript

For TypeScript-based projects, you can configure a VM instance with an intuitive builder pattern before accessing the main tools interface.

Builder Pattern

import { LightVM, Capability, TimeBudget } from 'lightvm';

const vm = new LightVM({ caps: [Capability.Observe, Capability.Control] })
  .setMaxIo(100) // Maximum number of I/O operations allowed (default: 100)
  .setMaxImport(3) // Maximum number of allowed module imports (default: 3)
  .setMaxAlloc(50) // Maximum number of memory allocations allowed (default: 50)
  .setMaxCall(200) // Maximum number of nested function calls allowed (default: 200)
  .setMaxJump(100) // Maximum number of control flow jumps allowed (default: 100)
  .setMaxTicks(1_000_000) // Maximum number of execution ticks before stopping (default: 1,000,000)
  .setMaxStackSize(128) // Maximum number of items the stack can hold (default: 128)
  .setAllowedImports(['math', 'time', 'utils']) // Whitelist of modules that can be imported
  .setTimeBudget(TimeBudget.Cheap) // Sets the execution time budget limit to prevent infinite loops (Default: Cheap)
  .withUnsafeMode(false) // Enable or disable system-level unsafe operations (default: false)
  .withNightly(false) // Allow nightly features (default: false)
  .withBacktrace(false) // Display backtrace details in error messages (default: false)
  .withExplain(false) // Display a more detailed hint in the error message (default: false)
  .withHint(true); // Display a hint on error messages (default: true)

const tools = vm.tools();

Object Pattern

import { LightVM, Capability, TimeBudget } from 'lightvm';

const vm = new LightVM({
  caps: [Capability.Observe, Capability.Control],
  runtimeConfig: {
    nightly: false, // Allow nightly features (default: false)
  },
  errorOptions: {
    backtrace: false, // Display backtrace details in error messages (default: false)
    explain: false, // Display a more detailed hint in the error message (default: false)
    hint: true, // Display a hint on error messages (default: true)
  },
  securityConfig: {
    maxIo: 100, // Maximum number of I/O operations allowed (default: 100)
    maxImport: 3, // Maximum number of allowed module imports (default: 3)
    maxAlloc: 50, // Maximum number of memory allocations allowed (default: 50)
    maxCall: 200, // Maximum number of nested function calls allowed (default: 200)
    maxJump: 100, // Maximum number of control flow jumps allowed (default: 100)
    maxTicks: 1_000_000, // Maximum number of execution ticks before stopping (default: 1,000,000)
    maxStackSize: 128, // Maximum number of items the stack can hold (default: 128)
    allowedImports: ['math', 'time', 'utils'], // Whitelist of modules that can be imported
    timeBudget: TimeBudget.Cheap, // Sets the execution time budget limit to prevent infinite loops (Default: Cheap)
    unsafeMode: false, // Enable or disable system-level unsafe operations (default: false)
  },
});

const tools = vm.tools();

Using Rust

For Rust users, configuration is done through VmConfig. You can declaratively set VM capabilities before executing bytecode.

Builder Pattern

use lightvm::LightVM;
use lightvm::types::{vmconfig::VmConfig, capability::Capability, time_budget::TimeBudget};

fn main() {
  let mut vm = LightVM::new(VmConfig {
    caps: vec![Capability::Control, Capability::Observe],
    ..Default::default()
  })
  .set_max_io(100) // Maximum number of I/O operations allowed (default: 100)
  .set_max_import(3) // Maximum number of allowed module imports (default: 3)
  .set_max_alloc(50) // Maximum number of memory allocations allowed (default: 50)
  .set_max_call(200) // Maximum number of nested function calls allowed (default: 200)
  .set_max_jump(100) // Maximum number of control flow jumps allowed (default: 100)
  .set_max_ticks(1_000_000) // Maximum number of execution ticks before stopping (default: 1,000,000)
  .set_max_stack_size(128) // Maximum number of items the stack can hold (default: 128)
  .set_allowed_imports(vec!["math".into(), "time".into(), "utils".into()]) // Whitelist of modules that can be imported
  .set_time_budget(TimeBudget::Cheap) // Sets the execution time budget limit to prevent infinite loops (Default: Cheap)
  .with_unsafe_mode(false) // Enable or disable system-level unsafe operations (default: false)
  .with_nightly(false) // Allow nightly features (default: false)
  .with_backtrace(false) // Display backtrace details in error messages (default: false)
  .with_explain(false) // Display a more detailed hint in the error message (default: false)
  .with_hint(true); // Display a hint on error messages (default: true)
  
  let tools = vm.tools();
}

Object Pattern

use lightvm::LightVM;
use lightvm::types::{
  vmconfig::VmConfig,
  runtime_config::RuntimeConfig,
  error_options::ErrorOptions,
  security_config::SecurityConfig,
  capability::Capability,
  time_budget::TimeBudget
};

fn main() {
  let mut vm = LightVM::new(VmConfig {
    caps: vec![Capability::Control, Capability::Observe],
    runtime_config: Some(RuntimeConfig {
      nightly: false // Allow nightly features (default: false)
    }),
    error_options: Some(ErrorOptions {
      backtrace: false, // Display backtrace details in error messages (default: false)
      explain: false, // Display a more detailed hint in the error message (default: false)
      hint: true // Display a hint on error messages (default: true)
    }),
    security_config: Some(SecurityConfig {
      max_io: 100, // Maximum number of I/O operations allowed (default: 100)
      max_import: 3, // Maximum number of allowed module imports (default: 3)
      max_alloc: 50, // Maximum number of memory allocations allowed (default: 50)
      max_call: 200, // Maximum number of nested function calls allowed (default: 200)
      max_jump: 100, // Maximum number of control flow jumps allowed (default: 100)
      max_ticks: 1_000_000, // Maximum number of execution ticks before stopping (default: 1,000,000)
      max_stack_size: 128, // Maximum number of items the stack can hold (default: 128)
      allowed_imports: vec!["math".into(), "time".into(), "utils".into()], // Whitelist of modules that can be imported
      time_budget: TimeBudget::Cheap, // Sets the execution time budget limit to prevent infinite loops (Default: Cheap)
      unsafe_mode: false // Enable or disable system-level unsafe operations (default: false)
    })
  });
  
  let tools = vm.tools();
}

TIP

Get the tools interface. Store this as a constant to reuse it for all upcoming tasks.

Related API Reference

Want to configure permissions or execution limits? Check out the Capabilities and Time Budget references for detailed usage.