Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Compiling MacRuby Code

ferrous26 edited this page · 3 revisions

MacRuby is capable of compiling your Ruby code into native machine code ahead of time (AOT) instead of just in time (JIT). The best description of compiling MacRuby code comes from the macrubyc man page itself:

     macrubyc is a command-line interface to the MacRuby Ahead-of-Time (AOT) compiler. It statically compiles
Ruby source code into native machine code (object files), and can then link it (dynamically or statically)
into executables or dynamic libraries.  It is typically invoked from ruby_deploy rather than being called

     The Ahead-of-Time compilation process has two major advantages. The Ruby code does not need to be parsed
and compiled at runtime, which improves the startup time of the program, and the original Ruby source code is
no longer available, as it has been compiled down to machine code.

     macrubyc allows the compilation of Ruby programs that will use the MacRuby dynamic runtime, supporting
the entire Ruby specifications set. It also permits static compilation of Ruby code into a standalone 
executable that embeds a static version of the MacRuby runtime. These executables can be deployed on 
environments where MacRuby is not installed, but some features of the Ruby language are not supported.

While most code will "Just Work"™ with the AOT compiler, there are still some bugs, so you will need to test your code after compilation to make sure everything is still working properly (but you were going to do that anyways, right? :P).


The MacRuby compiler command line interface is the most configurable interface for compiling your MacRuby code. The best documentation for this is the man page, try man macrubyc or macrubyc --help from the command line.

Most commonly you will simply want to make a 1:1 conversion of ruby files into object files. To do this you would use the -C option for macrubyc:

macrubyc -C -o ruby_code.rbo ruby_code.rb

This command will generate a new file, ruby_code.rbo, which contains the machine code equivalent of your ruby code.

The MacRuby convention is to use the .rbo extension for compiled ruby files. If both the .rbo and .rb files are present when requiring files, the .rbo file will be preferred.


When you deploy your MacRuby app (through Xcode, HotCocoa, or another tool), the --compile option can be used to have the compiler AOT compile each of your ruby files. This is equivalent to calling macrubyc with the -C option.

Compilation is turned on by default during deployment of Xcode projects, but can be turned off by modifying the Deployment target's Arguments.

After compilation, the original .rb files are removed from the application bundle.


MacRuby ships with an additional Rake task for compiling your ruby library or gem. The most basic usage requires adding two lines to your Rakefile.

require 'rake/compiletask'

The default task is named compile and is equivalent to calling macrubyc with the -C on each *.rb file in the lib/ directory of your project. While this is usually good enough, there are a few options to customize the CompileTask; check the documentation here for more information.

The most common issue is that you may need to change the name of the task, which can be done by passing a parameter at initialization:

Third Party Tools

The internals of the compiler are a private API, but there are some developers who have thrown caution to the wind and developed additional tools.

Something went wrong with that request. Please try again.