rb2cx

rb2cx is the command line interface to the functionality of Ruby2CExtension. It takes one or more Ruby files, translates them to equivalent C extensions and optionally compiles them with the C compiler.

Sections: Overview, General Options, Include Option, Optimization Options, Examples.

Overview

The general usage is very simple, just run rb2cx with the filenames of the Ruby files as arguments:

rb2cx file1.rb file2.rb

This will produce file1.c, file2.c and the compiled extensions file1.so, file2.so (the file extension depends on the platform).

Additionally it is possible to specify some options before the filenames.

General Options

Include Option

Ruby2CExtension has an experimental feature that allows dependencies of a compiled Ruby file to be included in the same extension. This is best described with an example. Let’s say we have 3 files: a.rb, b.rb and c.rb:

# a.rb
puts "a" 
class A; end
# b.rb
puts "b" 
require "a" 
class B; end
# c.rb
require "a" 
require "b" 
puts "c" 

The require-include feature is enabled if the -I/--include option followed by a search path is given (possibly multiple times). The search paths can be absolute or relative paths, they are searched for required files. So, if the example is compiled to a C extension with

rb2cx -I . c.rb

then the following will happen. For each call to require with no explicit receiver and one argument that is a simple string (i.e. no interpolation) the search paths are searched for a file that matches the argument to the require call (with an algorithm similar to Ruby’s). If no matching file is found, then the call to require is compiled as usual. But if a matching file is found, then that file is read and it is translated to C and instead of compiling the original require call that translated C code will be executed, unless a require of that file was encountered before.

So in the example we will get one C extension, that contains the code of all three files and the requires are performed at the right moment and in correct order. The output will be (notice that the require "a" in b.rb does not result in a second execution of a.rb, as expected):

a
b
c
As stated above, this feature is experimental, it should work well for many cases, e.g. for a library that has one main file which is always required by user code, but is split into multiple files for maintenance. Such a library could be compiled into a single C extension. But it can break for various reasons, e.g. Ruby will not be aware, that the included files are already “required” (so if a file is already included in a C extension, but also required by other normal Ruby code, then that file will in effect execute twice).

If the verbose mode is enabled (the -v/--verbose option), then each inclusion of a file will be logged. This way one can easily check if the expected files are actually included.

Optimization Options

Ruby2CExtension can use various optimizations to improve the performance of the resulting C extension. These optimizations are not enabled by default, because they can all result in wrong behavior. The optimizations are enabled by the -O/--optimization option followed by one of the following optimization names:

Examples

rb2cx -wv file.rb
rb2cx -I . -O all file.rb
rb2cx -I . -I ../libs -O const_cache -O builtin_methods -w file.rb