Debugging with Byebug

[Update July, 21, 2016]

Current versions of Shoes includes byebug v8.0.2 which changes how Shoes can use it. The remote debugger describe later works fine but is a little hard to setup. The easier way, IMO is to ignore that -d switch on the command line and modify your main script (aka myscript.rb) with these lines added to the top:

if ARGV.find_index('-me')
    require 'byebug'
    byebug
end

and then start shoes from the command line (cshoes.exe) $> cshoes.exe myscript.rb -- -me if you want debugging and cshoes.exe myscript.rb if you don't want debugging.

Once you get the byebug prompt you'll want to set a breakpoint - possibly the first line of the Shoes.app block? Remember that Shoes.app is a {block} if you skip over it with a 'next' your program will run normally. But, you do not want to 'step' into Shoes.app. Trust me - you'll be deep inside Shoes if you do. Set a breakpoint at some line of interest inside your Shoes.app block and then 'c', (continue) past the Shoes.app line.

[end update]

Shoes 3.2.23 has the capability for debugging Ruby (shoes scripts) Step in, step out, set breakpoints. That kind of debugging. It's a bit clunky and it may not be what you think you want but you didn't have anything before so let's it call a partial win for the good guys. We use byebug

There are multiple ways to invoke the debugger. One method does it from the command line (the best way and easiest) but you can also invoke the remote debugger facilities - harder to do and has some limitations.

Command line

mini:~/Projects/shoes3.2$ ~/Downloads/Shoes.app/Contents/MacOS/shoes-launch -d samples/simple-info.rb 

[1, 10] in /Users/ccoupe/Downloads/Shoes.app/Contents/MacOS/samples/simple-info.rb
=>  1: Shoes.app height: 800, width: 800 do
    2:   para "Startup info\n"
    3:   para "Ruby Version: #{RUBY_VERSION} on #{RUBY_PLATFORM}\n"
    4:   para "Shoes Release: #{Shoes::RELEASE_NAME}\n"
    5:   para "    built on #{Shoes::RELEASE_BUILD_DATE}\n"
    6:   para "    Fit: #{Shoes::RELEASE_TYPE}\n"
    7:   para "Gems Version #{Gem::RubyGemsVersion}"
    8:   if defined?(ShoesGemJailBreak)
    9:    para "Jailbreak == #{ShoesGemJailBreak}"
   10:   else
(byebug) b 8
Successfully created breakpoint with id 1
(byebug) c
Stopped by breakpoint 1 at /Users/ccoupe/Downloads/Shoes.app/Contents/MacOS/samples/simple-info.rb:8

[3, 12] in /Users/ccoupe/Downloads/Shoes.app/Contents/MacOS/samples/simple-info.rb
    3:   para "Ruby Version: #{RUBY_VERSION} on #{RUBY_PLATFORM}\n"
    4:   para "Shoes Release: #{Shoes::RELEASE_NAME}\n"
    5:   para "    built on #{Shoes::RELEASE_BUILD_DATE}\n"
    6:   para "    Fit: #{Shoes::RELEASE_TYPE}\n"
    7:   para "Gems Version #{Gem::RubyGemsVersion}"
=>  8:   if defined?(ShoesGemJailBreak)
    9:    para "Jailbreak == #{ShoesGemJailBreak}"
   10:   else
   11:    para "Cannot determine JailBreak status?"
   12:   end
(byebug)  

I'm showing the OSX command line since it's the least friendly. You have to use shoes-launch on OSX with the full path to it. The -d flag is followed by the Shoes script path. (Should work for .shy too)

Windows:

cshoes.exe -d path-to-script.

Linux:

~/.shoes/federales/shoes -d path-to-script

and if your running a build from source dist/shoes -d path-to-script You can even try to debug parts of Shoes that: .shoes/federales/shoes -d ~/.shoes/federales/lib/shoes/cobbler.rb

LINUX NOTE: If the Shoes console says it can't find infocmp you'll have to use your distro package manager to install it. For openSuse 13.1 that's cnf infocmp which tells you to do sudo zypper install ncurses-devel

Remote

For the remote ability you need Ruby installed and you need to have the byebug and rb-readline gems installed in that Ruby. Yes, it can/should be a different Ruby than Shoes is using. For Windows, that means you need to install RubyInstaller and the proper devkit. For OSX 10.9+ you can probably use the Ruby that Apple ships. For Linux, just install rvm and use it to install a ruby that's near current. 2.1.x would be an excellent choice.

Using that ruby from the command line. gem install rb-readline --no-doc and gem install byebug --no-doc

Example: Perhaps you want to debug sample/simple-sphere.rb. You need to put a byebug call in it. Which happens to be done in samples/expert-debug.

Start Shoes. type Alt-; ( ⌘-; for OSX) and you'll get a window telling you what to do

So start up another console and enter that command and you should be rewarded with

byebug -R localhost:8989
Connecting to byebug server...
Connected.

Now you use Shoes (splash screen) load the app that has that byebug command in it. Then the console shows

[1, 10] in expert-debug.rb
    1: Shoes.app :width => 500, :height => 500, :resizable => false do
    2:   byebug # breakpoint here
=>  3:   image 400, 470, :top => 30, :left => 50 do
    4:     nostroke
    5:     fill "#127"
    6:     image :top => 230, :left => 0 do
    7:       oval 70, 130, 260, 40
    8:       blur 30
    9:     end
   10:     oval 10, 10, 380, 380
(byebug) s

Notice how I issued the 's' command (step into) but because image is a Shoes command implemented in C, it just moved to the next Ruby line until I got bored and tried to invoke irb and then I just 'c' (continue - run until a breakpoint)

[13, 22] in expert-debug.rb
   13:       oval 30, 30, 338, 338
   14:       blur 10
   15:     end
   16:     fill gradient(rgb(1.0, 1.0, 1.0, 0.7), rgb(1.0, 1.0, 1.0, 0.0))
   17:     oval 80, 14, 240, 176
=> 18:     image :top => 0, :left => 0 do
   19:       fill "#79F"
   20:       oval 134, 134, 130, 130
   21:       blur 40
   22:     end
(byebug) irb
*** Command is available only in local mode.

(byebug) c

Like I said, remote debugging is a bit clunky. But it works.