"Scarpe" means shoes in Italian. "Scarpe" also means Shoes in modern Ruby and Webview!
Scarpe isn't feature complete with any version of Shoes (yet?). We're initially targeting Shoes 3, also called "Red Shoes."
Shoes is an old library (really several different ones) that let you build little local desktop computer programs, package them up and give copies to people. Imagine if you can write a tiny little Ruby program (e.g. sneak a peek at the next section) and then it would make a runnable app, opening a window in Ruby, where you could click buttons and play sounds and stuff.
Scarpe is a rewrite of Shoes, because old Shoes doesn't work any more. There have been a surprising number of rewrites of Shoes over the years -- people love it and miss having it around. This one is ours. By default it uses Webview.
Note: you'll probably want the Scarpe in Development instructions below in most cases! Scarpe isn't ready for "just install the released version" production usage yet.
Create an hello world application with:
Shoes.app do
para "Hello World"
end
A bit more...
Shoes.app do
@push = button "Push me"
@note = para "Nothing pushed so far"
@push.click {
@note.replace(
"Aha! Click! ",
link("Go back") { @note.replace "Nothing pushed so far" }
)
}
end
More examples can be found in the examples folder!
Explore more in the Scarpe Wiki for in-depth documentation, tutorials, and additional resources. Whether you're a new user, a new contributor or an experienced user, the Wiki provides valuable information to enhance your Scarpe experience.
Scarpe requires Ruby 3.2 or higher! You can use rvm, rbenv or your favourite version control to install Ruby just like normal.
This repo is where most of the action is happening right now, and to have the full Scarpe experience today this is probably what you want to do.
# dependencies - Mac version
brew install portaudio pkg-config # for sound!
# dependencies - Mac M1 version
brew install portaudio && bundle config build.bloops --with-portaudio-dir=$(brew --prefix portaudio)
# dependencies - Ubuntu Linux version
sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev portaudio19-dev
for any other Linux or Windows please see the webview docs for your [platform](https://github.com/webview/webview#prerequisites)
# get it
git clone http://github.com/scarpe-team/scarpe
cd scarpe; bundle install
# run it
./exe/scarpe examples/button.rb --dev
If you are using Visual Studio Code, you can use this extension. This extension simplifies the process of executing commands by eliminating the need to repeatedly type lengthy file paths, resulting in a more efficient and productive development experience.
To Run all availble tests run command
bundle exec rake ci_test
Scarpe is composed of various sub-libraries. You can run some tests separately.
Run Lacci Tests:
bundle exec rake lacci_test
Run Scarpe-Components Tests:
bundle exec rake component_test
Run Scarpe Tests:
bundle exec rake test
Check HTML Output:
bundle exec rake test:check_html_fixtures
First, clone the main GitHub repository.
bundle install dependencies like Webview from the cloned directory in your Ruby of choice.
You can run without Scarpe being installed by including its directory. For instance, from the "examples" directory you can run ruby -I../lib -I../lacci/lib -rscarpe hello_world.rb. You can also install Scarpe locally (gem build scarpe.gemspec && gem install scarpe-0.1.0.gem) or using a Gemfile with the "path" option for local Scarpe.
Most commonly we are all using this command: ./exe/scarpe examples/button.rb --dev --debug
The --dev flag points to your local Scarpe rather than an installed Scarpe gem.
The --debug flag will dump a ton of useful information to the console if you want to see what's happening with your app.
It's very early in Scarpe's development process. If you'd like to help develop Scarpe, great! It would be useful to drop us a message/issue/PR on GitHub early on, so we know you're working in a particular area, and we can warn you if anybody else is currently doing so. We also have a Discord.
We'd love the help!
If you want to quickly add a feature, you can use the ruby scarpegen.rb command. This command will generate the necessary files for you, along with a simple template and a set of questions to guide you through the process. By leveraging the ruby scarpegen.rb command and the provided resources, you can expedite the feature addition process and ensure a smoother development experience.
Great question! Right now we have a few key things we want to achieve. The first is passing all of the examples we can get our hands on. The second is passing Hackety-Hack. We're manually keeping tabs on that here.
But the short version is: no, we're far from done. Some Shoes features (e.g. multiple window support) may be very difficult to support with Webview at all. We're working on other ways to handle those features.
92/304
Scarpe allows you to modify the app's behaviour outside of the normal Shoes API with environment variables.
The SCARPE_DISPLAY_SERVICE environment variable allows you to choose one or more display services, from the default Webview service, to Scarpe-Wasm to potentially other experimental or incomplete services. This may be important if you're developing a new display method for Scarpe. The display service variable will contain a name like "wv_local" or "wv_remote" or "wasm_local" which correspond to a require-able Ruby file under lib/scarpe, either in the Scarpe gem or another gem your app requires.
Example usage:
SCARPE_DISPLAY_SERVICE=wv_relay ./exe/scarpe examples/hello_world.rb
The SCARPE_TEST_CONTROL environment variable can contain a path to a test-control-interface script for the Webview display service. If you look at test_helper, it gives some examples of how to use it.
If you run ./exe/scarpe --dev env, you can see all current environment settings.
Pre-Scarpe Shoes didn't have specific test APIs or infrastructure. That was pretty standard for GUI libraries when it was written. Scarpe supports a test API called Shoes-Spec, and different display services tend to extend it.
The idea is that you write a standard Shoes application and then there's additional test code that runs once your application is running. Since different display services run in very different ways (e.g. Webview vs Wasm vs GTK+), the test code isn't necessarily in the same Ruby process as the Shoes application.
They're often packaged in .sspec files that look like this:
---
----------- app code
Shoes.app do
@b = button "OK" do
@b.text = "Clicked"
end
end
----------- test code
assert_equal "OK", button().text
button().trigger_click
assert_equal "Clicked", button().text
See [https://github.com/scarpe-team/shoes-spec] for more details.
- Nobody Knows Shoes manual
- Original shoes (archived)
- For now we are aiming towards original shoes, but I believe later can learn from Shoes3.
- wiki
- shoes3
- shoes4 (JRuby, incomplete)
- Shoes' native splash app
- Original Shoes example directory
- Found shoes apps
- HacketyHack
- Resiliency - We want Scarpe to be tested and trustworthy to work consistently and predictably.
- User Experience - Ruby and this DSL are beautiful for making desktop app authoring easy. We should uphold this standard.
- Whimsy - We're not here to make money or be corporate. We're here to have fun! Even if we do end up building something amazing. Also, Chunky Bacon. 🥓
- Empathy - Let's help one another, and adhere to good contributor standards while doing so.
You can set SCARPE_LOG_CONFIG to an appropriate YAML file to set log levels per-component. You can find sample log configs under the logger directory. Scarpe has a number of component names that log data, set per-class. So you can set what components log at what sensitivity.
{
"default": "warn",
"Webview::WebWrangler": ["logger/web_wrangler.log", "debug"]
}
Usually it's easiest to just view the latest on GitHub.
But you can also built it yourself, locally, for testing or to take on the road.
Scarpe uses YARD for basic API documentation. You can run "yard doc" to generate documentation locally, and then view it with "yard server". Point your browser at "http://localhost:8808" for local viewing.
Bug reports and pull requests are welcome on GitHub at https://github.com/scarpe-team/scarpe. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct and CONTRIBUTING.md.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Scarpe project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.