2.3.0 • Published 5 months ago

ruby-head-wasm-wasi v2.3.0

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

ruby-head-wasm-wasi

WebAssembly port of CRuby with WASI.

This package distributes the latest master branch of CRuby.

Installation

For instaling ruby-head-wasm-wasi family, just run this command in your shell:

$ npm install --save ruby-head-wasm-wasi@latest
# or if you want the nightly snapshot
$ npm install --save ruby-head-wasm-wasi@next
# or you can specify the exact snapshot version
$ npm install --save ruby-head-wasm-wasi@0.3.0-2022-04-16-a

Quick Start (for Node.js)

See the example project for more details.

import fs from "fs/promises";
import { DefaultRubyVM } from "ruby-head-wasm-wasi/dist/node.cjs.js";

const main = async () => {
  const binary = await fs.readFile(
//  Tips: Replace the binary with debug info if you want symbolicated stack trace.
//  (only nightly release for now)
//  "./node_modules/ruby-head-wasm-wasi/dist/ruby.debug.wasm"
    "./node_modules/ruby-head-wasm-wasi/dist/ruby.wasm"
  );
  const module = await WebAssembly.compile(binary);
  const { vm } = await DefaultRubyVM(module);

  vm.eval(`
    luckiness = ["Lucky", "Unlucky"].sample
    puts "You are #{luckiness}"
  `);
};

main();

Then you can run the example project in your terminal:

$ node --experimental-wasi-unstable-preview1 index.node.js

Quick Start (for Browser)

In browser, you need a WASI polyfill See the example project for more details.

<html>
  <script src="https://cdn.jsdelivr.net/npm/ruby-head-wasm-wasi@latest/dist/browser.umd.js"></script>
  <script>
    const { DefaultRubyVM } = window["ruby-wasm-wasi"];
    const main = async () => {
      // Fetch and instntiate WebAssembly binary
      const response = await fetch(
//      Tips: Replace the binary with debug info if you want symbolicated stack trace.
//      (only nightly release for now)
//      "https://cdn.jsdelivr.net/npm/ruby-head-wasm-wasi@latest/dist/ruby.debug.wasm"
        "https://cdn.jsdelivr.net/npm/ruby-head-wasm-wasi@latest/dist/ruby.wasm"
      );
      const buffer = await response.arrayBuffer();
      const module = await WebAssembly.compile(buffer);
      const { vm } = await DefaultRubyVM(module);

      vm.printVersion();
      vm.eval(`
        require "js"
        luckiness = ["Lucky", "Unlucky"].sample
        JS::eval("document.body.innerText = '#{luckiness}'")
      `);
    };

    main();
  </script>
  <body></body>
</html>

APIs

Table of Contents

RubyVM

A Ruby VM instance

Examples

const wasi = new WASI();
const vm = new RubyVM();
const imports = {
  wasi_snapshot_preview1: wasi.wasiImport,
};

vm.addToImports(imports);

const instance = await WebAssembly.instantiate(rubyModule, imports);
await vm.setInstance(instance);
wasi.initialize(instance);

initialize

Initialize the Ruby VM with the given command line arguments

Parameters
  • args The command line arguments to pass to Ruby. Must be an array of strings starting with the Ruby program name. (optional, default ["ruby.wasm","--disable-gems","-e_=0"])

setInstance

Set a given instance to interact JavaScript and Ruby's WebAssembly instance. This method must be called before calling Ruby API.

Parameters
  • instance The WebAssembly instance to interact with. Must be instantiated from a Ruby built with JS extension, and built with Reactor ABI instead of command line.

addToImports

Add intrinsic import entries, which is necessary to interact JavaScript and Ruby's WebAssembly instance.

Parameters
  • imports The import object to add to the WebAssembly instance

printVersion

Print the Ruby version to stdout

eval

Runs a string of Ruby code from JavaScript

Parameters
  • code The Ruby code to run
