rubylang 0.1.18

Ruby as a fusevm frontend: lexer, parser, and compiler to fusevm::Chunk on a RubyHost heap — the first compiled standalone Ruby runtime
Documentation
██████╗ ██╗   ██╗██████╗ ██╗   ██╗██╗      █████╗ ███╗   ██╗ ██████╗
██╔══██╗██║   ██║██╔══██╗╚██╗ ██╔╝██║     ██╔══██╗████╗  ██║██╔════╝
██████╔╝██║   ██║██████╔╝ ╚████╔╝ ██║     ███████║██╔██╗ ██║██║  ███╗
██╔══██╗██║   ██║██╔══██╗  ╚██╔╝  ██║     ██╔══██║██║╚██╗██║██║   ██║
██║  ██║╚██████╔╝██████╔╝   ██║   ███████╗██║  ██║██║ ╚████║╚██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚═════╝    ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝

CI Rust Docs license status

[RUBY, COMPILED TO BYTECODE — JIT-COMPILED, NOT TREE-WALKED]

"MRI walks the tree. rubylang compiles it."

Ruby in Rust — a compiled Ruby runtime, hosted on the fusevm bytecode VM with a three-tier Cranelift JIT, shared with the other fusevm frontends.

Read the Docs · Engineering Report · Builtin Reference


Table of Contents


[0x00] OVERVIEW

MRI runs Ruby by walking an AST in C. rubylang lexes and parses Ruby to an AST, lowers it to fusevm bytecode, and runs it on a compiled VM with a Cranelift JIT. rubylang carries no VM or JIT of its own. Highlights:

  • Compiled, not tree-walked — arithmetic and comparison operators lower to native fusevm ops so the JIT can trace hot loops.
  • fusevm-hosted — no local vm.rs / jit.rs; the shared engine used by every fusevm frontend. jit-disk-cache persists native code across runs.
  • Native arithmetic — a strict numeric hook supplies Ruby semantics (String/Array +, floored integer division, cross-type ==) only for non-numeric operands the VM can't compute directly.
  • Reference-typed objects — String, Array, and Hash live on the host heap behind Value::Obj handles, so a.push(x) mutates in place — real Ruby reference semantics.
  • Scope-sharing blocks — every variable access routes through the shared host, so a block run as a nested VM captures and mutates its enclosing locals.
  • Real threads under a GVL — Thread.new spawns an OS thread that runs on the one process-global object heap, serialized by a Global VM Lock exactly like MRI: only one thread executes Ruby at a time, so shared-heap mutation stays atomic. Thread#join/#value release the GVL while waiting and re-raise a thread's exception; each thread swaps in its own call stack. Mutex, Queue/ SizedQueue, and ConditionVariable are provided — a blocking Queue#pop/ ConditionVariable#wait releases the GVL and parks on its own condvar until a producer/signaller wakes it.
  • Ruby truthiness — only nil and false are falsy (0 and "" are true); conditions normalize through a TRUTHY op before a native branch.
  • AOP intercepts — a glob-matched before/after/around method-intercept registry, the same design as zshrs's function intercepts.
  • Editor-ready — an LSP server, a DAP debugger (source-line breakpoints inside methods, stepping, call stack), and an irb-style REPL on a persistent host, all over stdio.
  • Differential parity — a snippet corpus diffed live against the reference ruby, frozen and replayed in CI with no ruby installed, plus a grammar-driven differential fuzzer.

[0x01] INSTALL

# Via Homebrew tap (bumped by each release; formula is `rubylang`)
brew tap MenkeTechnologies/menketech
brew install rubylang

# Or from source
git clone https://github.com/MenkeTechnologies/rubylang
cd rubylang
cargo build

# run a file, a one-liner, or the REPL
./target/debug/ruby script.rb
./target/debug/ruby -e 'puts (1..100).sum'
./target/debug/ruby --repl

rubylang is a standalone Rust crate (an explicit empty [workspace] keeps it independent of the meta repo). fusevm is pulled from crates.io with the jit, jit-disk-cache, aot, and ffi features. Run the tests with cargo test.

Zsh tab completion

cp completions/_ruby /usr/local/share/zsh/site-functions/_ruby
# or: fpath=(/path/to/rubylang/completions $fpath) in .zshrc
autoload -Uz compinit && compinit

[0x02] USAGE

def fib(n)
  n < 2 ? n : fib(n - 1) + fib(n - 2)
end

puts (0..10).map { |i| fib(i) }.join(", ")
# => 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55

sum = 0
[1, 2, 3, 4].each { |x| sum += x }
puts sum                                   # => 10

