Cross-platform UI with Qt4 and Ruby – Mac/Linux HOWTO
Today I’ve spent the day working on figuring out how to make UIs using Ruby and Qt4. If you haven’t heard of it, Qt4 is an awesome UI framework written in C++. Since C++ is way too much work, some great KDE devs wrote a bindings generator for Qt4 called qt4-qtruby. While this package is fairly “linuxy”, it’s pretty easy to build it on Mac OS X too, making it possible to write GUI programs for OS X without having to delve into RubyCocoa which has too much hackiness (in my opinion), or even worse, Objective C. Furthermore, your code that you write on OS X will look great on Windows and Linux too!
Starting from scratch
First, install Ruby. If you’re using Linux, you’ll probably use the package manager to install Ruby and the Ruby development libraries! (Ubuntu will run sudo apt-get install ruby irb ruby-dev) OS X Tiger ships with Ruby by default, but you’ll want to install an updated version, via the Ruby one-click installer, then disable the old Ruby by using the following command:
touch ~/.bashrc && echo ‘export PATH="/usr/local/bin:$PATH"’ >> ~/.bashrc
sudo mv /usr/lib/libruby.1.dylib /usr/lib/_libruby.1.dylib
Installing Qt4 and QtRuby
First, install Qt4 by using your package manager on Linux (in Ubuntu, use the -kdecopy packages, they are more up to date), or by downloading the DMG from the Qt/Mac Open Source Edition Download page. You’ll also need MacPorts (and by proxy, the XCode tools). Also, download the Qt4 Ruby bindings source code from Rubyforge and save it to the Desktop.
Here’s the cool thing about QtRuby, and the advantage of building it from source: the build framework for QtRuby scans through whatever version of Qt you have installed, and dynamically builds the bindings. This means, there’s no waiting for new Qt features to be available in Ruby, it’s always up-to-date! Which is quite handy, because it seems like every minor version of Qt has new cool stuff.
Next, we have to do a bit of hackery – unfortunately, there’s no easy way to install QtRuby but it’s not so hard. Here’s what you’ll run:
sudo port install cmake ## CMake is a cool build system
tar -xzvf qt4-qtruby-1.4.9.tgz && cd ./qt4-qtruby-1.4.9
cmake .
make && sudo make install
Try it out!
Once you’ve got it built, try this sample code to see some of the new features in Qt 4.3 – this code will run a natively-styled wizard in Windows, Mac, and Linux without any changes! Unfortunately, this code isn’t very elegant or Ruby-like, but it’s a base that someone could write a really elegant UI framework over like RoR.
a = Qt::Application.new(ARGV)
def create_intro_page
page = Qt::WizardPage.new do |p|
p.title = "Introduction"
end
label = Qt::Label.new("This is a wizard!")
label.word_wrap = true
layout = Qt::VBoxLayout.new do |v|
v.add_widget(label)
end
page.layout = layout
page
end
wiz = Qt::Wizard.new do |x|
x.add_page(create_intro_page())
x.set_window_title("Test Wizard")
x.show
end
a.exec
![]() On Mac OS X |
![]() On Linux |
In summary:
- Install a Ruby that doesn’t suck, and hack your environment so it works right
- Install Qt and MacPorts
- Build QtRuby and install it
- Make UIs for all 3 platforms without hating your life