Examples
vm.eval("puts 'hello world'");
const result = vm.eval("1 + 2");
console.log(result.toString()); // 3

Returns any the result of the last expression

RbValue

A RbValue is an object that represents a value in Ruby

Parameters

  • inner
  • vm
  • exporter

call

Call a given method with given arguments

Parameters
  • callee name of the Ruby method to call
  • args ...any arguments to pass to the method. Must be an array of RbValue
Examples
const ary = vm.eval("[1, 2, 3]");
ary.call("push", 4);
console.log(ary.call("sample").toString());

toPrimitive

Parameters
  • hint

toString

Returns a string representation of the value by calling to_s

toJS

Returns a JavaScript object representation of the value by calling to_js.

Returns null if the value is not convertible to a JavaScript object.

RbError

Extends Error

Error class thrown by Ruby execution

Parameters

  • message

Building the package from source

For building the package from source, you need to prepare a Ruby build produced by WASI SDK, and you need wit-bindgen and wasm-opt in your PATH.

The instructions for building a Ruby targeting WebAssembly are available here.

Then, you can run the following command in your shell:

# Check the directory structure of your Ruby build
$ tree -L 3 path/to/wasm32-unknown-wasi-full-js/
path/to/wasm32-unknown-wasi-full-js/
├── usr
│   └── local
│       ├── bin
│       ├── include
│       ├── lib
│       └── share
└── var
    └── lib
        └── gems
$ ./build-package.sh path/to/wasm32-unknown-wasi-full-js/
Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/intrinsics.js"
Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-abi-guest.d.ts"
Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-abi-guest.js"
Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-js-abi-host.d.ts"
Generating "/Users/katei/.ghq/github.com/ruby/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-js-abi-host.js"

src/index.ts → dist/index.umd.js, dist/index.esm.js, dist/index.cjs.js...
created dist/index.umd.js, dist/index.esm.js, dist/index.cjs.js in 682ms
2.1.0-2023-11-04-a

6 months ago

2.2.0-2023-11-25-a

6 months ago

2.1.0-2023-11-03-a

6 months ago

2.3.0

6 months ago

2.2.0-2023-11-24-a

6 months ago

2.1.0-2023-10-30-a

6 months ago

2.1.0-2023-11-06-a

6 months ago

2.2.0

6 months ago

2.2.0-2023-11-23-a

6 months ago

2.1.0-2023-11-05-a

6 months ago

2.2.0-2023-11-22-a

6 months ago

2.1.0-2023-11-08-a

6 months ago

2.2.0-2023-11-21-a

6 months ago

2.1.0-2023-11-07-a

6 months ago

2.2.0-2023-11-20-a

6 months ago

2.1.0-2023-10-20-a

7 months ago

2.1.0-2023-10-31-a

6 months ago

2.1.0-2023-11-09-a

6 months ago

2.1.0-2023-10-21-a

7 months ago

2.3.0-2023-11-30-a

5 months ago

2.1.0-2023-10-26-a

7 months ago

2.1.0-2023-10-27-a

7 months ago

2.1.0-2023-10-15-a

7 months ago

2.3.0-2023-11-29-a

5 months ago

2.1.0-2023-10-24-a

7 months ago

2.2.0-2023-11-19-a

6 months ago

2.1.0-2023-11-10-a

6 months ago

2.1.0-2023-10-25-a

7 months ago

2.2.0-2023-11-18-a

6 months ago

2.3.0-2023-11-27-a

6 months ago

2.1.0-2023-10-18-a

7 months ago

2.1.0-2023-11-12-a

6 months ago

2.2.0-2023-11-17-a

6 months ago

2.3.0-2023-11-28-a

6 months ago

2.1.0-2023-10-19-a

7 months ago

2.1.0-2023-11-11-a

6 months ago

2.2.0-2023-11-16-a

6 months ago

2.1.0-2023-10-28-a

7 months ago

2.1.0-2023-11-02-a

