As the owner of the semi-official MacRuby github mirror I would like to introduce you MacRuby.

MacRuby is a Ruby bridge to Apple’s Cocoa/Objective-C that enables a developer to take fully advantage of the OS X frameworks while developing the application in Ruby programming language.

Quoting the official README:

MacRuby is a Ruby implementation based on Mac OS X technologies, such as the Objective-C runtime and garbage collector, the CoreFoundation framework and the LLVM compiler infrastructure.

Neat I’d say.

Let’s start by installing MacRuby (remember: you have to install Xcode from official Snow Leopard DVD if you want to compile from source).

Update: check out the MacRuby nightly builds.

First we need the LLVM trunk, and keep in mind that PowerPC is not supported.

Start by grabbing a stable version of LLVM from their svn server.

Update: the recommended LLVM revision is now 82747.

svn co -r 82747 https://llvm.org/svn/llvm-project/llvm/trunk llvm-trunk
cd llvm-trunk
./configure

Now you should know that compiling LLVM takes a long while.
To help speed up things you can take advantage of using two cores of your CPU, which is the case of the majority of the newer machines.

UNIVERSAL=1 UNIVERSAL_ARCH="i386 x86_64" ENABLE_OPTIMIZED=1 make -j2

However this can leave your machine in a sort of unresponsitive state, so if you prefer you can take away the “-j2″ parameter.

After your usual cup of coffee we can install LLVM with this command:

sudo env UNIVERSAL=1 UNIVERSAL_ARCH="i386 x86_64" ENABLE_OPTIMIZED=1 make install

Now we are ready to build MacRuby.

Start by cd-ing, if you’re not there already, into your preferred directory, we are going to use Git to download from trunk.

Update: instructions on how to install git on Snow Leopard are here.

git clone git://github.com/masterkain/macruby.git
cd macruby
rake
sudo rake install

That’s it.

Installing MacRuby won’t touch your existing ruby binaries, in fact it will install them prefixed with “mac”.
For instance you can open up MacRuby’s version of IRB with the command:

macirb  --simple-prompt

and start playing around.

There are other commands, just type “mac” and press tab in your terminal to see other binaries.

The very first thing to try out is to load a framework, namely ‘Cocoa’, so fire up your macirb and give it a try:

kain-osx:~ kain$ macirb
irb: warn: can't alias exit from irb_exit.
irb(main):001:0> framework 'Cocoa'
=> true
irb(main):002:0>

Go on and try loading an Objective-C class:

irb(main):002:0> NSSound.ancestors
=> [NSSound, NSObject, Kernel]

All classes in MacRuby always inherit from NSObject:

irb(main):003:0> Regexp.ancestors
=> [Regexp, NSObject, Kernel]

There are many things that are cool/exciting in this technology, for example take a look at this:

irb(main):004:0> String
=> NSMutableString

Uh. Seems like Ruby classes are mapped to their equivalents in Objective-C.
That’s right, and this happen with no data loss nor they require manual conversion!

One difference with RubyCocoa is that MacRuby supports keyed arguments, for instance:

MacRuby:

1
2
3
4

window = NSWindow.alloc.initWithContentRect frame, 
    styleMask:NSBorderlessWindowMask,
    backing:NSBackingStoreBuffered,
    defer:false

RubyCocoa:

1
2
3
4
5

window = NSWindow.alloc.initWithContentRect_styleMask_backing_defer(
    frame,
    NSBorderlessWindowMask,
    NSBackingStoreBuffered,
    false)

Objective-C:

1
2
3
4
5

NSWindow *window = [[NSWindow alloc]
    initWithContentRect:frame
    styleMask:NSBorderlessWindowMask
    backing:NSBackingStoreBuffered
    defer:false];

Let’s see how one can send message to our objects using MacRuby.
There are different syntaxes to accomplish this, let’s see some examples along with their Objective-C equivalent:

1
2

person.setName(name) # [person setName:name];
person.name = name # [person setName:name];

As we already said every class here inherits from NSObject, therefore is not necessary to explicitly define subclassing, like we did in RubyCocoa:

1
2
3
4

# RubyCocoa
class TestController < OSX::NSObject
# MacRuby
class TestController

Let’s build a very simple app to demonstrate that MacRuby works, open Xcode and choose New Project; from User Templates go into Application and select MacRuby Application, press “Choose..”.

A dialog will appear, give the application a name you prefer (“Hello World” will suit) and press Save. I usually save my project in a proper dedicated folder.

At this point Xcode will show you its main window, click on the left on “Other sources”.

You will see two files in there, main.m and rb_main.rb .

main.m is a small file which contains the method that calls the MacRuby initializer.
rb_main.rb is the ruby script that will be executed once your application started.

If you click on “Build and run” the application will start, showing you an empty window. cmd+Q for quitting the application.

Now click from the top menu File -> New file or just press cmd+N, from the left select “Other” and click on “Empty file”.

Press next and in the File name input write “MyController.rb”.

Press “Finish”.

If you see that MyController.rb on the left is floating around, just drag it into “Classes” folder. Be aware that Xcode folders doesn’t reflect the actual data structure on filesystem, but rather represent a logical approach.

Edit MyController.rb by selecting it and writing in the editor window:

1
2
3
4
5
6

  class MyController < NSWindowController
    attr_writer :button
    def clicked(sender)
      puts "Button clicked!"
    end
  end

cmd+s to save the file.

Now, this code defines a subclass of NSWindowController and have two methods, a setter:

1

attr_writer :button

and clicked method:

1

def clicked(sender)

Those will serve the purpose especially with Interface Builder. In fact IB will see them respectively as an outlet and an action (for Obj-C users IBOutlet, IBAction).

To make sure that Interface Builder will pick up our method as an action, remember that it must have only one argument and that must be named sender.

We now have to wire our class with Interface Builder (from now on “IB”, go into the “Resources” folder and double click on MainMenu.nib .

In IB we need to instantiate our class to make it aware that we want to use one, to do that from the Library pane drag and drop a NSObject (blue cube) to the main window and select it.

From the inspector pane, as show in the next picture, select MyController as the Object Class.

Now drag a NSButton always from the Library pane to your main window.

While having the just placed button selected Press CTRL and left click, this will make a line appear; place it over My Controller we defined earlier (blue cube) in your MainMenu.nib window.
When releasing the mouse a little hud-like menu will appear, named “Received Actions”.
Release the mouse when hovering “clicked:”.

That’s it, we made a connection from this button to our method in our MyController.

Save the Nib file, go back to Xcode and press “Build and run”.

Your application will start, showing a window and a button.
Leaving the application running let’s go back to xcode, and press the little icon on the right with “gdb” on it, this will open up the debugger window.

Now, leaving this window visible let’s try clicking on our button and see what happen.
If all went right we should see a bold “Button clicked!”.

That’s it for today, however there is much more to talk about, say HotCocoa.

For further documentation please refer to the official website of MacRuby project.