Clone this wiki locally
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!
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.
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
binfolder as well, which the root
binends up pointing to.
shoes: implementation of the
shoesmeta-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
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.