6 months ago

2.1.0-2023-11-14-a

6 months ago

2.1.0-2023-10-16-a

7 months ago

2.2.0-2023-11-15-a

6 months ago

2.1.0-2023-10-29-a

7 months ago

2.3.0-2023-11-26-a

6 months ago

2.1.0-2023-10-17-a

7 months ago

2.1.0-2023-09-21-a

8 months ago

2.1.0-2023-09-22-a

8 months ago

2.1.0-2023-09-23-a

8 months ago

2.1.0-2023-10-09-a

7 months ago

2.1.0-2023-09-24-a

8 months ago

2.1.0-2023-10-11-a

7 months ago

2.1.0-2023-09-30-a

7 months ago

2.1.0-2023-09-20-a

8 months ago

2.1.0-2023-09-29-a

8 months ago

2.1.0-2023-10-03-a

7 months ago

2.1.0-2023-09-18-a

8 months ago

2.1.0-2023-10-14-a

7 months ago

2.1.0-2023-10-04-a

7 months ago

2.1.0-2023-09-19-a

8 months ago

2.1.0-2023-10-01-a

7 months ago

2.1.0-2023-10-12-a

7 months ago

2.1.0-2023-10-02-a

7 months ago

2.1.0-2023-10-13-a

7 months ago

2.1.0-2023-09-25-a

8 months ago

2.1.0-2023-10-07-a

7 months ago

2.1.0-2023-10-08-a

7 months ago

2.1.0-2023-09-26-a

8 months ago

2.1.0-2023-10-05-a

7 months ago

2.1.0-2023-10-06-a

7 months ago

2.1.0-2023-09-28-a

8 months ago

2.1.0-2023-09-17-a

8 months ago

2.1.0-2023-08-28-a

9 months ago

2.1.0-2023-08-05-a

9 months ago

2.0.0-2023-06-16-a

11 months ago

2.0.0-2023-07-21-a

10 months ago

2.1.0-2023-08-16-a

9 months ago

2.0.0-2023-06-27-a

11 months ago

2.0.0-2023-06-04-a

11 months ago

2.1.0-2023-07-31-a

10 months ago

2.1.0-2023-08-27-a

9 months ago

2.1.0-2023-08-04-a

9 months ago

2.0.0-2023-06-15-a

11 months ago

2.1.0-2023-09-10-a

8 months ago

2.0.0-2023-07-22-a

10 months ago

2.1.0-2023-09-11-a

8 months ago

2.0.0-2023-05-30-a

12 months ago

2.1.0-2023-08-15-a

9 months ago

2.1.0-2023-07-30-a

10 months ago

2.0.0-2023-06-03-a

11 months ago

2.0.0-2023-06-26-a

11 months ago

2.0.0-2023-07-10-a

10 months ago

2.0.0-2023-07-23-a

10 months ago

2.0.0-2023-06-18-a

11 months ago

2.1.0-2023-08-07-a

9 months ago

2.1.0-2023-09-12-a

8 months ago

2.0.0-2023-06-29-a

11 months ago

2.0.0-2023-07-11-a

10 months ago

2.1.0-2023-09-01-a

8 months ago

2.1.0-2023-08-06-a

9 months ago

2.0.0-2023-07-24-a

10 months ago

2.1.0-2023-08-29-a

9 months ago

2.1.0

10 months ago

2.1.0-2023-09-13-a

8 months ago

2.1.0-2023-08-17-a

9 months ago

2.0.0-2023-07-12-a

10 months ago

2.0.0-2023-06-28-a

11 months ago

2.0.0-2023-06-05-a

11 months ago

2.0.0-2023-05-22-a

12 months ago

2.1.0-2023-08-01-a

9 months ago

2.0.0-2023-07-25-a

10 months ago

2.0.0-2023-07-02-a

10 months ago

2.1.0-2023-08-12-a

9 months ago

2.0.0-2023-07-13-a

