Crate mrubyedge_cli

Crate mrubyedge_cli 

Source
Expand description

§mrubyedge-cli

Command-line interface for mruby/edge - a lightweight, WebAssembly-focused mruby VM implementation.

§About mruby/edge

mruby/edge is an mruby-compatible virtual machine implementation written in Rust, specifically designed for WebAssembly environments. It aims to provide:

  • WebAssembly-first design: Optimized for running Ruby code in browsers and edge computing environments
  • Lightweight runtime: Minimal footprint and binary size suitable for constrained environments
  • mruby compatibility: Executes mruby bytecode (.mrb files) and Ruby source code
  • Rust safety: Built with Rust for memory safety and reliability

§Installation

Install mrubyedge-cli using cargo:

cargo install mrubyedge-cli

Or build from source:

git clone https://github.com/mrubyedge/mrubyedge.git
cd mrubyedge
cargo build --release -p mrubyedge-cli

§Getting Started

Create a simple Ruby script hello.rb:

puts "Hello from mruby/edge!"
puts RUBY_ENGINE

Run it with mrbedge:

mrbedge hello.rb
# or explicitly
mrbedge run hello.rb

§Main Features

§run - Execute Ruby Scripts

The run subcommand executes Ruby source files (.rb) or compiled mruby bytecode (.mrb).

Usage:

mrbedge run <file>
# or simply
mrbedge <file>

Examples:

# Run Ruby source
mrbedge run script.rb

# Run compiled bytecode
mrbedge run script.mrb

§compile-mrb - Compile Ruby to Bytecode

Compiles Ruby source code into mruby bytecode format for faster loading and distribution.

Usage:

mrbedge compile-mrb <input.rb> -o <output.mrb>

Examples:

# Compile a single file
mrbedge compile-mrb app.rb -o app.mrb

# Run the compiled bytecode
mrbedge run app.mrb

§wasm - Generate WebAssembly Modules

Compiles Ruby code directly into a standalone WebAssembly module that can run in browsers or any WebAssembly runtime.

Usage:

mrbedge wasm <input.rb> -o <output.wasm>

Examples:

# Generate WebAssembly module
mrbedge wasm app.rb -o app.wasm

# Use in browser or Node.js
# The generated WASM can be loaded and executed in any WASM runtime

Use Cases:

  • Serverless edge computing
  • Browser-based applications
  • Microservices with minimal overhead
  • Cross-platform portable executables

WASI Support:

The wasm command can generate both WASI-enabled and non-WASI WebAssembly binaries. By default, it produces WASI-enabled modules. To disable WASI support, use the --no-wasi flag.

Import/Export Functions:

You can specify WebAssembly function imports and exports using RBS (Ruby Signature) files. Place RBS files with specific naming conventions alongside your Ruby script:

For a Ruby script named foo.rb:

  • foo.import.rbs: Defines external functions to import from the WebAssembly host
  • foo.export.rbs: Defines Ruby functions to export as WebAssembly functions

Example:

# app.rb
def calculate(x, y)
  x + y
end
# app.export.rbs
def calculate: (Integer, Integer) -> Integer
# app.import.rbs
def external_log: (String) -> void

The generated WebAssembly module will expose Kernel#calculate and can call Kernel#external_log from the host environment.

NOTE: Inlined RBS for imports and exports annotations will be supported in future releases.

§Additional Resources

Modules§

rbs_parser
subcommands
template