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.
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
file2.c and the compiled extensions
file2.so (the file extension depends on the platform).
Additionally it is possible to specify some options before the filenames.
--help: a help message is printed and the program exits regardless of other arguments.
--only-c: only the translation to C code is performed, the compilation to native extensions is omited.
--verbose: some status messages are printed, e.g. which files are currently translated or compiled.
--warnings: warnings are printed for some things that might not work as expected. The warnings do not cover everything mentioned in the limitations documentation.
--version: the Ruby2CExtension version is printed.
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 puts "a" class A; end
# b.rb puts "b" require "a" class B; end
# c.rb require "a" require "b" puts "c"
require-include feature is enabled if the
followed by a search path is given (possibly multiple times). The search paths
can be absolute or relative paths, they are searched for
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,
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
b.rb does not result in a second execution of
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
a b c
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
--verbose option), then each
inclusion of a file will be logged. This way one can easily check if the
expected files are actually included.
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
--optimization option followed by one
of the following optimization names:
const_cache: enables constant lookup caching
builtin_methods: enables optimization of calls to built-in methods
inline_methods: enables inlining of some built-in methods
case_optimize: enables case optimization
all: enables all of the above optimizations
rb2cx -wv file.rb rb2cx -I . -O all file.rb rb2cx -I . -I ../libs -O const_cache -O builtin_methods -w file.rb