Spinel compiles Ruby into native programs

Spinel is a compiler and it works differently than CRuby (MRI)

CRuby (also called MRI, Matz's Ruby Interpreter) is an interpreter: it compiles each file to bytecode when it loads it, and runs that bytecode in a virtual machine. So a program can load or create new code while it runs.

Spinel works differently. It reads the whole program first, figures out the type of every value, and writes C. So the program you run is native machine code, plus a small runtime library from Spinel for things like garbage collection.

What Spinel checks before compiling a Ruby script

Before Spinel writes any C, it checks that it can be sure about every value and every call in the program. Here's a small program that passes the check, and one that fails it:

def double(x) = x * 2
puts double(21)

code = $stdin.gets
puts eval(code)

spinel: e3.rb:2: unsupported eval of a runtime string is not supported by AOT compilation (define the code statically)
spinel: 1 refusal, nothing written

Spinel's docs call this a refusal. The message tells us the file and line.

What does the C program that Spinel writes look like?

Let's go back to double. We can compile it with spinel -S, which prints the C instead of making a program. We can compile it twice: first when it only gets Integers, and then when it gets an Integer and a String. The C below is trimmed to the parts that change, with comments added.

1. double only gets Integers

# one.rb
def double(x)
  x * 2
end

puts double(21)
puts double(4)

/* one.c */
sp_int sp_double(sp_int lv_x) {
  return sp_int_mul(lv_x, 2LL);
}

/* puts double(21) */
sp_oint _t1 = sp_oint_of(sp_double(21LL));
printf("%lld\n", (long long)_t1.v);

sp_int is a plain C integer. So x can stay in a CPU register, and x * 2 is one multiply plus an overflow check. puts becomes a printf.

2. double gets an Integer and a String

# two.rb
def double(x)
  x * 2
end

puts double(21)
puts double("ab")   # "abab"

/* two.c */
sp_RbVal sp_double(sp_RbVal lv_x) {
1/* tell the garbage collector about x */
  struct { sp_gc_frame_hdr h; void **p[1]; } _gcf = {{0, 1}};
  SP_GC_ROOT_FRAME(_gcf);
  _gcf.p[0] = SP_GC_ENTRY_RBVAL(lv_x);
2return sp_poly_mul(lv_x, sp_box_int(2LL));
}

/* puts double(21): box 21 into main's own GC frame first */
_gcf.v[0] = sp_box_int(21LL);
3sp_poly_puts(sp_double(_gcf.v[0]));
/* puts double("ab") */
3sp_poly_puts(sp_double(SP_STR_BOX(((char *)_fzl_4d2505ca.d))));

Now x can be two types, so Spinel can't use a plain C integer for it. It uses sp_RbVal instead, a boxed value: a tag that says what's inside (Integer, String, and so on) and the value itself. We can also see these changed:

• 1double now tells the garbage collector about x, because x can hold a String that lives in memory.
• 2x * 2 becomes a call to sp_poly_mul. It checks the tags while the program runs and picks the right multiply: Integer times Integer, String repeat, Float, Array, and more.
• 3puts becomes sp_poly_puts, which also checks the tag first.

Without the #line directives (spinel -S --no-line-map), the whole C file goes from 47 lines to 97 lines, mostly for the support code that Strings, Symbols and class names now need.

In Spinel, value types can affect performance A LOT

To see the cost, we can call double(i) 200 million times in a loop, and then add one double("ab") call after the loop:

def double(x)
  x * 2
end

sum = 0
i = 0
while i < 200_000_000
  sum += double(i)
  i += 1
end
puts sum
puts double("ab") # second version only

The String call runs only once, after the loop. But it still makes Spinel's loop about 15 times slower, because double now takes a boxed value on every call.

We can see why in the machine code, with objdump -d on the two programs. In the Integer-only program, the C compiler inlines double and turns x * 2 into adding 2 each time. The whole loop is 8 instructions and has no calls (the jump labels are renamed to make it easier to read):

# Integers only
loop:
  xor  %ecx,%ecx
  add  %rax,%rdx    # sum += 2 * i
  seto %cl          # overflow check
  add  $0x2,%rax    # next 2 * i
  test %rcx,%rcx
  jne  overflow
  cmp  $0x17d78400,%rax # 2 * 200_000_000
  jne  loop

In the two-type program, sum also becomes a boxed value, because double now returns one. So every time through the loop, it registers values with the garbage collector and calls two runtime functions that check the tags:

# Integer and String
  call sp_poly_mul  # x * 2
  call sp_poly_add  # sum += double(i)

So Spinel is fastest when each value keeps one type.

Ruby features that Spinel doesn't support

Here are two more Ruby features that Spinel refuses:

class Ghost
  def method_missing(name, *args)
    "you called #{name}"
  end
end
puts Ghost.new.hello

spinel: mm.rb:2: warning: method_missing is defined but spinel does not dispatch undefined-method calls to it; such calls raise NoMethodError (method_missing can still be called explicitly)
spinel: mm.rb:6: undefined method 'hello' for an instance of Ghost (NoMethodError)
spinel: 1 refusal, nothing written

class Config
  ENV.fetch("FIELDS", "host,port").split(",").each do |name|
    define_method(name) { "value of #{name}" }
  end
end
puts Config.new.host

spinel: dm.rb:3: Module#define_method with a non-literal name is not supported; use a literal Symbol or String (see docs/limitations.md)
spinel: 1 refusal, nothing written

Spinel also doesn't support ObjectSpace.each_object, TracePoint, binding as an object, refinements and callcc. The full list is in docs/limitations.md.

Spinel tries to refuse any code it can't be sure about. But some unsupported code still compiles and only fails when it runs: Ractor.new compiles and then raises NameError. And Spinel still has bugs where it compiles a program and prints a wrong answer.

Spinel still supports some metaprogramming

Metaprogramming works when Spinel can see the names when it compiles: define_method and send with names written in the code, and Struct.new with a block. This program compiles and prints the same output as CRuby:

Point = Struct.new(:x, :y) do
  def +(other) = Point.new(x + other.x, y + other.y)
end

class Shape
  %i[area perimeter].each do |m|
    define_method(m) { raise NotImplementedError }
  end
end

class Square < Shape
  def initialize(side) = @side = side
  def area = @side * @side
end

p [Point.new(1, 2), Point.new(3, 4)].sum(Point.new(0, 0))
p [1, 2, 3].map { |n| Square.new(n).area }
%w[upcase reverse].each { |m| puts "spinel".send(m) }

#<struct Point x=4, y=6>
[1, 4, 9]
SPINEL
lenips

Speed on ruby-bench

ruby-bench is the benchmark suite in the ruby organization on GitHub. It has 88 benchmarks, and Spinel gets a speed number on only 29 of them.

Which benchmarks Spinel can run

The 29 benchmarks that have a speed number

Most of these are micro benchmarks, and real apps like Rails still can't run, so the averages don't say much about real apps yet.

Setup: Oct 31, 2026, Spinel 3e867e30, CRuby 4.0.7 and ruby-bench 73918b2 on a shared 4-core cloud VM, using ruby-bench's run_benchmarks.rb with its default settings. The chart shows the median time. YJIT's speedups on this VM are a little smaller than on rubybench.github.io.

Spinel's development activity

Matz made the first commit on March 16, 2026 and worked alone for 5 weeks. Then other people started to send pull requests.