module Rubellite::Docs::A_GETTING_STARTED::OVERVIEW

Overview

Getting Started & System Architecture

Rubellite is a high-performance interop framework designed to connect the Crystal and Ruby programming environments with zero overhead.

By pairing Crystal's LLVM-compiled speed with CRuby's expansive dynamic ecosystem, Rubellite enables developers to execute Ruby code directly within Crystal fibers, share native types, invoke methods with Crystal blocks, and bridge Crystal Channels with Ruby concurrency primitives.

Executive Summary & Key Topics

Topic Method / Anchor Description
Architectural Principles & Layering .topic_01_architecture Breakdown of Rubellite's three core runtime layers.

Related Guides & Source References

Defined in:

rubellite/docs/a_getting_started/overview.cr

Class Method Summary

Class Method Detail

def self.topic_01_architecture : Nil #

Architectural Principles & Layering: Breakdown of Rubellite's three core runtime layers.

Rubellite is structured into three distinct layers:

Layer Primary Role Location
**Crystal Host** Native execution, fiber scheduling, memory bounds `src/rubellite/`
**C API Bridge** Direct bindings to MRI `libruby`, symbol hygiene `src/rubellite/c_api.cr`
**Diagnostics** Radare2 symbol auditing, import library generation `src/rubellite/diagnostics/`

Rubellite manages GC safety across both engines: Crystal's Boehm GC and Ruby's compacting garbage collector coordinate to ensure unboxed primitives and heap-allocated Ruby objects remain valid across calls.

Working Examples

require "rubellite"

# Initialize the embedded Ruby VM
Rubellite.init

# Evaluate a Ruby expression and unbox the result
result = Rubellite.eval("2 + 2")
puts "Result: #{result.to_i64}" # => 4

# Clean up VM state on shutdown
Rubellite.cleanup

Common Pitfalls & Safety Caveats

  • Warning: Always call Rubellite.init before evaluating code or allocating Ruby values.
  • Warning: Ensure Rubellite.cleanup is invoked during shutdown to run Ruby at_exit handlers.

Frequently Asked Questions (FAQ)

  • Q: Does Rubellite require a standalone Ruby installation? A: Yes, Rubellite links dynamically against the system's CRuby shared library (libruby).

  • Q: What versions of Ruby are supported? A: CRuby 3.2 through 4.x are supported, with dedicated version branches tracking upstream releases.


[View source]