Ruby2CExtension

Ruby2CExtension is a Ruby to C extension translator/compiler. It takes any Ruby source file, parses it using Ruby’s builtin parser and then translates the abstract syntax tree into “equivalent” C extension code.

Let’s say you have a Ruby file foo.rb. To translate it to a C extension and then compile it, just run:

rb2cx foo.rb

This will produce the files foo.c and foo.so (on Linux). foo.c is the generated C extension source code and foo.so is the compiled C extension.

If foo.rb is a library, you can just rename, move or delete foo.rb (only if you have a backup, of course) and your Ruby program will just use foo.so instead.

If foo.rb is a script, then it isn’t possible to just run foo.so, because Ruby does not support running C extensions directly, but you can do this:

ruby -r foo.so -e "" 

which should produce the same output as

ruby -r foo.rb -e "" 

Sections: Why?, Requirements, Download, Installation, Features, Usage, Feedback, Thanks, License.

Why?

Well, like everybody else I wanted a faster Ruby and I also wanted to learn about Ruby’s internals, so I thought translating Ruby to C might be worth a try…

The initial results were not as good as I had hoped, but they weren’t bad either: without optimizations the generated C extension is practically never slower than the Ruby code and I found cases where it is more than twice as fast, usually it is somewhere in between. But, starting from version 0.2.0, Ruby2CExtension can use optimizations to significantly speedup execution in many cases (sometimes more than five times faster than normal Ruby).

Of course Ruby2CExtension can also be used as an obfuscator for Ruby code, though this was not my main motivation.

Requirements

Ruby2CExtension is developed for the Ruby 1.8 versions (only 1.8.4 and later). It is currently tested with Ruby 1.8.4, 1.8.5 and 1.8.6. Only those versions should be used, because Ruby2CExtension depends on Ruby internals that can change between Ruby versions. If an untested Ruby version is used, then there will be a warning. It might work for later 1.8 versions, but it definitely won’t work with Ruby 1.9.

Ruby2CExtension requires RubyNode to access Ruby’s node trees (the AST). RubyNode is available at http://rubynode.rubyforge.org/.

Ruby2CExtension is pure Ruby code, so it should work on all platforms that Ruby supports, but it is currently only tested on Linux. There might be problems with the automatic compilation of the generated C code on some platforms (in particular on Windows).

Download

Installation

Just run (as root):

gem install ruby2cext

Or if you do not use the gem:

ruby setup.rb

This will install Ruby2CExtension to the default locations. Optionally you can supply some options to setup.rb to customize the installation (see "ruby setup.rb --help").

Features

Ruby2CExtension supports a very large subset of Ruby’s features:

Things that (currently) don’t work:

Some of the above things might be fixed in future versions.

Things that don’t work as expected and probably never will:

Ruby2CExtension will translate and compile Ruby files using one or more of the above functionalities without a warning (for some cases warnings can be enabled, see rb2cx), so if your Ruby code uses such functionality, please verify that the compiled C extension works as expected.

For more details please see limitations.

Usage

There are two “interfaces” to use Ruby2CExtension:

Please see their respective documentations.

Feedback

If you find a bug, think that something doesn’t work as it should or have other suggestions, then please don’t hesitate to contact me and tell me about it.

I am also interested to know if Ruby2CExtension works under Windows (or other non Linux platforms).

Thanks

I would like to thank Eric Mahurin for various good ideas for optimizations and for inspiring Eval2C.

License

Copyright 2006-2007 Dominik Bathon.

Ruby2CExtension is licensed under the same terms as Ruby.