https://github.com/ruby/ruby.wasm

ruby.wasm is a collection of WebAssembly ports of the CRuby.
https://github.com/ruby/ruby.wasm

emscripten ruby wasi wasm webassembly

Last synced: 27 days ago
JSON representation

ruby.wasm is a collection of WebAssembly ports of the CRuby.

• Host: GitHub
• URL: https://github.com/ruby/ruby.wasm
• Owner: ruby
• License: mit
• Created: 2021-12-29T01:11:11.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2024-04-13T15:05:00.000Z (7 months ago)
• Last Synced: 2024-04-13T19:32:54.136Z (7 months ago)
• Topics: emscripten, ruby, wasi, wasm, webassembly
• Language: Ruby
• Homepage: https://ruby.github.io/ruby.wasm/
• Size: 1.91 MB
• Stars: 607
• Watchers: 23
• Forks: 46
• Open Issues: 20
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# ruby.wasm

[![Build ruby.wasm](https://github.com/ruby/ruby.wasm/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/ruby/ruby.wasm/actions/workflows/build.yml)

ruby.wasm is a collection of WebAssembly ports of the [CRuby](https://github.com/ruby/ruby).

It enables running Ruby application on browsers, WASI compatible WebAssembly runtimes, and Edge Computing platforms.

## Try ruby.wasm (no installation needed)

Try ruby.wasm in [TryRuby](https://try.ruby-lang.org/playground#code=puts+RUBY_DESCRIPTION&engine=cruby-3.2.0dev) in your browser.

## Quick Links

- [Cheat Sheet](https://github.com/ruby/ruby.wasm/blob/main/docs/cheat_sheet.md)

- [FAQ](https://github.com/ruby/ruby.wasm/blob/main/docs/faq.md)

- [API Reference](https://github.com/ruby/ruby.wasm/blob/main/docs/api.md)

- [Complete Examples](https://github.com/ruby/ruby.wasm/tree/main/packages/npm-packages/ruby-wasm-wasi/example)

- [Community Showcase](https://github.com/ruby/ruby.wasm/wiki/Showcase)

## Quick Example: Ruby on Web browser

Create and save `index.html` page with the following contents:

```html

  

  

    require "js"

    puts RUBY_VERSION # (Printed to the Web browser console)

    JS.global[:document].write "Hello, world!"

  

```

## Quick Example: How to package your Ruby application as a WASI application

Dependencies: [wasmtime](https://github.com/bytecodealliance/wasmtime)

```console

$ gem install ruby_wasm

# Download a prebuilt Ruby release

$ curl -LO https://github.com/ruby/ruby.wasm/releases/latest/download/ruby-3.3-wasm32-unknown-wasip1-full.tar.gz

$ tar xfz ruby-3.3-wasm32-unknown-wasip1-full.tar.gz

# Extract ruby binary not to pack itself

$ mv ruby-3.3-wasm32-unknown-wasip1-full/usr/local/bin/ruby ruby.wasm

# Put your app code

$ mkdir src

$ echo "puts 'Hello'" > src/my_app.rb

# Pack the whole directory under /usr and your app dir

$ rbwasm pack ruby.wasm --dir ./src::/src --dir ./ruby-3.3-wasm32-unknown-wasip1-full/usr::/usr -o my-ruby-app.wasm

# Run the packed scripts

$ wasmtime my-ruby-app.wasm /src/my_app.rb

Hello

```

## npm packages (for JavaScript host environments)

See the `README.md` of each package for more detail and its usage.

  

    

      Package

      Description

      npm

    

  

  

    

      @ruby/3.3-wasm-wasi

      CRuby 3.3 built on WASI with JS interop support

      

    

    

      @ruby/3.2-wasm-wasi

      CRuby 3.2 built on WASI with JS interop support

      

    

    

      @ruby/head-wasm-wasi

      HEAD CRuby built on WASI with JS interop support

      

    

    

      @ruby/head-wasm-emscripten

      HEAD CRuby built on Emscripten (not well tested)

      

    

  

## Prebuilt binaries

This project distributes [prebuilt Ruby binaries in GitHub Releases](https://github.com/ruby/ruby.wasm/releases).

A _build_ is a combination of ruby version, _profile_, and _target_.

### Supported Target Triples

  

    

      Triple

      Description

    

  

  

    

      wasm32-unknown-wasip1

      Targeting WASI Preview1 compatible environments 
(e.g. Node.js, browsers with polyfill, wasmtime, and so on)

    

    

      wasm32-unknown-emscripten

      Targeting JavaScript environments including Node.js and browsers

    

  

### Profiles

  

    

      Profile

      Description

    

  

  

    

      minimal

      No standard extension libraries (like json, yaml, or stringio)

    

    

      full

      All standard extension libraries

    

  

## Notable Limitations

The current WASI target build does not yet support `Thread` related APIs. Specifically, WASI does not yet have an API for creating and managing threads yet.

Also there is no support for networking. It is one of the goal of WASI to support networking in the future, but it is not yet implemented.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to build and test, and how to contribute to this project.

Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/ruby.wasm