Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

321 lines (212 sloc) 10.2 KB


rake-compiler aims to help Gem developers deal with Ruby extensions, simplifying code and reducing duplication.

It followss *convention over configuration* and sets a standardized structure to build and package both C and Java extensions in your gems.

This is the result of experiences dealing with several Gems that required native extensions across platforms and different user configurations where details like portability and clarity of code were lacking.

An Overview

Let's summarize what rake-compiler provides:

  • No custom rake tasks required. Less code duplication and errors.

  • Painlessly build extensions on different platforms (Linux, OSX and Windows).

  • Painlessly build extensions for different Ruby implementations (JRuby, Rubinius and MRI).

  • Allow multiple extensions be compiled inside the same gem.

  • Mimics RubyGems installation process, so helps as a test environment.

  • Simplify cross platform compilation of extensions (target Windows from Linux).

I'm sold! show me how to use it! (Installation)

Usage of rake-compiler is pretty much straight forward.

First, you need to install the gem:

$ gem install rake-compiler

Now what? (Usage)

Now that you have the gem installed, let's give your project some structure.


Let's say we want to compile an extension called 'hello_world', so we should organize the code and folders that will help rake-compiler do its job:

|-- ext
|   `-- hello_world
|       |-- extconf.rb
|       |--
|       `-- hello_world.c
|-- lib
`-- Rakefile

TIP: Having a consistent folder structure will help developers and newcomers to find code and also contribute back to your project more easily.

Adding the code

So now it's time to introduce the code to compile our extension:

# File: Rakefile

require 'rake/extensiontask''hello_world')

Ok, that's it. No other line of code.

If we wanted to do the same for a JRuby extension (written in Java):

# File: Rakefile

require 'rake/javaextensiontask''hello_world')

Compile process

Those two lines of code automatically added the needed rake tasks to build the hello_world extension. Running Rake on 1.8.x/1.9 (MRI):

$ rake -T
(in /home/user/my_extension)
rake compile                # Compile the extension(s)
rake compile:hello_world    # Compile just the hello_world extension

Simply calling compile:

$ rake compile

Will do all the compile process for us, putting the result extension inside lib directory.

NOTE: Please be aware that building C extensions requires the proper development environment for your Platform, which includes libraries, headers and build tools. Check your distro / vendor documentation on how to install it.

NOTE: Building Java extensions requires the javac, part of the Java Development Kit (JDK). This should be included by default on Mac OS X, and downloadable from for other operating systems.

Generate native gems

A common usage scenario of rake-compiler is generate native gems that bundles your extensions.

This got over-simplified with Rake::ExtensionTask:

# somewhere in your Rakefile, define your gem spec
spec = do |s| = "my_gem"
  s.platform = Gem::Platform::RUBY
  s.extensions = FileList["ext/**/extconf.rb"]

# add your default gem packing task do |pkg|

# feed your ExtensionTask with your spec'hello_world', spec)

Now, as usual, you can build your pure-ruby gem (standard output):

$ rake gem
(in /projects/oss/my_gem.git)
mkdir -p pkg
  Successfully built RubyGem
  Name: my_gem
  Version: 0.1.0
  File: my_gem-0.1.0.gem
mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem

Plus, you have the functionality to build native versions of the gem:

# rake native gem
(... compilation output ...)
mkdir -p pkg
  Successfully built RubyGem
  Name: my_gem
  Version: 0.1.0
  File: my_gem-0.1.0.gem
mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
  Successfully built RubyGem
  Name: my_gem
  Version: 0.1.0
  File: my_gem-0.1.0-x86-mingw32.gem
mv my_gem-0.1.0-x86-mingw32.gem pkg/my_gem-0.1.0-x86-mingw32.gem

You get two gems for the price of one.

And the same for JRuby extensions:

# rake java gem
(... compilation output ...)
mkdir -p pkg
  Successfully built RubyGem
  Name: my_gem
  Version: 0.1.0
  File: my_gem-0.1.0.gem
mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
  Successfully built RubyGem
  Name: my_gem
  Version: 0.1.0
  File: my_gem-0.1.0-java.gem
mv my_gem-0.1.0-java.gem pkg/my_gem-0.1.0-java.gem

What about breaking the standards? (Customization)

In case you want to bend the convention established, rake-compiler let you personalize several settings for Rake::ExtensionTask: do |ext| = 'hello_world'                # indicate the name of the extension.
  ext.ext_dir = 'ext/weird_world'         # search for 'hello_world' inside it.
  ext.lib_dir = 'lib/my_lib'              # put binaries into this folder.
  ext.config_script = 'custom_extconf.rb' # use instead of 'extconf.rb' default
  ext.tmp_dir = 'tmp'                     # temporary folder used during compilation.
  ext.source_pattern = "*.{c,cpp}"        # monitor file changes to allow simple rebuild.
  ext.config_options << '--with-foo'      # supply additional configure options to config script.
  ext.gem_spec = spec                     # optional indicate which gem specification
                                          # will be used to based on.

Future is now: Cross compilation

rake-compiler provides now an standardized way to generate, from Linux or OSX both extensions and gem binaries for Windows!

It takes advantages from GCC host/target to build binaries (for target) on different OS (hosts).

How I enjoy this?

Besides having the development tool chain installed (GCC), you should install also mingw32 cross compilation package.

Installation depends will depend on your operating system/distribution. On Ubuntu and Debian machines, a simple apt-get install mingw32 will be enough.

On OSX, mingw32 is available via MacPorts: port install i386-mingw32-gcc (ensure you update your ports tree before hand as mingw32 has been been broken).

I have my tool-chain, now what?

You need to build Ruby for Windows.

Relax, no need to freak out! Let rake-compiler do it for you:

rake-compiler cross-ruby

And you're done. It will automatically download, configure and compile latest stable version of Ruby for Windows, and place it into ~/.rake-compiler

If, instead, you want to build another version than the default one, please supply a VERSION:

rake-compiler cross-ruby VERSION=1.8.6-p114

If you, like me, have multiple versions of MinGW packages, you can specify the HOST that will be used to cross compile ruby:

rake-compiler cross-ruby HOST=i386-mingw32 # (OSX mingw32 port)

The host will vary depending on provider (mingw32 versus mingw-w64 projects). Consult the documentation and website of the MinGW package provider before reporting any issue.

Let's build some gems!

Now, you only need to use additional options in your extension definition:'my_extension', gem_spec) do |ext|
  ext.cross_compile = true                # enable cross compilation (requires cross compile toolchain)
  ext.cross_platform = 'i386-mswin32'     # forces the Windows platform instead of the default one
                                          # configure options only for cross compile
  ext.cross_config_options << '--with-something'

  # perform alterations on the gemspec when cross compiling
  ext.cross_compiling do |gem_spec|
    gem_spec.post_install_message = "You installed the binary version of this gem!"

By default, cross compilation targets 'i386-mingw32' which is default GCC platform for Ruby.

To target gems for current Ruby official distribution, please force the platform to the one shown before.

Magician doing some tricks, don't blink!

Compiles keeps being simple:

rake cross compile

And now, build your gems for Windows is just 5 more letters:

rake cross native gem

And you're done, yeah.

Take it even further

You can specify against with version of Ruby you want to build the extension:

rake cross compile RUBY_CC_VERSION=1.8.6

If you installed 1.9.1, you can do:

rake cross compile RUBY_CC_VERSION=1.9.1

Even more, you can target multiple versions (ie. 1.8.6 and 1.9.1):

rake cross compile RUBY_CC_VERSION=1.8.6:1.9.1

And more exiting, bundle both binaries in one “fat” Gem:

rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.1

That will place binaries for 1.8 and 1.9 versions of ruby inside lib_dir


Now is up to you to make your gem load the proper one ;-)

What are you talking about? (Give me examples)

I know all the above sounds like a complete foreign language (it does even for me!). So, what if I show you some examples?

Check our wiki with links to the proper rake files used by many developers and projects and how they use rake-compiler.


rake-compiler is a work in progress and we will appreciate feedback during the development of it! (and contributions too!)

You can find more information about rake-compiler:


If you have any trouble, don't hesitate to contact the author. As always, I'm not going to say “Use at your own risk” because I don't want this library to be risky.

If you trip on something, I'll share the liability by repairing things as quickly as I can. Your responsibility is to report the inadequacies.

Jump to Line
Something went wrong with that request. Please try again.