I wish all guides to installing stuff on Mac would be like this one.
Rasmus
25 Jul 07 at 7:12 am
It bears mentioning that the actual bindings generator sitting behind this is Smoke (written in Perl) — Smoke is actually capable of generating bindings for many different languages, on top of which certain additional customizations are added for the particular language. This tool is what is used to generate most of the Qt and KDE bindings, including, I believe, the Qyoto C#/Mono bindings.
The other disadvantage is that, while you can definitely write applications like this, in order to distribute them, you’ll need people to have:
* Ruby
* Qt (the right version)
* QtRuby
That’s fine for limited distribution, but for wide-scale it would probably be a problem. Nonetheless, this is kickass, as Qt is something like the coolest UI toolkit on the face of the planet
And just imagine… When Qt 4.4 comes out, it’ll come with WebKit integrated!
Shadowfiend
27 Jul 07 at 5:14 pm
This is definitely a problem I’m aware of. My grandiose plan is to make Rake tasks that automatically package an application for all three platforms, doing “the right thing” for Win, Mac, and Linux. However, that’s a pretty far-out vision – in the interim, basically my plan is to include the Qt and QtRuby libraries statically in the .app. I’m also considering the actual main executable a stub that possibly goes out and downloads the Ruby one-click installer.
For Linux, it really isn’t a problem at all – you just set the dependencies in the DEB/RPM. Mac and Windows are the “hard” ones, especially Windows having weird compiler issues on top of the packaging issues.
Paul Betts
27 Jul 07 at 10:06 pm
I agree possibilities are enormous for cross platform applications.
I was pretty excited to see a book on qtruby
http://pragmaticprogrammer.com/titles/ctrubyqt/index.html
but ruby qt4 gem/bindings for windows are still not available.
last message I see in the rubyforge discussion is over a year old
http://rubyforge.org/forum/message.php?msg_id=9388
the ruby version which windows generally use, one click installer or instant rails is compiled with VC++ and not mingw.
hope someone builds a mswin32 gem for us
Senthil
Senthil Nayagam
30 Jul 07 at 2:59 am
[...] Cross-platform UI with Qt4 and Ruby – Mac/Linux HOWTO » Thursday Night [...]
del.icio.us bookmarks - 2007-08-26
27 Aug 07 at 2:20 am
Hi, thanks for the post, it helped.
I am not sure if the Qt/Ruby bindings are being actively developed any longer. The most recent version (1.4.9) from http://rubyforge.org/projects/korundum/ is (as of today) ten months old. It does not compile correctly out of the box, so it can be made to work if you are patient.
Here’s how:
1. After downloading qt-ruby-1.4.9, you’ll need to also get some more recent perl code. Go here: http://websvn.kde.org/trunk/KDE/kdebindings/kalyptus/ and download the files ‘kalyptus’ and ‘kalyptusCxxToSmoke.pm’, and replace your local versions with those.
2. cmake .
3. make
It will fail at some point with an error complaining about a header file that can’t be found. Edit the c++ file (in my case it was x_14.cpp) and simply comment out the offending line. The c++ file was generated by smoke, which is done earlier in the ‘make’ process.
4. make (again)
5. sudo make install
The ruby code in this blog post works! Unfortunately, the ‘Hello world’ code I’ve seen elsewhere fails. I don’t know if this has to do with changes to the Qt API or not, since I’m a Qt nube.
Hope that helps somebody, somewhere.
Gabe Johnson
5 Apr 08 at 12:52 pm
It worked for me too (thanks Gabe Johnson for your tip)!
Simone D.
6 Apr 08 at 2:43 am
Thanks for the post and thanks Gabe Johnson for the tip. I finally got it working…
Dilney
21 Apr 08 at 2:25 pm
Thanks it worked. But i could only build qt4ruby with qt-mac source 4.3, when i tried with qt 4.4.3, qt4ruby 1.4.9 and qt4ruby 1.4.10 both had compile errors.
Jayakrishnan
1 Nov 08 at 1:00 am
Hi to all,
We are developing an application based on Qt Ruby. In that we need to play a flash file. But i don’t know how to run a flash(.swf) file in Qt. Can any one suggest or give code to run .swf file in Qt Ruby application.
Regards,
Narasimha Raju. Naidu
Narasimha Raju. Naidu
4 Nov 08 at 3:03 am
I can make the files, but when I install, I am given a bunch of install options. Which ones do I choose?
Any help appreciated…
Heinrich
Heinrich17:qt4-qtruby-1.4.10 hbeck$ make && sudo install
[ 53%] Built target smokeqt
Scanning dependencies of target qtruby4
[ 56%] Building CXX object ruby/qtruby/src/CMakeFiles/qtruby4.dir/handlers.o
Linking CXX shared module qtruby4.so
[ 60%] Built target qtruby4
Scanning dependencies of target rbuic4_bin
[ 63%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/customwidgetsinfo.o
[ 65%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/databaseinfo.o
[ 68%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/driver.o
[ 70%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/treewalker.o
[ 73%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ui4.o
[ 75%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/uic.o
[ 78%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/validator.o
[ 80%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ruby/rbextractimages.o
[ 82%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ruby/rbwritedeclaration.o
[ 85%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ruby/rbwriteicondata.o
[ 87%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ruby/rbwriteicondeclaration.o
[ 90%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ruby/rbwriteiconinitialization.o
[ 92%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/ruby/rbwriteinitialization.o
[ 95%] Building CXX object ruby/qtruby/tools/rbuic/CMakeFiles/rbuic4_bin.dir/main.o
Linking CXX executable rbuic4
[ 95%] Built target rbuic4_bin
Scanning dependencies of target rbrcc
[ 97%] Building CXX object ruby/qtruby/tools/rbrcc/CMakeFiles/rbrcc.dir/rcc.o
[100%] Building CXX object ruby/qtruby/tools/rbrcc/CMakeFiles/rbrcc.dir/main.o
Linking CXX executable rbrcc
[100%] Built target rbrcc
Password:
usage: install [-bCcpSsv] [-B suffix] [-f flags] [-g group] [-m mode]
[-o owner] file1 file2
install [-bCcpSsv] [-B suffix] [-f flags] [-g group] [-m mode]
[-o owner] file1 … fileN directory
install -d [-v] [-g group] [-m mode] [-o owner] directory …
Heinrich17:qt4-qtruby-1.4.10 hbeck$
Heinrich
7 Nov 08 at 3:45 pm
check out this http://qtjruby.org/
Gacha
21 Nov 08 at 6:17 am
@Gacha: This looks to be full of awesomeness – thanks!
Paul Betts
9 Jan 09 at 4:41 pm
if you use macport qt4-mac, qt4-qtruby-1.4.10
that don’t forget about
http://rubyforge.org/tracker/download.php/181/761/23116/4207/qt4-qtruby.patch
Ivan Sidarau
16 Feb 09 at 9:16 am
[...] Qt on the Mac is a tad bit different, both harder and easier. I primarily followed this guide, but I had a few issues which will be documented here. Note that the guide was made for Os X 10.4 [...]
Qt and Ruby on Windows and Mac « The Curious Penguin
20 Jun 09 at 9:57 am