Category Archives: Ruby

Getting Qt and Ruby (=QtRuby) running on Windows 7 (and Windows XP)

Update 2011-10-16:
Following a very-well written post on stackoverflow, getting QT and Ruby running on Windows 7 is quite easy nowadays.

Quote from

The following steps work on Windows 7:

  1. Install Ruby 1.9.2 via the official download page.
  2. In a Windows shell, run gem install qtbindings.

The trivial example (require 'rubygems'; require 'Qt') should now work.

Hence the tutorial below is now obsolete. However, I will keep it here for reference purposes.


This is an update on a previous tutorial which explained how to write Ruby applications using Qt on Windows XP. This new version is dealing with Ruby applications using Qt on Windows 7 (but it should also work in Windows XP). Also, it uses Qt 4.6.1 instead of Qt 4.3.4 and it also brings a newer version of QtRuby (2.1.0).


Believe it or not: In some QtRuby application I wrote some time ago, somebody discovered a “hidden feature” (let’s not use the b-word here). To remove this “feature” I had to re-install my development environment since in the meantime I got a new laptop (really fancy one with SSD and all, I like it).

Three years ago, getting QtRuby running on Windows was so complicated that it was worth a lengthy  tutorial.
But now it’s 2011. Should be much better now, right?
Turns out, in June 2011 it is so complicated, that dr1ku wrote an even longer tutorial  (no bashing indented, his article is really exhaustive with a lot of insight and information).
Today it is my turn again. Luckily I found a solution that is reasonably simple, but still requires some not-too-obvious steps (at least for a ruby-noob like myself).

So. Here we go again. I wonder what it will be like in 2014.
Oh wait, the end of the world is scheduled for 2012. Phew, that will save us some trouble.


As in the previous installment of this guide, I did not use the latest versions of Ruby/Qt/QtRuby, because they simply don’t work together (as dr1ku points out in his post mentioned above). I will assume that Ruby is not yet installed on your system.

  1. Download and install Ruby 1.8.7-p334.
    Make sure to use the RubyInstaller version. You can find it at rubyforge.During installation, make sure to add ruby to your path.
    Verify the installation by opening a command line and type ruby --version. It should yield:
    ruby 1.8.7 (2011-02-18 patchlevel 334) [i386-mingw32]
  2. Update gems to the latest version by typing
    gem update --system
  3. Install rake (which is a prerequisite for QtRuby)
    gem install rake
  4. Install DevKit (which is a prerequisite for QtRuby)
    Follow the instructions found here.
    Don’t panic: The instruction looks lengthy, but most of the steps are optional or for updating legacy versions of DevKit.
  5. Finally install QtRuby gem. On the command line type
    gem install qtruby4 --remote --platform=mswin32
    The --platform=mswin32 is required to override the platform check of gems.
  6. Verify the installation by opening a command line and type irb (an interactive ruby interpreter)
    Type require 'rubygems' and hit enter. It should yield true.
    Now type require 'Qt' which should also yield true.

Well, that’s it. For getting-started instructions and some more information, please visit the previous installment of this guide  and start reading after “That’s it!”


Where was I? Oh right, that “hidden feature” is still hiding…


Deploying Ruby (and QtRuby) Applications

Important Note
This post is outdated and as David Mullet points out here, ocra is the recommended way for deploying Ruby applications on windows.

This post is about deploying Ruby apps like in “plain-old-ruby-desktop-apps-where-no-rails-is-involved” and covers only MS Windows.


OK, now you have spent the last few days hacking together your Qt-and-Ruby application. You want to show it to your client to get some feedback on it. So you type: “Dear Mr. Client, attached to this mail you find … eh, ahem” Well, what exactly do you attach to the mail? A howto.txt that describes how to install Ruby and then use the gem command line version to install qt-ruby and whatever other dependencies your application might have? As you already know, there might be tons of problems like: Does your client have admin privileges on his computer? Is he scared to death by a command line? Do you really want to bother your client with such stuff?
No, “Ruby means less painful programming.” they told you. Well they didn’t say anything about deploying, did they?


Luckily there guys like Erik Veenstra who think that “Ruby also means less painful deployment”. Erik wrote two tools:

tar2rubyscript takes a folder full of Ruby files (and subfolders full of Ruby files) and creates one single Ruby script that contains your whole application.

rubyscript2exe takes any ruby script, runs it, analyzes the dependencies and packages everything into one .exe file.

So here is how to deploy a Ruby desktop app. I will not go into much detail, since everything is explained very well in the tutorial on Erik’s page:

  1. Install tar2rubyscript and rubyscript2exe:
    gem install tar2rubyscript
    gem install rubyscript2exe
  2. Create a file named “init.rb” that requires you main application start script and put it in your top-level source code directory. tar2rubyscript will use init.rb to start your application. Mine looks like this:
    Dir.chdir oldlocation
    require 'main.rb'
    The first line switches the directory, since when starting an application that was packed with tar2rubyscript, it will be extracted to a temporary directory and started from there, but you probably want the current directory to be the directory where the user double-clicked the .exe. I have stolen that line from
  3. Pack your application into a single ruby script (assuming that ‘source’ is a directory containing ‘init.rb’ and your application’s source code)
    tar2rubyscript source
  4. Pack your application into an executable
    rubyscript2exe killerapp.rb --rubyscript2exe-verboseThe parameter --rubyscript2exe-verbose will make rubyscript2exe give some information about what it is doing.
  5. You will end up with a file named killerapp.exe. Double clicking it should start your application. On any Windows PC.

This is it. Very simple, eh? However, there are some minor issues that I’d like to mention:

  1. As stated above, rubyscript2exe starts your application to investigate its dependencies. If you have an application that does not quit by itself, rubyscript2exe will not continue unless you quit the application manually. To avoid that, you may add the following line to the appropriate place in your application:
    exit if RUBYSCRIPT2EXE.is_compiling?
    Keep in mind, that some dlls do not get loaded by your application unless you really use them so if you use above line, make sure that all dlls that you app depends on have been loaded.
  2. When you double-click killerapp.exe, a DOS-window appears, showing the output of your application. In case of a command line application this is fine. In case of a Windows application you probably don’t want a DOS-box. Use
    rubyscript2exe killerapp.rb --rubyscript2exe-rubyw
    to create an executable that starts without a DOS-box.
    However, if I switch off the DOS box, my Qt-Ruby application refuses to start.
  3. When your executable gets started, it extracts all dlls, the Ruby runtime and your application to
    [Current User's Home]\eee\eee.killerapp.exe and starts from there. Your application’s dependencies might include some large dlls (e.g. QtGui4.dll which is 8 MB), so the extraction takes some time and your application startup feels somewhat slow.
    In case of my application, the directory from which the application is running is 36 MB large and even after the application has quit, not everything is deleted and the dlls take up 21 MB of disk space. This is a HDD memory leak!

That’s it for now. As soon as I make progress on the latter two issues, I will update the post accordingly. I you have a hint, I would welcome your comment.

Happy deploying!

Getting Qt and Ruby (=QtRuby) running on Windows XP

Important note

An update on this post is available here. The improvements are

  • only 6 steps instead of 10
  • QtRuby 2.1.0 instead of whatever old version is installed by the guide below
  • Qt 4.6.1 instead of Qt 4.3.4
  • Ruby 1.8.7 instead of Ruby 1.8.6

This is a tutorial about writing Ruby applications that use the Qt framework on Windows XP. For doing so, the Qt-Ruby bindings named QtRuby are used.


Ruby programs that have a nice GUI? Is that possible? With all that Ruby On Rails stuff going on, good old desktop applications have been left behind. And so has the topic of creating a desktop application that is pleasant to use and to code.

When combining Ruby and Qt, developers finally have a chance to create Ruby GUI applications that are neither pain in the ass for developers nor pain in the eye for the user.


At the time of writing this I have very little experience with QtRuby. However I just wanted to get started with it and did not find a decent guide for doing so on windows, so I just put together what I learned in the first few days.
For the sake of simplicity and brevity, this guide does not use the latest versions of Ruby, Qt and QtRuby. Instead, it is using prebuilt binaries and installers, that have been created by some nice guys (for getting the latest version running, see comments).
You have been warned. Comments are welcome.

Setting everything up

Getting your first QtRuby program to run under windows is surprisingly simple.

Installing Ruby

  1. Download the Ruby One-Click Installer from the official Ruby site: Make sure to use that exact version. Otherwise you might run into dll-version problems (see Yann’s comment for details).
  2. During installation, check the SciTE and Enable RubyGems options. SciTE is an editor and Gems is the Ruby package manager (we won’t need those here, but they are both very handy tools).
  3. Install to c:\ruby. You may of course choose a different path, but for the rest of this guide I will assume this location.
  4. When installation is finished, open a shell and type ruby --version. It should say ruby 1.8.6.

Installing Qt

  1. Download  Qt 4.3.4 Open Source Edition from and install it.
  2. During installation,  check the Install mingw option (if you do not yet have mingw installed). mingw is a gcc (C++ compiler) for Windows. Qt 4.3.4 Open Source comes with precompiled binaries that need the runtime dll (mingwm10.dll) of mingw.
  3. To check, whether the installation worked, go to Start->Programs->Qt->Examples and Demos. You should see a window with fancy animation that offers various examples of Qt in action.

Installing QtRuby

  1. Get the installer from and install it.
  2. Open irb (that’s a Ruby shell) by typing irb at your Windows shell.
  3. Type require 'Qt4' and execute it by pressing Enter. It should yield true

That’s it! Now you are ready to begin development of QtRuby programs.
You may leave now if you want and hack away on your own. However, if you want some advice on how to start and where to get information, I kindly invite you to stay a bit longer.

Hello Qt, Hello Ruby!

Let’s see if we can greet our new friends. Type the following program into the irb. Alternatively you may copy-paste the code into a fresh file. Name it main.rb and run it with ruby main.rb.

require 'Qt'
app ="Hello Ruby, hello Qt!")

