From e890aabdacc8f5ebc04aa53d38224fb44e58de2d Mon Sep 17 00:00:00 2001 From: tannevaled Date: Sat, 26 Sep 2026 14:32:30 +0200 Subject: [PATCH] README: the measured conformance figure, an embedding section, and the browser build that does not build Every factual claim here was re-measured on 3e8e3cc (darwin/arm64) against MRI 4.0.5 on the same host. What changed, and what condemned it: - Conformance: 21,982 passing / floor 21,970 -> measured 22,488 / floor 22,475. Three independent runs (run.sh at two different per-file timeouts and job counts, plus a separate sweep tallying all four counters) each reported exactly 22,488. fail/error/skip are 1,090/538/477, so the share of examples that ran and passed is 93.3%, not 91.4%. The old section also quoted 91.4% in its table and 91.1% in its prose. - Removed the "no line map, __LINE__ is always 0" section, which the README called its single widest gap. It no longer reproduces: rbgo and MRI now agree exactly on __LINE__, on backtrace line numbers, on warn(uplevel:) prefixes and on const_source_location. - Removed the intermittent autoload_spec.rb crash. Five consecutive runs of that file gave identical results and three full corpus sweeps never saw it fail, so the run-to-run spread the README told readers to expect is not reproducible here. - Added: GOOS=js GOARCH=wasm does not compile. internal/vm/errno.go references three syscall constants the js port lacks. It built at 68cb53a, the commit before the Errno subsystem landed, and no CI lane catches it because only wasip1 is gated. The README had called the browser a first-class/supported target. - Added: $stderr is not a separate stream. The VM takes one writer and wires $stderr/STDERR to it, so warn and $stderr.puts arrive on stdout; only the CLI's uncaught-exception printer uses real stderr. - Added an "Embedding in a Go program" section. There was none, in the repository whose org is called go-embedded-ruby. The public surface is one function, ruby.Run(src, out); the documented contract (merged streams, fresh VM per call, exceptions as Go errors, require_relative resolving against the process working directory) was established by compiling and running a probe against it. - Added, each verified against MRI: RUBY_VERSION reports 3.4.1; magic encoding comments are not honoured; pp does not exist. Errno's "32 diverging constants" survived checking - by set difference, 81 names are zero-valued under rbgo and 49 under MRI, with every MRI zero also zero under rbgo. - Platforms now follow ci.yml: the four exotic arches are nightly, not per-PR. - Quick start commands all executed. Noted that rbgo build must run from a checkout, which it does not say today and which fails confusingly elsewhere. FLOOR is untouched. Co-Authored-By: Claude Opus 5 --- README.md | 481 +++++++++++++++++++++++++++++------------------------- 1 file changed, 256 insertions(+), 225 deletions(-) diff --git a/README.md b/README.md index 36b6462e..0860500e 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,19 @@ [![Docs](https://img.shields.io/badge/docs-mkdocs--material-9B1C2E)](https://go-embedded-ruby.github.io/docs/) [![License](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE) [![Go](https://img.shields.io/badge/go-1.26.4%2B-00ADD8)](https://go.dev/dl/) -[![Phase](https://img.shields.io/badge/phases-6%20%2B%208%20in%20progress-1a7f37)](https://go-embedded-ruby.github.io/docs/roadmap/) +[![ruby/spec](https://img.shields.io/badge/ruby%2Fspec-22%2C488%20examples%20passing-1a7f37)](#runtime-conformance--rubyspec) -**A pure-Go implementation of Ruby — one static binary, full dynamism, zero cgo.** +**A Ruby interpreter written in pure Go, with cgo disabled** — so you can embed it +in a Go program with `import "github.com/go-embedded-ruby/ruby"`, or ship it as a +single static binary that cross-compiles wherever Go does, with no C toolchain and +no libruby. + +**How complete is it?** It runs **22,488** of ruby/spec's `language/` + `core/` +examples ([what that counts](#runtime-conformance--rubyspec)) — a large and growing +subset of the language, and **not** a drop-in replacement for CRuby. Read +[What does not work yet](#what-does-not-work-yet) before you depend on it; the +embedding API is currently **one function**, and the browser WebAssembly target +does not build today. This repository is the interpreter: a compiler that lowers Ruby to bytecode, and a stack VM (mruby/YARV lineage) that runs it. The Ruby **front-end** (lexer, @@ -107,81 +117,62 @@ GUI toolkit), `require "tui"` (terminal-cell toolkit) and `require "mvvm"` ## Status -### Runtime conformance — ruby/spec (measured 2026-09-23) +### Runtime conformance — ruby/spec + +The honest summary: **rbgo runs a large and growing subset of Ruby, and is not a +drop-in replacement for CRuby.** The number below is the best evidence available, +and it is worth understanding exactly what it counts. -Since July the work has been **runtime** conformance: making the VM behave as -Ruby does, measured against [ruby/spec](https://github.com/ruby/spec)'s -`language/` and `core/` suites. Measured with -`scripts/conformance/rubyspec/run.sh` on darwin/arm64 against the pinned corpus -at `SPEC_SHA=87b1631992bd00cf0c4934474766d54dad088191`, on `d498ddc` — the tip -of `main` at the time, including -[#629](https://github.com/go-embedded-ruby/ruby/pull/629). `main` has since -advanced to `2200e17`, whose only change is the `FLOOR` file -([#638](https://github.com/go-embedded-ruby/ruby/pull/638)); the interpreter -built from it is byte-identical, so these figures stand unchanged. +**What is measured.** The `language/` and `core/` suites of +[ruby/spec](https://github.com/ruby/spec) — the executable specification of the +Ruby language and its core library — run through rbgo by +`scripts/conformance/rubyspec/run.sh`. Each spec file runs in its own `rbgo` +process under a minimal MSpec-compatible shim that ships with this repo. | | | | --- | --- | -| **passing examples** | **21,982** — four consecutive runs, all four identical | -| fail / error | 1,321 / 740 | -| skipped | 473 | -| pass rate of examples that ran | **91.4 %** (21,983 of 24,044) | -| spec files | 2,191 of 2,206 produce a result; 15 produce none | -| **CI floor** (`FLOOR`) | **21,970** | - -(The ratchet reports 21,982; a separate sweep capturing `fail`/`error`/`skip` as -well read 21,983. The one-example difference is the `#615` noise below.) - -**The floor is not the score, and the two are close on purpose.** `FLOOR` says -*"no run may come in below this"* — a shrink-only ratchet, raised in its own PR -after a wave lands. The measured total sits **above** it, but only just: 21,982 -against 21,970 is a margin of **12**. That is deliberate. The floor is set a -handful of examples below the **lowest observed run** — enough to absorb the -run-to-run jitter of [#615](https://github.com/go-embedded-ruby/ruby/issues/615), -and no more, because a floor slack enough to hide the loss of a whole spec file -would defeat the thing the ratchet exists to catch. So a small gap is the ratchet -working; a large one would mean it had gone slack. - -They remain different claims. The floor is the **guarantee CI enforces**; the -measured total is **what rbgo does** on a given run. Quoting the floor as the -conformance figure understates rbgo by the margin; quoting the measured total as -a guarantee overstates it by the same amount. - -**Run-to-run spread is possible and is a known bug, not noise in the method.** -`core/module/autoload_spec.rb` crashes intermittently while popping a frame -([#615](https://github.com/go-embedded-ruby/ruby/issues/615)), and the whole -file's examples are lost when it does — an earlier set of four runs on `68cb53a` -spread 21,845–21,903 for exactly that reason. The four runs above happened not to -hit it; the issue is open, so run it more than once and take the *low* run as the -guaranteed figure. - -> **Not every gain is VM conformance.** Two of the recent jumps came from fixing -> the **measurement**, not the interpreter, and it is worth keeping them apart: -> -> - **The mspec shim** ([#624](https://github.com/go-embedded-ruby/ruby/pull/624), -> refs [#621](https://github.com/go-embedded-ruby/ruby/issues/621)) ran each -> example under `instance_eval`, so a helper defined in an outer `describe` was -> unreachable from a nested one. `core/string/valid_encoding/utf_8_spec.rb` -> scored **0 of 28 — and 0 of 28 under MRI 4.0.5 too**, through the same shim. -> Fixing the shim moved the corpus 20,905 → 20,936, of which **28 are -> attributable**. -> - **The parser upgrade to v0.2.0** -> ([#625](https://github.com/go-embedded-ruby/ruby/pull/625)) made **13 -> `language/*_spec.rb` files parseable that had never parsed at all**. They had -> been contributing zero to *both* columns — not failing, invisible. `language/` -> went 1,443 → 1,776 passing (+333), while `fail+error` rose 283 → 436, because -> those files brought their own failures with them. -> -> Both are gains in what the measurement can **see**, not in what the VM can -> **do**. The rest of the climb — the floor went from **6,000** when the ratchet -> landed on 2026-08-03 ([#263](https://github.com/go-embedded-ruby/ruby/pull/263)) -> to **21,970** today, across 27 conformance waves — is the VM. - -There is no honest denominator for "percent of Ruby". 91.1 % is the share of the -examples *this shim actually ran*; the shim is not mspec, it stubs some matchers -(so their examples are **skipped**, not passed), and 473 skips and 15 unreadable -files sit outside the ratio entirely. - +| **passing examples** | **22,488** | +| failing / erroring examples | 1,090 / 538 | +| skipped (a matcher our shim does not implement) | 477 | +| examples that actually ran (pass + fail + error) | 24,116 | +| share of those that passed | **93.3 %** | +| spec files | 2,196 of 2,206 produced a result; 10 produced none | +| **floor enforced by CI** (`FLOOR`) | **22,475** | + +Measured 2026-09-26 on `3e8e3cc`, darwin/arm64, against the corpus pinned at +`SPEC_SHA=87b1631992bd00cf0c4934474766d54dad088191`. Three independent runs — two +through `run.sh` (at different per-file timeouts and different parallelism) and +one through a separate sweep that tallies all four counters — each reported +exactly **22,488**, with the same 10 files producing no result. + +**What this number is *not*.** It is *not* "rbgo implements 93 % of Ruby", and +there is no honest way to turn it into a percentage of the language: + +- **Only `language/` and `core/` are swept.** ruby/spec's `library/`, `optional/` + and `security/` trees are **not run at all**. Most of what people mean by "the + standard library" is outside this measurement. (rbgo does bind a large set of + stdlib and gem replacements — see *Supported today* — but their conformance is + not what this figure reports.) +- **The shim is not MSpec.** A few matchers (`be_computed_by`, `ruby_exe`, some + `argf`/IO helpers) are stubbed, so the examples that need them are counted as + **skipped**, not passed. That makes the total a conservative lower bound. +- **Skips are outside the ratio.** The 93.3 % divides passes by the examples that + ran; the 477 skips and the 10 unreadable files are in neither column. +- **An "example" is not a feature.** Examples are not weighted, so a heavily + specified method contributes far more than a rarely used one. + +**The floor and the score are different claims.** `FLOOR` is a shrink-only +ratchet: CI fails if a run comes in below it, so conformance is tracked and can +only go up. The floor is therefore the level **CI guarantees**; the measured total +is **what rbgo did on a given run**. Quoting the floor understates rbgo by the +margin between them; quoting the measured total as a guarantee overstates it by +the same amount. + +**Reproduce it yourself:** + +```sh +scripts/conformance/rubyspec/run.sh # clones the pinned corpus on first run +``` ### Front-end conformance & performance (campaign final, 2026-06-27) A major conformance + performance campaign measured rbgo's pure-Go **front-end @@ -593,177 +584,220 @@ throughput tracks the underlying driver rather than the interpreter: `eval`/`require` calls (if any) would raise in the closed binary, since there is no front-end left to compile source at runtime. -- **WebAssembly (`GOOS=js GOARCH=wasm`) is a supported target.** rbgo runs in the - browser two ways: the **playground** ships the full interpreter (front-end + - VM + numeric/image stack) as a wasm module that evaluates arbitrary Ruby in the - page (see [Run in the browser](#run-in-the-browser--webassembly)); and - **`rbgo build --closed --target wasm app.rb`** cross-compiles a closed-world - wasm module that runs *that one program* (no front-end linked) and can drive - the page's DOM/Canvas through the built-in `JS` module - (`JS.document`/`JS.log`/`JS::Ref#call`/`JS.raf`). - -### Not implemented — the limitations worth naming - -Measured on `main` (`d498ddc`), darwin/arm64, against MRI 4.0.5 on the same host. - -**rbgo carries no line map, so `__LINE__` is always `0`.** This is the single -widest gap, because three separate features are built on source positions and all -three are lost: - -```ruby -# probe.rb, line 1 is the puts -puts __LINE__ # rbgo: 0 MRI: 1 -def f; warn "msg", uplevel: 0; end -f # rbgo: "warning: msg" - # MRI: "probe.rb:2: warning: msg" -begin; raise "boom"; rescue => e; puts e.backtrace.first; end - # rbgo: "probe.rb:0:in '
'" - # MRI: "probe.rb:4:in '
'" -p Object.const_source_location(:Comparable) # rbgo: nil MRI: [] +- **WebAssembly:** the **WASI** target (`GOOS=wasip1 GOARCH=wasm`) builds and runs, + and is gated in CI. The **browser** target (`GOOS=js GOARCH=wasm`) does **not** + currently build — the playground under `cmd/wasm`, the `JS` bridge and + `rbgo build --closed --target wasm` are all blocked behind one compile error in + `internal/vm`. See [WebAssembly](#webassembly) and *What does not work yet*. + +### What does not work yet + +Every entry below was re-checked on `3e8e3cc` (darwin/arm64, 2026-09-26) by running +it against **MRI 4.0.5 on the same host**. Entries that no longer reproduced have +been removed. + +**The browser WebAssembly target does not currently build.** `GOOS=js GOARCH=wasm` +fails to compile, because `internal/vm/errno.go` references three `syscall` +constants that the `js` port does not define: + +```console +$ CGO_ENABLED=0 GOOS=js GOARCH=wasm go build ./cmd/rbgo +# github.com/go-embedded-ruby/ruby/internal/vm +internal/vm/errno.go:101:35: undefined: syscall.ENOTRECOVERABLE +internal/vm/errno.go:108:35: undefined: syscall.EOWNERDEAD +internal/vm/errno.go:120:35: undefined: syscall.ETXTBSY +``` + +This affects the playground (`./cmd/wasm`) and the closed-world browser build +(`rbgo build --closed --target wasm`) alike, since both link `internal/vm`. It is a +recent regression — the same build succeeded at `68cb53a`, the commit before the +Errno subsystem landed — and no CI lane catches it, because only the **`wasip1`** +wasm target is gated. **`GOOS=wasip1 GOARCH=wasm` does build and run** (see +*Platforms*), so server-side/WASI WebAssembly is unaffected. + +**`$stderr` is not a separate stream.** The VM is constructed with a single output +writer, and `$stderr`/`STDERR` are wired to it, so anything a Ruby program sends to +`$stderr` — including `warn` — arrives on **stdout**: + +```console +$ rbgo -e '$stdout.print "O"; $stderr.print "E"' >out.txt 2>err.txt +$ cat out.txt; echo "[err: $(cat err.txt)]" +OE[err: ] ``` -Every backtrace frame reports line `0`; `warn(uplevel:)` emits the message with -no `file:line:` prefix; `const_source_location` answers `nil`. Nothing here is a -partial implementation to be tuned — the information is not recorded. +Uncaught exceptions are the exception to this: the CLI prints those to real stderr +itself. Redirecting `2>` to separate diagnostics from program output therefore does +not work as it does under MRI. -Otherwise, and each with an open issue that states it precisely: +Otherwise: -| | | +| | how it differs from MRI 4.0.5 | | --- | --- | -| `Errno` carries all **158** of MRI's constants, but **32** of them report errno `0` on darwin where MRI has a real number (`EAUTH` 0 vs 80, `EBADRPC` 0 vs 72, `EDEVERR` 0 vs 83, …). Go's portable `syscall` package does not expose the platform-only names. Nothing else about the table disagrees: all 158 names are present under both, and the other 126 numbers match exactly | [#633](https://github.com/go-embedded-ruby/ruby/issues/633) | -| `Numeric#to_int` is **not defined**, so `Complex(2.9, 0).to_int` raises `NoMethodError` where MRI returns `2` | [#631](https://github.com/go-embedded-ruby/ruby/issues/631) | -| `File::Stat#==` answers identity: `a.==(b)` is `true` (Comparable) while `a == b` is `false` | [#632](https://github.com/go-embedded-ruby/ruby/issues/632) | -| `File#stat` cannot answer for a file unlinked while open — rbgo's streams are buffered by path and hold no descriptor | [#635](https://github.com/go-embedded-ruby/ruby/issues/635) | -| **Windows:** no text-mode newline translation — CRLF reaches the reader as written | [#610](https://github.com/go-embedded-ruby/ruby/issues/610) | -| **Windows:** `File::Stat#atime`/`#ctime` fall back to mtime; `#birthtime` raises | [#635](https://github.com/go-embedded-ruby/ruby/issues/635) | -| **Windows:** `File.realpath` does not expand 8.3 short names (`RUNNER~1`) | [#636](https://github.com/go-embedded-ruby/ruby/issues/636) | -| `core/module/autoload_spec.rb` crashes intermittently popping a frame, costing its whole file from the measurement | [#615](https://github.com/go-embedded-ruby/ruby/issues/615) | -| **`Process.fork` does not exist** — Go's runtime cannot be forked safely | — | -| `BEGIN { }` / `END { }` blocks do not parse (the one construct of 41 probed where MRI accepts and the front-end refuses) | front-end | - -Two further entries are **harness**, not interpreter, and are listed here only so -that nobody reads them as VM gaps: the conformance shim's `SPEC_TMP_BASE` is -`/tmp`, a symlink on darwin, which fails 11 `realpath`/`realdirpath` examples on a -path that is correct ([#630](https://github.com/go-embedded-ruby/ruby/issues/630)); -**MRI 4.0.5 fails them the same way through the same shim**. And the shim's -`instance_eval` rebinding ([#621](https://github.com/go-embedded-ruby/ruby/issues/621)) -is largely fixed but not closed. - -**100% coverage** is enforced in CI on the two **POSIX** lanes — ubuntu and -macOS. The full `-race` suite also runs on **windows**, but the coverage gate is -not applied there: a few POSIX-only paths (opening `/dev/null` as a character -device) are unreachable, so its measured coverage is structurally below 100 %. -Per-PR architecture cover is the two **native** lanes, `amd64` and `arm64`, which -run `go test ./...` (not the coverage gate); the four exotic 64-bit targets -(`riscv64`/`loong64`/`ppc64le`/`s390x`) are validated **off** the per-PR path — -nightly under QEMU and on scheduled real hardware. A `wasip1/wasm` lane builds and -runs the interpreter under wazero. `.github/workflows/ci.yml` is the authority. -Phase 8 (conformance and -representation/perf tuning) is well advanced. The 2026-06 campaign brought the -**front-end** to ~100 % parse / 99.82 % parse+compile on real-world Ruby; since -July the work has been **runtime** conformance, and the ruby/spec ratchet has -gone from a floor of 6,000 to 21,970 across 27 waves, measuring **21,982** -passing examples today. On the performance side small-integer interning and capture-tracked -frame-environment recycling have cut call-path allocations (a small-int loop from -~245k allocations to 1; recursion's call allocations halved, ~14% faster), with -the 6-runtime benchmark suite ([BENCHMARKS.md](BENCHMARKS.md)) tracking rbgo vs -MRI / YJIT / JRuby / TruffleRuby. The road from "parses + compiles" to "runs whole -applications" — the runtime stdlib + C-extension surface — is now well underway: -**the real `puppet apply` CLI runs end-to-end** (see *Running Puppet* above), -converging `notify`, `file` and `exec` resources and exiting cleanly, with the -broader resource providers (`package` / `service`) the active next milestone. -See the -[roadmap](https://go-embedded-ruby.github.io/docs/roadmap/). +| `RUBY_VERSION` | rbgo reports `"3.4.1"`; the differential oracle it is developed against is MRI 4.0.5 | +| `Numeric#to_int` | not defined — `Complex(2.9, 0).to_int` raises `NoMethodError`; MRI returns `2` | +| `File::Stat#==` | `a == b` is `false` for two stats of the same file (MRI: `true`); `a.==(b)` answers `true` | +| `File#stat` on a file unlinked while open | raises `Errno::ENOENT`; MRI answers from the open descriptor. rbgo's streams are buffered by path and hold no descriptor | +| `Errno` | all **158** of MRI's constant names are present, but **32** report errno `0` where MRI has a real number (`EAUTH`, `EBADRPC`, `EDEVERR`, …). Measured by set difference on darwin: 81 names are zero-valued under rbgo, 49 under MRI, and every MRI zero is also zero under rbgo. Go's portable `syscall` package does not expose the platform-only names | +| magic encoding comments | `# encoding: ascii-8bit` is not honoured — a literal still reports `UTF-8`, where MRI reports `ASCII-8BIT` | +| `pp` | neither `Kernel#pp` nor `require "pp"` exists (`require "prettyprint"` does work) | +| `Process.fork` | does not exist — Go's runtime cannot be forked safely | +| `BEGIN { }` / `END { }` | do not parse (`parse error: unexpected "{" after statement`). Everything else the front-end was known to refuse now parses — see [go-ruby-parser](https://github.com/go-ruby-parser/parser) | +| `Thread#backtrace` for another thread | raises `NotImplementedError`; rbgo keeps one frame stack per VM, not per thread | + +## Platforms + +`.github/workflows/ci.yml` is the authority; this is what it actually runs. + +**On every pull request:** + +| Lane | What runs | +| --- | --- | +| **linux, macOS, windows** | the full suite under `-race`. The **100 % coverage gate** is enforced on linux and macOS only — a few POSIX-only paths (opening `/dev/null` as a character device) are unreachable on windows, so its coverage is structurally below 100 % | +| **amd64, arm64** | `go test ./...` on native runners | +| **wasip1/wasm** | built with `CGO_ENABLED=0 GOOS=wasip1 GOARCH=wasm` and **run** under [wazero](https://wazero.io), a pure-Go runtime — verified here: `wazero run rbgo.wasm -e 'puts (1..10).sum'` prints `55` | + +**Not on the pull-request path** — validated on a nightly schedule instead: +`riscv64`, `loong64`, `ppc64le` and `s390x`, under QEMU +(`arch-qemu-nightly.yml`) and natively on real hardware (`native-arch.yml`: the +GCC Compile Farm, plus an IBM LinuxONE s390x host). + +**`GOOS=js GOARCH=wasm` (the browser) has no CI lane and does not currently +build** — see *What does not work yet*. + +## Try it in one command + +No checkout, no toolchain beyond Go itself: + +```console +$ go run github.com/go-embedded-ruby/ruby/cmd/rbgo@latest -e 'puts "hello from rbgo"; puts (1..10).sum' +hello from rbgo +55 +``` + +(The first run compiles the interpreter, which takes a while and produces a large +binary. There are no version tags yet, so `@latest` resolves to the tip of `main`.) ## Quick start -Requires **Go 1.26.4+**. +Requires **Go 1.26.4+**. From a checkout: -```bash -# run a one-liner -go run ./cmd/rbgo run -e 'puts 1 + 2' # => 3 +```console +$ go build -o rbgo ./cmd/rbgo # CGO_ENABLED=0 is the default here +$ ./rbgo -e 'puts 1 + 2' +3 +``` -# run a file -cat > fib.rb <<'RB' +Run a file: + +```console +$ cat > fib.rb <<'RB' def fib(n) - if n < 2 - n - else - fib(n - 1) + fib(n - 2) - end + n < 2 ? n : fib(n - 1) + fib(n - 2) end puts fib(20) RB -go run ./cmd/rbgo run fib.rb # => 6765 +$ ./rbgo fib.rb +6765 +``` -# build the CLI -go build -o rbgo ./cmd/rbgo -./rbgo fib.rb +`rbgo build` compiles a program's lowerable methods to native Go and links a +specialised binary. **It must be run from a checkout of this repository**, because +it shells out to `go build` against this module — run elsewhere it fails with +`stat .../cmd/rbgo: directory not found`: -# AOT-compile a program's methods to native code and link a specialised binary -./rbgo build -o fib fib.rb # fib (the method) becomes native int64 -./fib fib.rb # => 6765 +```console +$ ./rbgo build -o fib fib.rb +rbgo build: fib (1 method(s) AOT-compiled: Object#fib) +$ ./fib fib.rb +6765 +``` -# closed-world: bake the program in as bytecode and drop the front-end -./rbgo build --closed -o fib fib.rb # no lexer/parser/compiler linked -./fib # => 6765 (runs with no source file) +Add `--closed` to bake the program in as bytecode and drop the front-end entirely, +giving a binary that needs no source file: -# WebAssembly: cross-compile a closed-world program to a browser wasm module -./rbgo build --closed --target wasm -o app.wasm app.rb # GOOS=js GOARCH=wasm +```console +$ ./rbgo build --closed -o fib fib.rb +rbgo build: fib (1 method(s) AOT-compiled: Object#fib) +rbgo build: closed-world — front-end dropped (no lexer/parser/compiler linked) +rbgo build: binary size 172.5 MiB +$ ./fib +6765 ``` -## Run in the browser — WebAssembly - -**`GOOS=js GOARCH=wasm` is a first-class target.** Everything is pure Go with cgo -disabled, so the interpreter, the numeric stack and the cgo-free image pipeline -compile to a single wasm module and run **entirely in the browser** — there is no -server-side code. There are two ways to ship Ruby to the browser: - -> **js/wasm excludes the network/OS gem backends.** A browser has no TCP sockets -> and no cgo, so the gems whose backends open real sockets or use OS facilities -> are compiled out of the `GOOS=js GOARCH=wasm` build (they carry a -> `//go:build !(js && wasm)` tag, which also keeps ~90 MB of driver code out of -> the module). On wasm, `require` of any of them raises a clean Ruby `LoadError` -> (`cannot load such file -- kafka (not available in the wasm build)`): -> **`grpc`**, **`nats`**, **`kafka`**, **`mysql2`/`mysql`**, **`mongo`/`bson`**, -> **`arrow`**, **`parquet`**, **`openstack`**, **`sidekiq`**, **`resque`** (the -> last two are the `redis`-backed job queues). A second tier — -> **`sqlite3`**, **`sequel`**, **`activerecord`**, **`bolt`**, **`bleve`**, -> **`etcd`** — still `require`s successfully but raises when a connection/handle -> is constructed (e.g. `SQLite3::Database.new`), because their drivers do not -> build for wasm. The **native build is unchanged**: every gem is present, loads -> and conforms exactly as before. Plain Ruby, the numeric/image stack and the -> `JS` DOM/Canvas bridge are fully available in the browser. - -**1. The playground — full interpreter in wasm.** A self-contained page (Ruby -REPL + a load→`gaussian_blur`/`sobel`/`canny`→render image demo) lives in -[`web/`](web). It builds `cmd/wasm`, which links the whole front-end (lexer, -parser, compiler) and VM, so the page can evaluate *arbitrary* Ruby typed by the -user: +## Embedding in a Go program -```bash -./web/build.sh serve # build web/rbgo.wasm and serve http://localhost:8080 +The public API is deliberately tiny — **one function**: + +```go +package ruby // github.com/go-embedded-ruby/ruby + +func Run(src string, out io.Writer) error ``` -The module publishes `rbgoEval(src)` and `rbgoImage(src, bytes)` on the JS global -object; see [web/README.md](web/README.md) for the bridge. +`Run` parses, compiles and executes `src` on a **fresh VM**, writing the program's +output to `out`. Everything else in this repository is under `internal/`, so this +is the whole embedding surface today. -**2. `rbgo build --target wasm` — a closed-world wasm app.** To ship *one* Ruby -program (not a REPL), AOT-bake it into a closed-world wasm module that drops the -front-end: +```go +package main -```bash -./rbgo build --closed --target wasm -o app.wasm app.rb +import ( + "bytes" + "fmt" + + "github.com/go-embedded-ruby/ruby" +) + +func main() { + var out bytes.Buffer + if err := ruby.Run(`puts "hello from Ruby"`, &out); err != nil { + panic(err) + } + fmt.Printf("%q\n", out.String()) // "hello from Ruby\n" +} +``` + +The contract, as measured rather than intended: + +- **One writer, both streams.** There is no separate stderr. `$stdout`, `$stderr` + and `warn` all land in `out`: running + `$stdout.print "O"; $stderr.print "E"; warn "W"` fills the buffer with `"OEW\n"`. + If you need the two apart, you cannot get it through this API. +- **A Ruby exception becomes a Go `error`.** Running `raise ArgumentError, "bad"` + returns an error whose message is `ArgumentError: bad`, and writes nothing to + `out`. A syntax error comes back the same way, with a line number: + `parse error at line 1: ...`. +- **Every call is a fresh VM.** A global set in one `Run` is gone in the next, and + nothing is shared between calls. There is no exported way to hold a VM open, + pre-load code into it, call a Ruby method from Go, or pass Go values in. +- **`require_relative` resolves against the process working directory**, not + against a script, because `Run` has no file to anchor to. From a different + working directory the same program fails with + `LoadError: cannot load such file -- /tmp/lib`. + +The VM stays alive after `Run` returns as long as something still references it — +which is what lets an event-driven embedded program keep running. + +## WebAssembly + +**WASI (`GOOS=wasip1 GOARCH=wasm`) works and is gated in CI.** The interpreter +builds with cgo disabled and runs under any WASI runtime: + +```console +$ CGO_ENABLED=0 GOOS=wasip1 GOARCH=wasm go build -o rbgo.wasm ./cmd/rbgo +$ wazero run rbgo.wasm -e 'puts (1..10).sum' +55 ``` -`--target wasm` requires `--closed` (the wasm entry runs the embedded program, -then parks the Go runtime with `select{}` so JS callbacks keep firing). The -program can reach the page through the built-in **`JS` module** — `JS.global`, -`JS.window`, `JS.document`, `JS.log`, `JS::Ref#get`/`set`/`call`/`[]`/`on` for -DOM and Canvas, and `JS.raf { |t| … }` for an animation loop — so a closed-world -wasm app can render and handle events with no JavaScript of its own. Serve the -emitted `app.wasm` next to Go's `wasm_exec.js` loader. +**The browser target (`GOOS=js GOARCH=wasm`) does not currently build** — see +*What does not work yet*. The playground under `./cmd/wasm`, the `JS` bridge and +`rbgo build --closed --target wasm` are all blocked behind that compile error, so +treat the browser story as unavailable until it is fixed. +On any wasm target the gem backends that need real sockets or OS facilities are +compiled out (`grpc`, `nats`, `kafka`, `mysql2`, `mongo`/`bson`, `arrow`, +`parquet`, `openstack`, `sidekiq`, `resque`, …); `require` of one raises a clean +Ruby `LoadError` rather than failing to link. ## Layout ``` @@ -805,13 +839,10 @@ oracle below: the ratchet is the absolute floor, the oracle catches divergences the specs don't cover. **The floor and the measurement are two different numbers.** `FLOOR` is -**21,970** — the level CI refuses to fall below, raised there in -[#638](https://github.com/go-embedded-ruby/ruby/pull/638) after wave 27. A run -measures **21,982** passing, four consecutive runs all identical: a margin of 12, -which is the size it is meant to be (see *Runtime conformance* for why). See -*Runtime conformance* above for the full breakdown, the run-to-run spread -([#615](https://github.com/go-embedded-ruby/ruby/issues/615)) and what the ratio -does and does not mean. +**22,475** — the level CI refuses to fall below. A run measured here on `3e8e3cc` +reports **22,488** passing. The floor is the guarantee; the measured total is what +one run did. See *Runtime conformance* above for the full breakdown, the method, and +what the ratio does and does not mean. ```bash scripts/conformance/rubyspec/run.sh # measure vs the floor @@ -858,9 +889,9 @@ On top of the front-end sweeps, a **ruby/spec ratchet** runs the `language/` and specification of the language — through `rbgo` under a minimal MSpec-compatible shim, and gates CI on a **shrink-only floor** of passing examples ([`scripts/conformance/rubyspec/`](scripts/conformance/rubyspec/), floor in -`FLOOR`, currently **21,970**). The floor can only be raised, so measured +`FLOOR`, currently **22,475**). The floor can only be raised, so measured language conformance moves in one direction — but the floor is a *gate*, not the -result: the measured total is **21,982**. Run it with +result: the measured total is **22,488**. Run it with `scripts/conformance/rubyspec/run.sh`, and see *Runtime conformance* under *Status* for the full breakdown.