Jason R. Clark edited this page Mar 6, 2017 · 26 revisions

Welcome to the Shoes 4 wiki! This is a great place to get started with Shoes 4. See the Roadmap for release details.

What is Shoes 4?

Shoes 4 is the new version of the shoes DSL (Domain Specific Language) for writing GUI applications in ruby. Shoes 4 is rethinking the way shoes works, from an implementation point of view. The DSL itself however should stay intact as shooooesers all over the planet love it as it is. The shoes DSL is pretty simple which is the main reason for its beauty. Also cross-platform compatibility is at the heart of goals for shoes. For further information you can check out the homepage, an awesome talk by Steve Klabnik called the return of shoes and a talk by Tobias Pfeiffer called An Introduction to Shoes. Also don't forget to have a look at the most famous shoes application Hackety Hack.

So what is different about Shoes 4?

The goals of Shoes 4 are

  • to be almost-fully-compatible with Shoes 3
  • to make changes to the Shoes DSL in those few cases where it isn't already as wonderful as it could be
  • to separate the DSL from the graphical implementation, so that multiple implementations can "plug in" to the same DSL
  • to establish a "shoes spec" suite of specifications. Any implementation should be able to run the spec suite to verify that it_behaves_like :shoes. The spec suite also makes hacking on Shoes 4 easier, because it tells you if your changes have broken anything else.
  • to run in a normal Ruby environment, rather than embedding its own customized Ruby

The reference implementation for Shoes 4 is SWT(Standard Widget Toolkit), which runs on JRuby. However, we want there to be multiple backends for shoes -- maybe Qt, maybe GTK -- you name it! There have been different flavors of shoes before, but Shoes 4 aims to establish a shared DSL and a shared spec suite, so that the implementations can be more or less interchangeable.

Installing Shoes 4

You should check out the README for up to date information about how to install Shoes 4 on your machine and what dependencies are needed.

Getting started with contributing to Shoes 4

You want to help out with the development of Shoes 4? Great! You can start off by having a look at this tutorial on davorb's blog.

What to work on

You can always check out our open issues and see if you can contribute either by implementing something, discussing something or testing something. Everything helps and every help is highly appreciated!

We frequently have active pull requests that need to be tested before getting merged into master. Find out more about Testing a Pull Request.

If you don't find anything there you can also work on something else. You can check out the manual and see if the described functionality is implemented and if not go ahead and implement it.

Also you may check out the samples/ directory - it contains a lot of samples which you can try to run and if they don't work you can go ahead and try to fix some of them. There is a README in the samples folder detailing which samples are currently considered to be working.

Project Structure

The general directory structure of Shoes 4 is as follows:

  • bin: contains development executables for use when running Shoes from source. Each gem has its own bin folder as well, which the root bin ends up pointing to.
  • shoes: implementation of the shoes meta-gem. Might go away soon (https://github.com/shoes/shoes4/issues/958)
  • shoes-core: the backend-agnostic, pure Ruby implementation of the Shoes DSL, main executable and backend picker
  • shoes-swt: the default, JRuby + SWT based backend
  • samples: a variety of samples that should show that a given shoes implementation works as intended. When they all work, we'll be very happy!
  • */spec: Shoes 4 is written with Test Driven Development (TDD), which means we want to have tests for everything, and these tests (also called specs) go into these directories! Each of the gem directories has their own appropriate specs, although they can be run from the top level as well.
  • benchmark: scripts for use in performance benchmarking parts of Shoes
  • tasks: supporting code for rake tasks

Style Guide

Shoes 4 has a comfortably-fitting style guide. While it is not laced too tightly, it might help you get your footing.

Get your changes merged

If you work on something, please let us know! Make a comment on an issue you are currently working or if you are working on a new implementation please open an appropriate issue so we have a place for discussion and people don't end up implementing the same thing twice!

Don't be afraid to make an early pull request with an incomplete implementation! This is great for discussions, receiving feedback and helping each other.

Development and Debugging Tools

Check out some of the development and debugging tools you can use while developing Shoes.


This section is meant to help you with some resources regarding some of the main technologies used in the development of Shoes 4.


Currently we are using JRuby for the development of Shoes 4 as it is cross-platform compatible and gives us access to a large ecosystem of cross-platform compatible GUI frameworks. You can find more information about JRuby at the project homepage.

As we call a lot of Java methods this guide about calling Java from Ruby is really helpful! JRuby makes the integration with java really seamless, so you can call java methods as if they were Ruby methods - yay! :-)



RSpec is the testing framework of our choice, you can check out their documentation. RSpec is really descriptive so you could also go ahead and check out specs/ directory in order to get a feel for RSpec.