go-gem-wrapper

go-gem-wrapper is a wrapper for creating Ruby native extension in Go

• Go 1.23+
• Ruby 3.3+

At first, patch to make a gem into a Go gem right after bundle gem

See _tools/patch_for_go_gem/

Please also add the following depending on the CI you are using.

e.g.

- uses: actions/setup-go@v5
  with:
    go-version-file: ext/GEM_NAME/go.mod

For example, consider the following Ruby method implemented in Go

module Example
  def self.sum(a, b)
    a + b
  end
end

// ext/GEM_NAME/GEM_NAME.go

//export rb_example_sum
func rb_example_sum(_ C.VALUE, a C.VALUE, b C.VALUE) C.VALUE {
	aLong := ruby.NUM2LONG(ruby.VALUE(a))
	bLong := ruby.NUM2LONG(ruby.VALUE(b))

	sum := aLong + bLong

	return C.VALUE(ruby.LONG2NUM(sum))
}

// ext/GEM_NAME/GEM_NAME.go

/*
#include "example.h"

// TODO: Append this
VALUE rb_example_sum(VALUE self, VALUE a, VALUE b);
*/
import "C"

// ext/GEM_NAME/GEM_NAME.go

//export Init_example
func Init_example() {
	rb_mExample := ruby.RbDefineModule("Example")

	// TODO: Append this
	ruby.RbDefineSingletonMethod(rb_mExample, "sum", C.rb_example_sum, 2)
}

See also

• ruby/testdata/example/ext/example/example.go
• ruby/testdata/example/ext/example/tests.go

We provide auto-generated bindings for (almost) all CRuby functions available when including ruby.h 💪

See below for details.

• ruby/enum_generated.go
• ruby/function_generated.go
• ruby/type_generated.go
• _tools/ruby_h_to_go/

CRuby methods are mapped to Go methods based on the following rules

• No lowercase letters included (/^[A-Z0-9_]+$/)
  • No changes
  • e.g. RB_NUM2UINT (CRuby) -> ruby.RB_NUM2UINT (Go)
• Lowercase letters included
  • Converted to CamelCase
  • e.g. rb_define_method (CRuby) -> ruby.RbDefineMethod (Go)

Most of the methods defined in ruby.h are automatically generated and defined in ruby/function_generated.go.

However, some of the methods listed below are not supported.

1. deprecated or internal methods
   • See function.exclude_name in https://github.com/ruby-go-gem/ruby_header_parser/blob/main/config/default.yml
2. Methods with variable-length arguments
   • Because Go's variable-length arguments couldn't be passed directly to C.
   • However, it is possible to execute functions with variable length arguments in CRuby from Go with a hack like RbRaise in ruby/ruby_internal_error.go

Run bundle exec rake ruby:example:build.

See bundle exec rake -T for more tasks.

go install golang.org/x/tools/cmd/godoc@latest
godoc

open http://localhost:6060/pkg/github.com/ruby-go-gem/go-gem-wrapper/ruby/

Ruby meets Go - RubyKaigi 2015