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:
This will produce the files
foo.so (on Linux).
foo.c is the
generated C extension source code and
foo.so is the compiled C extension.
foo.rb is a library, you can just rename, move or delete
if you have a backup, of course) and your Ruby program will just use
foo.rb is a script, then it isn’t possible to just run
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.
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.
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).
Just run (as root):
gem install ruby2cext
Or if you do not use the gem:
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").
Ruby2CExtension supports a very large subset of Ruby’s features:
define_method, ... (only when the block is given directly)
Things that (currently) don’t work:
breakwith a value from inside a block
returnfrom inside a block
defined?is not implemented for all cases
Some of the above things might be fixed in future versions.
Things that don’t work as expected and probably never will:
local_variables, that depend on a Ruby SCOPE
eval(str)and similar methods that parse a string and eval it; these methods work, but they might not behave as expected (i.e. access to local variables and similar things won’t work, see above)
callccworks but might behave strangely (in particular local variables might behave wrong)
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.
There are two “interfaces” to use Ruby2CExtension:
Please see their respective documentations.
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).
I would like to thank Eric Mahurin for various good ideas for optimizations and for inspiring Eval2C.
Copyright 2006-2007 Dominik Bathon.
Ruby2CExtension is licensed under the same terms as Ruby.