wasm/README.md

   1 # WebAssembly / WASI port of Ruby
   2
   3 ## How to cross-build
   4
   5 ### Requirement
   6
   7 - Ruby (the same version as the building target version) (baseruby)
   8 - GNU make
   9 - [WASI SDK](https://github.com/WebAssembly/wasi-sdk) 14.0 or later
  10 - [Binaryen](https://github.com/WebAssembly/binaryen) version 106 or later
  11 - Linux or macOS build machine
  12
  13 ### Steps
  14
  15 1. Download a prebuilt WASI SDK package from [WASI SDK release page](https://github.com/WebAssembly/wasi-sdk/releases).
  16 2. Set `WASI_SDK_PATH` environment variable to the root directory of the WASI SDK package.
  17 ```console
  18 $ export WASI_SDK_PATH=/path/to/wasi-sdk-X.Y
  19 ```
  20 3. Download a prebuilt binaryen from [Binaryen release page](https://github.com/WebAssembly/binaryen/releases)
  21 4. Set PATH environment variable to lookup binaryen tools
  22 ```console
  23 $ export PATH=path/to/binaryen:$PATH
  24 ```
  25 5. Download the latest `config.guess` with WASI support, and run `./autogen.sh` to generate configure when you
  26    are building from the source checked out from Git repository
  27 ```console
  28 $ ruby tool/downloader.rb -d tool -e gnu config.guess config.sub
  29 $ ./autogen.sh
  30 ```
  31
  32 6. Configure
  33   - You can select which extensions you want to build.
  34   - If you got `Out of bounds memory access` while running the produced ruby, you may need to increase the maximum size of stack.
  35 ```console
  36 $ ./configure LDFLAGS="-Xlinker -zstack-size=16777216" \
  37   --host wasm32-unknown-wasi \
  38   --with-destdir=./ruby-wasm32-wasi \
  39   --with-static-linked-ext \
  40   --with-ext=ripper,monitor
  41 ```
  42
  43 7. Make
  44 ```console
  45 $ make install
  46 ```
  47
  48 Now you have a WASI compatible ruby binary. You can run it by any WebAssembly runtime like [`wasmtime`](https://github.com/bytecodealliance/wasmtime), [`wasmer`](https://github.com/wasmerio/wasmer), [Node.js](https://nodejs.org/api/wasi.html), or browser with [WASI polyfill](https://www.npmjs.com/package/@wasmer/wasi).
  49
  50 Note: it may take a long time (~20 sec) for the first time for JIT compilation
  51
  52 ```
  53 $ wasmtime ruby-wasm32-wasi/usr/local/bin/ruby --mapdir /::./ruby-wasm32-wasi/ -- -e 'puts RUBY_PLATFORM'
  54 wasm32-wasi
  55 ```
  56
  57 Note: you cannot run the built ruby without a WebAssembly runtime, because of the difference of the binary file type.
  58
  59 ```
  60 $ ruby-wasm32-wasi/usr/local/bin/ruby -e 'puts "a"'
  61 bash: ruby-wasm32-wasi/usr/local/bin/ruby: cannot execute binary file: Exec format error
  62
  63 $ file ruby-wasm32-wasi/usr/local/bin/ruby
  64 ruby-wasm32-wasi/usr/local/bin/ruby: WebAssembly (wasm) binary module version 0x1 (MVP)
  65 ```
  66
  67 ## Current Limitation
  68
  69 - No `Thread` support for now.
  70 - Spawning a new process is not supported. e.g. `Kernel.spawn` and `Kernel.system`