ruby-extension-go

Build Ruby native extensions in pure Go - no Ruby required during installation!

Overview

This library provides native extension compilation support for Ruby gems in pure Go. It supports multiple build systems commonly used by Ruby gems, making it possible to build native extensions without requiring Ruby during the installation phase.

Ruby equivalent: Gem::Ext::Builder

Requirements: Go 1.25 or later

Supported Build Systems

• extconf.rb - The most common Ruby extension build system
• Rakefile - Rake-based builds (rake compile)
• CMake - CMake-based extensions
• Cargo - Rust-based Ruby extensions
• configure - Autotools-style configure scripts

Why This Exists

Part of the ORE ecosystem, this library enables:

• Building Ruby native extensions without Ruby installed
• Cross-compilation support
• Faster parallel builds
• Better error reporting
• Consistent build environment

Quick Start

go get github.com/contriboss/ruby-extension-go

Usage

Basic Extension Building

package main

import (
    "context"
    "log"

    rubyext "github.com/contriboss/ruby-extension-go"
)

func main() {
    // Create builder factory
    factory := rubyext.NewBuilderFactory()

    // Configure build
    config := &rubyext.BuildConfig{
        GemDir:       "/path/to/extracted/gem",
        ExtensionDir: "/path/to/ext",
        DestPath:     "/path/to/install",
        RubyPath:     "/usr/bin/ruby",
        RubyVersion:  "3.4.0",
        Verbose:      true,
    }

    // Build all extensions
    extensions := []string{"ext/myext/extconf.rb"}
    results, err := factory.BuildAllExtensions(context.Background(), config, extensions)
    if err != nil {
        log.Fatal(err)
    }

    for _, result := range results {
        if result.Success {
            log.Printf("Built: %v", result.Extensions)
        } else {
            log.Printf("Failed: %v", result.Error)
        }
    }
}

Building Specific Extension Types

// For extconf.rb extensions
builder := &rubyext.ExtConfBuilder{}
if builder.CanBuild("extconf.rb") {
    result, err := builder.Build(ctx, config, "ext/myext/extconf.rb")
}

// For Rust extensions
cargoBuilder := &rubyext.CargoBuilder{}
if cargoBuilder.CanBuild("Cargo.toml") {
    result, err := cargoBuilder.Build(ctx, config, "ext/rust_ext/Cargo.toml")
}

Build Systems Details

ExtConf Builder

Handles traditional Ruby C extensions using extconf.rb:

• Generates Makefile via Ruby
• Supports custom build flags
• Handles platform-specific configurations

Rake Builder

For gems using Rake for compilation:

• Executes rake compile
• Supports custom rake tasks
• Handles multi-stage builds

CMake Builder

For modern C++ extensions:

• Cross-platform support
• Out-of-source builds
• Advanced dependency management

Cargo Builder

For Rust-based extensions:

• Handles Cargo.toml projects
• Supports release/debug builds
• Manages Rust toolchain

Configure Builder

For Autotools-based extensions:

• Standard ./configure && make
• Cross-compilation support
• Platform detection

Features

• Parallel Builds - Use multiple CPU cores for faster compilation
• Cross-Compilation - Build for different architectures
• Build Caching - Avoid rebuilding unchanged extensions
• Error Recovery - Detailed error messages for debugging
• Platform Detection - Automatic platform-specific adjustments

Go 1.25+ Features

This library leverages modern Go features:

• Automatic GOMAXPROCS tuning - Respects container CPU limits on Linux
• DWARF 5 debug info - Smaller binaries and faster linking
• Modern generics - Type-safe builder patterns with simplified core types
• Performance optimizations - Benefit from Go 1.25 compiler improvements

Experimental Features

You can enable experimental Go 1.25 features for potential performance improvements:

# New garbage collector (10-40% GC overhead reduction)
# Best for small object-intensive applications
GOEXPERIMENT=greenteagc go build

# JSON v2 with better performance
# Substantially faster decoding, encoding at parity
GOEXPERIMENT=jsonv2 go build

Note: These are experimental features. Test thoroughly before using in production. They can be enabled via environment variable or build tags without code changes.

Architecture

ORE
 ↓
ruby-extension-go
 ↓
BuilderFactory
 ↓
├── ExtConfBuilder
├── RakeBuilder
├── CMakeBuilder
├── CargoBuilder
└── ConfigureBuilder

Building

We use Mage for builds:

# Install Mage
go install github.com/magefile/mage@latest

# Run tests
mage test

# Run linter
mage lint

# Build
mage build

# Run CI checks
mage ci

Testing

# Run tests with coverage
mage test

# Run tests with race detector
mage testrace

# Run integration tests
go test -tags=integration ./...

Performance

• Parallel compilation with make -j
• Efficient resource usage
• Build output caching
• Minimal overhead vs native builds

Platform Support

• Linux - Full support for all build systems
• macOS - Full support, handles SDK paths
• Windows - Limited support (MinGW/MSYS2)
• Cross-compilation - Via proper toolchain configuration

License

MIT

Related Projects

• ORE - The fast Ruby gem installer
• gemfile-go - Parse Gemfile and Gemfile.lock
• rubygems-client-go - RubyGems.org API client

---

Made by @contriboss - Building the future of Ruby dependency management