From: "Mauricio Fernández" <batsman.geo@...>
Date: 2003-06-20T16:07:40+09:00
Subject: Re: reading ruby source

On Fri, Jun 20, 2003 at 11:31:08AM +0900, Shashank Date wrote:
> I'm making a serious attempt to read and understand the C-source which
> compiles to ruby.exe (at least the "core" part, if it has been identified as
> minimalist ruby). Is there any source code level documentation somewhere
> which can help me overcome the initial sense of being lost ;-)

IMHO the source code is quite understandable, the only complicated
files being regex.c and eval.c (where the actual evaluation of the
AST happens). For the other files, you always get a good guide at the
bottom, like

    rb_define_method(rb_cString, "initialize", rb_str_init, -1);
    rb_define_method(rb_cString, "copy_object", rb_str_replace, 1);
    rb_define_method(rb_cString, "<=>", rb_str_cmp_m, 1);
    rb_define_method(rb_cString, "==", rb_str_equal, 1);

This makes it extremely easy to quickly locate the source of a method
belonging to a core built-in class.

> If not, what do you gurus, who have mastered the terrain, suggest ? Is there
> a "best reading order" to the various C modules? Like where to begin, what
> may be skipped in the first pass, etc.

I'm not yet at guru level, so take my suggestions w/ a grain of salt
(OTOH, you might find them more valuable as I'm just a mere mortal and
know what things are difficult, instead of believing everything is
trivial :)

Ruby Core
 * dln.c: wraps dlopen or the equiv. function of your platform, not very
   interesting
 * gc.c: quite easy to follow, of interest only if you want to know how
    the GC works internally, but it's just mark & sweep doing "common
    sense" things so you can safely skip it. 
 * st.c: a hash table implementation used internally by Ruby, quite
   straightforward
 * eval.c: much harder to read as you have to know the node types to
   follow it; several functions are essentially a big switch() statement
   for a node
 * parse.y: this can help you see what different node types correspond
   to by having a look at the grammar.
 * regex.c: whatever, don't read it :-)

some other .c files contain only support code

Built-in classes
Take the class you like, scroll down to the Init_xxx() function and
locate the C function that implements the method you want to study. No
particular order required.

You (I :) will sometime want to read eval.c, but it's hard to follow on
first read. 

> Incidentally, when I compiled the 1.8.0 preview 2 on Windows (before
> downloading Andy's one click installer) it generated "minruby.exe" and I
> presume it is the "core" I mentioned earlier. Am I correct ?

IIRC it's used to process the extconf.rb files in the ext/ subdirectory.

-- 
 _           _                             
| |__   __ _| |_ ___ _ __ ___   __ _ _ __  
| '_ \ / _` | __/ __| '_ ` _ \ / _` | '_ \ 
| |_) | (_| | |_\__ \ | | | | | (_| | | | |
|_.__/ \__,_|\__|___/_| |_| |_|\__,_|_| |_|
	Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com

The documentation is in Japanese.  Good luck.
	-- Rich $alz