SpaceShoes

SpaceShoes allows embedding Ruby GUI code in your web pages. You can embed simple Ruby GUI applications directly or you can write a multi-file application and package it up to be loaded from the page or pages of your choice.

SpaceShoes is based on Scarpe, which is a reimplementation of Shoes by _why the lucky stiff. It contains a lot of code from Scarpe-Wasm by Giovanni Borgh and Noah Gibbs.

The Simplest Spacewalk

SpaceShoes does a few different tricks. The easiest is for you to add a line in an HTML page and then run your Shoes app right from the page.

Here's how that looks:

<!DOCTYPE html>
<html lang="en">
  <head>

  <script type="module" src="https://cdn.jsdelivr.net/npm/@spaceshoes/spacewalk/spacewalk.js"></script>
  <script type="text/ruby">
    Shoes.app do
      @p = para "Buttons are good!"
      button("OK") { @p.replace("Buttons are amazing!") }
    end
  </script>

  </head>
  <body>
  </body>
</html>

That little text/ruby block with Shoes.app inside the Ruby script block? That's a real Shoes app, running ruby.wasm. If you put other Ruby code in there, it will do Ruby things. If you put other Shoes code in there, it will do Shoes things. It's all done in your browser.

You don't have to have Ruby installed. You don't need to clone the SpaceShoes repository. All you need is to create a little HTML file and open it in the browser. It's even fine as a file URL.

Your Very Own Spacewalk

You can also use SpaceShoes to package up your app. If you want or need multiple files bundled into a Wasm module, you'll start from the Ruby side.

Add SpaceShoes to the application's Gemfile by executing:

$ bundle add space_shoes

Make sure it's installed:

$ bundle install

SpaceShoes will make a package containing specific versions of Ruby and SpaceShoes, plus whatever other gems are in your Gemfile. It will pick up all the local files, including images and Ruby source files. Try not to have any huge files sitting around, or they will be included in your Wasm package!

<!DOCTYPE html>
<html lang="en">
  <head>

  <script type="module" src="spacewalk.js"></script>
  <script type="text/ruby">
    Shoes.app do
      para "Images are good too."
      image "my_local_file.png"
    end
  </script>

  </head>
  <body>
  </body>
</html>

TODO: more information about how to make this work.

Developing Spacewalk

If you've cloned the repository, you can build your own spacewalk.js. Run "bundle install" to get the appropriate gems and then run this:

./exe/space-shoes --dev build-default

That will build a local packed_ruby.wasm containing a Ruby build and your locally-modified version of SpaceShoes. If you make changes to SpaceShoes, that's a great way to test them.

You can also run the tests:

rake test

There's a little example of using local SpaceShoes in html/templates/shoes_embed.html. It uses the spacewalk.js in html/templates. It won't work with a file URL though, because CORS policy doesn't like file URLs. So you'll need to run a local HTML server in the appropriate directory, something like this:

# From SpaceShoes root directory
ruby -run -e httpd -- -p 4321 .

Then you can access it with a local URL like "http://localhost:4321/html/templates/shoes_embed.html"

Binaryen

https://github.com/WebAssembly/binaryen/releases
tested with version 117
install for your platform
copy wasm-opt into your path

# Taken from Largo's ruby.wasm build instructions
bundle exec rbwasm --log-level debug build --ruby-version 3.3 --target wasm32-unknown-wasi --build-profile full  -o ruby-app.wasm
# Remove the debug info
wasm-opt --strip-debug ruby-app.wasm -o ruby-app.wasm
# Optimize for size without hurting speed as much.
wasm-opt ruby-app.wasm -Os -o ruby-app.wasm

To create a new NPM package you'll need to use wasm-opt to reduce the file size below 50MB.

Development

You'll need a Ruby-based install to help develop SpaceShoes. You'll need Ruby 3.2 or later, probably installed via a version manager like chruby or rvm.

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/scarpe-team/space_shoes. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Random Notes and References

To install wasmtime for testing: https://github.com/bytecodealliance/wasmtime

Single-line HTTP server: "ruby -run -e httpd -- -p 4321 ."

EvilMartians blog post on using Ruby.wasm's Bundler integration https://evilmartians.com/chronicles/first-steps-with-ruby-wasm-or-building-ruby-next-playground

History

Giovanni Borgh wrote the initial scarpe-wasm code, including tools like wasify, for his Google Summer of Code project. Noah Gibbs then adapted it to use Scarpe.

Some of the top-level structure of SpaceShoes is different from scarpe-wasm. But a lot of the actual initial code comes from scarpe-wasm and was written by Noah Gibbs and/or Giovanni Borgh.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the SpaceShoes project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

space_shoes

Runtime