10 months ago

2.0.0-2023-06-08-a

11 months ago

2.0.0-2023-05-23-a

12 months ago

2.0.0-2023-07-03-a

10 months ago

2.0.0-2023-07-26-a

10 months ago

2.0.0-2023-06-19-a

11 months ago

2.1.0-2023-08-11-a

9 months ago

2.0.0-2023-06-07-a

11 months ago

2.0.0-2023-07-14-a

10 months ago

2.1.0-2023-08-26-a

9 months ago

2.1.0-2023-08-03-a

9 months ago

2.0.0-2023-07-27-b

10 months ago

2.0.0-2023-07-27-a

10 months ago

2.0.0-2023-07-04-a

10 months ago

2.1.0-2023-07-28-a

10 months ago

2.0.0-2023-05-31-a

12 months ago

2.1.0-2023-08-14-a

9 months ago

2.0.0-2023-07-15-a

10 months ago

2.0.0-2023-05-21-a

12 months ago

2.1.0-2023-08-02-a

9 months ago

2.0.0-2023-07-05-a

10 months ago

2.1.0-2023-07-29-a

10 months ago

2.1.0-2023-08-13-a

9 months ago

2.0.0-2023-07-16-a

10 months ago

2.0.0-2023-06-09-a

11 months ago

2.1.0-2023-09-06-a

8 months ago

2.1.0-2023-08-31-a

8 months ago

2.0.0-2023-05-26-a

12 months ago

2.0.0-2023-07-06-a

10 months ago

2.0.0-2023-07-17-a

10 months ago

2.0.0-2023-05-27-a

12 months ago

2.0.0-2023-06-30-a

11 months ago

2.0.0-2023-07-07-a

10 months ago

2.0.0-2023-07-18-a

10 months ago

2.0.0-2023-05-24-a

12 months ago

2.1.0-2023-09-08-a

8 months ago

2.0.0-2023-06-10-a

11 months ago

2.0.0-2023-07-08-a

10 months ago

2.0.0-2023-06-21-a

11 months ago

2.1.0-2023-08-10-a

9 months ago

2.1.0-2023-09-09-a

8 months ago

2.0.0-2023-05-25-a

12 months ago

2.0.0-2023-07-09-a

10 months ago

2.0.0-2023-06-20-a

11 months ago

2.1.0-2023-09-02-a

8 months ago

2.0.0-2023-06-12-a

11 months ago

2.1.0-2023-09-14-a

8 months ago

2.0.0-2023-06-23-a

11 months ago

2.1.0-2023-09-03-a

8 months ago

2.0.0-2023-06-11-a

11 months ago

2.1.0-2023-08-08-a

9 months ago

2.1.0-2023-09-15-a

8 months ago

2.0.0-2023-06-22-a

11 months ago

2.1.0-2023-09-04-a

8 months ago

2.0.0-2023-05-28-a

12 months ago

2.0.0-2023-06-14-a

11 months ago

2.0.0-2023-06-02-a

11 months ago

2.0.0-2023-06-25-a

11 months ago

2.1.0-2023-09-05-a

8 months ago

2.0.0-2023-05-29-a

12 months ago

2.0.0-2023-06-13-a

11 months ago

2.0.0-2023-06-24-a

11 months ago

2.0.0-2023-06-01-a

12 months ago

0.6.0

1 year ago

0.6.0-2023-05-16-a

12 months ago

2.0.0-2023-05-20-a

12 months ago

0.6.0-2023-05-13-a

12 months ago

0.6.0-2023-05-14-a

12 months ago

0.6.0-2023-05-15-a

12 months ago

2.0.0

12 months ago

2.0.0-2023-05-18-a

12 months ago

2.0.0-2023-05-19-b

12 months ago

0.5.0

1 year ago

0.4.0

2 years ago

0.3.0

2 years ago

0.2.0

2 years ago

0.1.0

2 years ago