Hello Ruby, hello Qt

You should see something that looks strikingly similar to the screenshot.

Getting Help on Qt
Qt is the best-documented library I have ever seen. You can find everything at
(The QtRuby version you downloaded has been built against Qt 4.3.1)

The docs are available as an offline version: If you install and compile an open source version of Qt (see this post ), you will get a program called Qt Assistant (assisstant.exe) that offers the full documentation and some neat searching features.
When installing Qt, you will also get a nice program called qtdemo.exe. It contains lots of example programs (in fact the Regular Expressions ‘example’ is one of my favorite tools at work).

However, there is one drawback on both, the documentation and the example programs. It is all written for C++ coders. Damn!
Fortunately the difference between C++-Qt and Ruby-Qt is not that big. But it gets even better…

Tons of Examples (in Ruby!)
…because a very kind guy named Richard Dale converted the Qt examples from C++ to Ruby. They come with the QtRuby source package, that can be found on the Rubyforge homepage of Korundum/QtRuby ( Let me show you how to get them running (and introduce you to the resource compiler on the way).

  1. Download e.g. qt4-qtruby-1.4.9.tgz and unpack it
  2. Browse to the directory qt4-qtruby-1.4.9\ruby\qtruby\examples\graphicsview\collidingmice and open a shell
  3. Type ruby main.rb
  4. And tadaah – you will get an error message saying no such file to load -- qrc_mice.rb (LoadError)

The reason for this error is that the resources (images in this case) have to be available for the program to work. To create the required resource file, we have to execute the Ruby-pendant of the Qt resource compiler (rbrcc, probably located in c:\ruby\bin)
rbrcc mice.qrc -o qrc_mice.rb
Try ruby main.rb again. This time you should see a window with some mice running around in it.

Colliding Mice Example in Ruby

More, More, More
When finished with this short introduction, I strongly recommend to check out
immediately. It explains how the concepts of Qt/C++ translate to QtRuby, gives a few nice tricks, that are not possible in C++ and demonstrates some convenient features of QtRuby. There’s also a bunch of links at the bottom of that page, that points out more resources to learn about QtRuby.
Great stuff, one small warning: It appears that the example code is written for Qt 3.x. So keep that in mind when copy-pasting it.

Well, that’s it for now. Happy coding!