puts({ a: 1, b: 2 }.merge({ c: 3 }).keys.length)   # => 3

Embedding

pub fn run_program(src: &str, input: &str) -> Result<String, String>

Runs src as a complete program on a fresh interpreter (its own thread and host per call, so calls from several threads never share state or output). input is what gets and $stdin/STDIN reads see; everything written to $stdout/$stderr is returned and nothing reaches the process stdout. A syntax error, an uncaught exception, or exit/exit!/abort with a nonzero status is Err; exit 0 returns Ok with the output so far. The process never exits.

let out = rubylang::run_program("puts gets.upcase", "hi\n")?;
assert_eq!(out, "HI\n");
assert!(rubylang::run_program("raise 'boom'", "").is_err());

[0x03] LANGUAGE FEATURES

Implemented and checked against the reference ruby:

  • Core objects & dispatch — Integer, Float, String, Array, Hash, Symbol, Range, Proc, with a growing core-method and Kernel surface.

  • Blocks / yield / closures — scope-sharing blocks with break / next / return control flow.

  • Classes — initialize, attr_*, instance variables, single inheritance, super (bare-forwarding and explicit-args, resolving through the singleton-class chain for def self.m class methods too), ancestor-chain method resolution, method chaining.

  • Modules — module + include mixins searched before the superclass; class methods via def self.m.

  • Exceptions — begin / rescue / ensure, method-body and statement-modifier rescue, raise with a message or an exception class, typed ZeroDivisionError / NoMethodError / ArgumentError and custom classes.

  • Parameters & assignment — splat parameters (def f(a, *rest)), block-pass by value (&:sym, &proc, &method(:m), &nil = no block) and Ruby 3 argument forwarding (def m(...) / m(...)), parallel assignment (a, b = 1, 2, array destructuring, swap, nested (a, (b, c)), d = … groups, a = *x, y), block- and method-parameter destructuring (map { |(a, b), i| … }, def f((a, b), c), nested and splat groups, ->((a, b)) { }), default arguments.

  • String interpolation — double-quoted #{} interpolation, plus the sigil shorthand ("count: #@n", "path: #$0", "#@@registry") in strings, heredocs, :"…" symbols, regex literals and %W[] / %I[] arrays.

  • Standard library — require-able builtin libs including json, set, date/time, securerandom, digest, base64, ostruct, socket (TCPServer/TCPSocket), sqlite3, and fiddle, plus bundled pure-Ruby uri, csv, optparse, and yaml (common-surface subsets, loaded from the binary with no external files).

  • Database persistence — require "sqlite3" gives a real, on-disk SQLite3::Database backed by a bundled SQLite (compiled in-tree, no external gem or FFI). The core sqlite3-gem shape: SQLite3::Database.new(path) / .open (and ":memory:"), block form that auto-closes, execute / execute2 with positional binds, rows as Arrays or (with results_as_hash = true) Hashes, get_first_row / get_first_value, last_insert_row_id / changes, and rescuable SQLite3::SQLException. The sqlite→Ruby type map is INTEGER→Integer, REAL→Float, TEXT→String, NULL→nil, BLOB→String. See examples/sqlite_persistence.rb.

  • ActiveRecord-style ORM — stdlib/active_record.rb is a real, pure-Ruby subset of Rails' ActiveRecord built on the bundled SQLite3::Database (no stubs, runs identically on rubylang and MRI). Covers connection management + table-name inference + PRAGMA schema introspection with dynamically-defined column accessors; a lazy chainable query Relation (where / order / limit / offset / pluck / first / last / count / exists? / find_each / where.not, every value ?-bound); finders (find / find_by / find_by!); persistence (create! / save! / update / destroy_all / update_all / reload, dirty tracking, new_record?); presence + query-backed uniqueness validations with an errors object (save returns false when invalid, save!/create! raise AR::RecordInvalid); before_save/after_save/before_create/after_create/ before_destroy callbacks; and belongs_to / has_many associations. See examples/orm_app.rb (CRUD) and examples/orm_blog.rb (associations, validations, callbacks, query chaining).

  • FFI via Fiddle — require "fiddle" gives real foreign-function calls: Fiddle.dlopen a shared library (or dlopen(nil) for the current process), resolve a symbol's address with handle[sym], then build a Fiddle::Function.new(addr, [arg_types], ret_type) and #call it. Arguments (Integer/Float/String) marshal to C and the result marshals back through libffi, with a runtime-determined signature — this is genuine C execution, not a shim. Fiddle::Pointer wraps bytes, reads a returned char* back into a Ruby String, and supports ptr[i]/ptr[i, len] reads plus ptr[i] = byte / ptr[i, len] = str writes (clamped to the allocation). The MRI type codes are provided (TYPE_VOID/TYPE_INT/ TYPE_LONG/TYPE_SIZE_T/TYPE_VOIDP/TYPE_DOUBLE/TYPE_CHAR/TYPE_SHORT/ TYPE_LONG_LONG and their unsigned negatives), and Fiddle::DLError is rescuable. FFI is inherently unsafe — a wrong signature can crash the process, exactly as MRI Fiddle documents.

    require "fiddle"
    libc = Fiddle.dlopen(nil)                                   # current process
    strlen = Fiddle::Function.new(libc["strlen"],
                                  [Fiddle::TYPE_VOIDP], Fiddle::TYPE_SIZE_T)
    strlen.call("hello")                                        # => 5
    sqrt = Fiddle::Function.new(libc["sqrt"],
                                [Fiddle::TYPE_DOUBLE], Fiddle::TYPE_DOUBLE)
    sqrt.call(16.0)                                             # => 4.0
    dup = Fiddle::Function.new(libc["strdup"],
                               [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOIDP)
    dup.call("world").to_s                                      # => "world"
    

    Boundary: Fiddle calls arbitrary C functions in a shared library — it is not a libruby C ABI. MRI-C-API extension gems (nokogiri, the C mysql2, etc.) link against libruby and its VALUE/rb_* internals; that ABI is a separate, much larger surface Fiddle does not provide, so those native gems do not load. Pure-Ruby gems and anything expressible as direct C calls do.


[0x04] COMMAND-LINE FLAGS

The ruby binary parses the ruby(1) option grammar (repeatable -e, bundled short switches, glued value switches like -Idir/-rlib, -- end-of-options, and program-file-vs-ARGV handling), so shebang scripts and tools that shell out to ruby work unchanged.

MRI-compatible switches

Flag Effect
FILE [args…] Run a .rb script; args become ARGV, $0/$PROGRAM_NAME/__FILE__ are set. Runs a matching --build bundle from the cache if one is current, else compiles fresh.
-e SRC [args…] Run a one-liner (repeatable; multiple -e are joined with newlines). Trailing args become ARGV; $0 is -e.
- Read the program from stdin (as a bare ruby with piped input does); $0/__FILE__ are - and the following tokens are ARGV.
-I DIR Prepend DIR to $LOAD_PATH (repeatable; glued -Idir or detached).
-r LIB require LIB before the program runs (repeatable).
-c Check syntax only — print Syntax OK, do not run.
-w / -W[level] Warning level → $VERBOSE. No switch → false; -W0 → nil; -W1 → false; -w, -W, -W2…-W7 → true. The level is scanned as octal, so -W8/-W9 are not levels — the digit is re-read as its own (invalid) switch. Last switch wins, so -w -W0 ends at nil. The level also seeds Warning[]: -W0 turns every category off, the default leaves only experimental on, and -w adds deprecated.
-W:CATEGORY Select a warning category (deprecated, experimental, performance, strict_unused_block, each also with a no- prefix) instead of a level; $VERBOSE is untouched. An unknown category warns and runs. Accepted but not yet applied: Warning[] keeps the level's defaults.
-d / --debug Set $DEBUG.
-S Search $PATH for the program file.
-v Print the version banner, then run any program — and run it verbosely ($VERBOSE = true), as --verbose does.
--verbose $VERBOSE = true, without the banner.
--version Print the version banner and exit.
-h / --help Print usage and exit.
--enable-FEATURE / --disable-FEATURE Toggle a feature; also spelled --enable=FEATURE, and the name takes - or _. FEATURE may be all or a comma-separated list. Known features are gems, error_highlight, did_you_mean, syntax_suggest, rubyopt, frozen_string_literal, yjit, zjit; an unknown one warns and runs. Last switch wins.
-- End of options; the next token is the program file, the rest is ARGV.

Of those features, two do something: frozen_string_literal sets what a file with no # frozen_string_literal: magic comment compiles as (a file that states its own setting always keeps it, so --enable cannot freeze a file that asked for false), and --disable-rubyopt makes RUBYOPT be ignored entirely. The rest are accepted with no effect so a command line written for MRI runs unaltered — there is no RubyGems to disable, and no YJIT/ZJIT.

RUBYOPT is honoured, and its switches are applied before the command line — so an explicit -W0 overrides a RUBYOPT=-w. Because the variable is ambient, only switches that cannot change what runs are accepted there: -I, -r, -d, -v, -w, -W, -K, -U, -E, --verbose, --debug, and the --enable-* / --disable-* families. Anything else (notably -e, the -n/ -p/-a/-l line-loop switches, -c, -S, -x, -0, --version, --help) is refused with invalid switch in RUBYOPT: ….

RUBY_VERSION reports 3.4.0 (the targeted MRI language level, so gems' required_ruby_version checks pass); RUBY_ENGINE is rubylang, RUBY_ENGINE_VERSION the crate version, RUBY_PLATFORM the host triple. The text-processing line-loop switches (-n/-p/-a/-l/-F) are parsed but not yet implemented (they need ARGF plus the Kernel $_ method family) and error out rather than silently mis-running.

rubylang extensions

Flag Effect
--repl Interactive REPL on a persistent host.
--lsp Language Server Protocol over stdio.
--dap Debug Adapter Protocol over stdio: source-line and function breakpoints, stepping, and the call stack. The variables request reports a method frame's parameters only, and evaluate is not implemented — it answers <cannot evaluate ...> for every expression.
--build FILE AOT-bundle the whole app — the entrypoint plus every file it statically requires / require_relatives — into one program in the on-disk cache. A later ruby FILE runs it directly, needing none of the required sources on disk.
--build --native FILE Emit a standalone native executable next to the script (app.rb → app). It runs the whole app with no ruby interpreter and no .rb sources present. fusevm's Cranelift AOT emitter compiles the main chunk and every method and block body to one native object; the full program (methods/classes/blocks/constants) is baked in and linked against the rubylang runtime (rustc + the crate rlib). Needs rustc and the build tree present.
--dump-tokens FILE Print the lexer token stream and exit.
--dump-ast FILE Print the parsed AST and exit.
--dump-bytecode FILE Print the lowered fusevm chunk and exit.
--disasm FILE Print a fusevm bytecode disassembly and exit.
--tiers FILE Run it, then report which fusevm execution tier took each of its chunks.

[0x05] ARCHITECTURE

rubylang contains no virtual machine or JIT of its own. The execution path mirrors how zshrs hosts zsh and elisp hosts Emacs Lisp:

Ruby source → lexer → parser (AST) → lower to fusevm bytecode → fusevm VM + Cranelift JIT
                                             │
                                RubyHost heap (methods, blocks, String/Array/Hash)
Piece How
fusevm-hosted No local vm.rs / jit.rs. Ruby lowers to fusevm bytecode and runs on the shared three-tier Cranelift JIT; jit-disk-cache persists native code across runs.
Native arithmetic Operators lower to native fusevm ops; a strict numeric hook supplies Ruby semantics (String/Array +, floored integer division, cross-type ==) only for non-numeric operands.
Reference-typed objects String, Array, and Hash live on the host heap behind Value::Obj handles, so a.push(x) mutates in place — real Ruby reference semantics.
Scope-sharing blocks Every variable access routes through the shared host, so a block run as a nested VM captures and mutates its enclosing locals.
GVL threading One process-global Mutex<RubyHost> heap (MRI's single-VM model). Threads share it; a Global VM Lock serializes execution (only the lock-holder runs Ruby), released around blocking waits. Local-var envs are Arc<Mutex> and fibers are thread-owned so the heap is Send.
Ruby truthiness Only nil and false are falsy — 0 and "" are true — so conditions normalize through a TRUTHY op before a native branch.

[0x06] PARITY HARNESS

Behaviour is checked against the reference ruby by a differential parity harness — cargo run --bin parity diffs the snippet corpus (tests/data/parity_corpus.rb) live against the system ruby, and tests/parity.rs replays the frozen outputs in CI with no ruby installed. Unimplemented METHODS raise undefined method rather than answering a plausible value. That guarantee does not extend to unimplemented CONSTANTS: a few native pseudo-modules (FileUtils, Socket) leave their constant bound to nil instead of raising NameError, a bare undefined identifier evaluates to nil rather than raising NameError, and a handful of flag-valued APIs answer a wrong number rather than refusing. BUGS.md lists them. (Errno is no longer among them: the Errno::* classes resolve by name, sit under SystemCallError, and carry #errno.)

Alongside the fixed corpus, a differential parity fuzzer — cargo run --bin parity-fuzz — generates thousands of seed-deterministic Ruby snippets across grammar-driven modes (arithmetic, float shortest-repr, slicing, enumerables, format specs, case/when, loop control flow including redo, Hash-through- Enumerable, Enumerator external iteration and laziness, keyword arguments, lambda-vs-proc arity, metaprogramming hooks, Comparable/Enumerable mixins, Set, Data, freeze, object introspection, Method reflection (#arity/#owner/#parameters), multi-value Enumerator yields, string encodings, byte strings, the Array#pack / String#unpack directive surface, the tr/squeeze/count/delete character sets, Complex, the object model (anonymous-class naming on constant assignment, instance_variable_* name validation, respond_to? visibility, String#succ carry rules), …) and diffs stdout + exit code of the reference ruby against rubylang. Every divergence is delta-debugged to a minimal reproducer and replays exactly with parity-fuzz --seed N --once. It runs subprocesses only (never links the library) and needs a reference ruby, so CI does not run it. --baseline FILE allowlists known gaps so only a new divergence fails the run; RUBYLANG_FUZZ_RUBY=PATH selects the oracle.

The examples/ directory holds runnable programs that double as tests: the test_*.rb scripts embed check assertions that abort on any divergence from Ruby, and tests/examples.rs runs every example through the binary in CI, asserting a clean exit and stdout matching the frozen reference output (cargo run --bin parity -- --freeze-examples regenerates it).


[0x07] STATUS & ROADMAP

The standalone ruby binary, the REPL, the rkyv bytecode cache, the LSP server, and the AOP method-intercept engine are all in the tree. before/after/ around advice registered via intercept(pattern, kind, handler) fires from the method-dispatch choke point, gated on an O(1) check so unadvised calls are unaffected.

ruby --build --native FILE compiles an app to a standalone native executable — no interpreter, no .rb sources at run time. fusevm's Cranelift AOT emitter lowers the main chunk and every method and block body into one relocatable object, one native driver per chunk; the full program (methods/classes/blocks/constants) is serialized and baked into a generated frontend, which rustc links against the rubylang runtime (the crate rlib, itself statically linking fusevm) plus that object. At startup the binary seeds the host as ruby FILE does — ARGV, $0, __FILE__, the prelude — loads the embedded program, and runs; a method or block call dispatches to its native driver. The run ends through the interpreter's own path, so exit, an uncaught exception's report and status, and at_exit handlers behave as under ruby FILE.

The DAP debugger (ruby --dap) sets source-line and function breakpoints (break on method entry), steps (next/stepIn/stepOut), and inspects the call stack; markers are emitted only in --dap mode, so normal runs are unaffected. Two limits: evaluate is wired but answers <cannot evaluate EXPR> for every expression, and variables reports only a method frame's parameters — a top-level frame answers an empty list, and locals assigned in a method body are absent. Regex literals (/pat/flags), =~/!~, String#{match,scan,match?,sub,gsub} with Regexp, MatchData, and arbitrary-precision Integer (auto-promotion on overflow) are supported. A Regexp is a value as well as a matcher: ==, eql? and hash compare its source and option bitmask, so /a/ == /a/ and it works as a Hash key. Set#<=> answers the subset relation (nil when neither set contains the other), Enumerator::Lazy#uniq streams over an infinite source, and everything derived from <=> treats an unrankable pair the way Ruby does: the Comparable operators raise ArgumentError rather than answering false (Rational(1, 2) < Float::NAN), and so do sort/min/max and their _by and block forms ([1, "a"].sort), while Array#<=> answers nil. between? and clamp are one implementation across Comparable, Integer, Float, String and Rational, keeping the two rules that differ — clamp rejects a min above its max and skips a nil bound, between? does neither. extend / prepend / class << self, the full case/in pattern surface (two-sided find patterns, **nil exact-key matching, alternation binding, the deconstruct/deconstruct_keys protocol on user objects) plus the one-line forms (expr => pattern rightward assignment and expr in pattern boolean match), reserved-word keyword labels (def f(class:)), Date/DateTime, Time (an exact Rational instant viewed in UTC, the local zone or a fixed offset, with MRI's strftime), Binding (binding, eval(str, b), ERB#result(b)), output capture through a reassigned $stdout, bare %(…) strings, and __END__ are all implemented. at_exit handlers run last-registered first as the program ends (after an uncaught exception too), and an exception carries the backtrace its raise unwound through, rendered by full_message(highlight:, order:) as MRI prints it and read back as Thread::Backtrace::Locations by backtrace_locations; a method or block written in a required file reports that file and its own lines wherever it is called from, under <top (required)> and the Kernel#require / #require_relative / #load frame that ran it. An object's singleton_class reflects what extend and def obj.m did to it (ancestors, include?, instance_methods(false), Method#owner), and Object#singleton_method, #public_method and Module#included_modules are implemented. See BUGS.md for the full known-gaps list.


[0x08] DOCUMENTATION


[0xFF] LICENSE

MIT — free and open source. See LICENSE.