This post originated from an RSS feed registered with Ruby Buzz by Sam Aaron. Original Post: Exploring Rubinius Feed Title: Communicatively Speaking Feed URL: http://sam.aaron.name/feed/atom.xml Feed Description: Sam Aaron's blog. Here you'll find interesting discussions on matters such as communicative programming, domain specific languages and music. Latest Ruby Buzz Posts Latest Ruby Buzz Posts by Sam Aaron Latest Posts From Communicatively Speaking

Wowsers, so you went ahead and got Rubinius working on your machine. You played about with sirb, and sighed at the beauty of the coloured error reports. What more in life could you want? Well, you’re reading this, so you must want more. So, before we can go anywhere, we need to have a look round and explore the structure of the project.

(This article is currently a general dumping ground for my current knowledge of the Rubinius codebase gleaned from reading the code, chatting to people in #Rubinius, and this wiki page. I’ll keep it up to date as both the directory structure changes, and my understanding of the codebase increases.)

If we look inside a fresh clone of Rubinius, we can see the following text files:

AUTHORS    LICENSE    README     Rakefile    configure  
INSTALL    Makefile   ROADMAP    THANKS

Rakefile, Makefile and configure were used to build Rubinius. The other files should be fairly self-explanatory. Go ahead, and read them. There are also a whole bunch of directories:

bin        configure  examples   hashi      lib        shotgun    stdlib
compiler   doc        extensions kernel     runtime    spec       test

Let’s go through these in turn:

bin

This directory contains a number of scripts mainly used to test Rubinius. For example, a mini version of RSpec (mspec) is included in this directory. There are also scripts to determine code coverage (completeness), support continuous integration (ci), and autotest amongst others. Ignore bin/rcc, bin/rasm, and bin/bm as they are now deprecated.

compiler

The compiler directory includes the translator, compiler and the assembler. The compiler turns a sexp to rubinius assembly. See kernel/core/compile.rb if you are looking for the entry point into this code

doc

The doc directory is currently an out of date dump of a bunch of documentation files. The stuff in here is due to be cleaned up and added to as more project documentation is written.

examples

Code samples. Likely to be deleted

extensions

Theoretically, a place to put Subtend extensions. Likely to be deleted.

hashi

This is an experimental directory containing files that implement essential features of the Rubinius bootstrap library. The goal is to enable the Rubinius core libraries to be run on other implementations like MRI and JRuby.

kernel

kernel/core – Ruby code to implement the MRI ‘core’ libraries kernel/bootstrap – Minimal implementations of various classes that are needed to load the rest of the system. Usually overriden when kernel/core loads kernel/platform – Platform-specific code and support. See platform/ffi.rb for details

lib

MRI C standard library code, rewritten in Ruby. StringIO and Socket are two current examples

runtime

Compiled output from the kernel/ and compiler/ directories

shotgun

The parts of Rubinius that are written in C, or generate C code. Fore example, there is a local copy of parsetree in shotgun/lib/grammar_runtime.c which converts the c struct from grammar.y into a sexp. This directory also contains the MRI parser (shotgun/lib/grammar.y) which reads in ruby and spits out sexps.

spec

Specs for Rubinius and also Ruby. This is an ambitious branch of the Rubinious project aimed at speccing out MRI’s behaviour.

stdlib

An imported copy of the Ruby 1.8.6 standard library. Note that there are only Ruby files in here.

test

Pre-spec test code, and tests borrowed from other Ruby implementations