Reading ruby source

ruby-talk
1

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 :wink:

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.

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 ?
Thanks,
– shanko

2

If you can accept the recommendation of someone with 10 minutes
experience, I’d suggest you open up array.c; skip to the bottom
where there’s a list of ‘rb_define_method’ which are instance
methods for Array; pick one that has a familiar outcome like …

rb_define_method(rb_cArray, “compact”, rb_ary_compact, 0);

… search for rb_ary_compact, ignore ‘rb_ary_compact_bang’ for
a moment and you’ll see that pretty soon one calls the other.
You can see the whole thing in a few lines. You’re not
debugging, so you can trust that whatever it calls is correct :slight_smile:

The chapter ‘Extending Ruby’ in the pickaxe tells about VALUE
(which, -incoming slap?- is a Ruby object) and some of the
INT2NUM etc. macros (What a fine book). Then pick another
method that you’re more interested in and try to avoid chasing
depth until you’re bored with the top level.

Good stuff.

Can’t answer your other bits. Whenever I try to compile
anything on Windows, I get an error message saying:-
“Go away, you idiot.” even though I’ve raked together every
Mingw, UNIXtool, Borland free compiler, DevC++ package that
I can; read about makefiles (yeeuch) and I call myself a
Systems Programmer. I never used to be this thick :((

Thanks for listening,

daz

···

“Shashank Date” sdate@everestkc.net wrote:

Is there a “best reading order” to the various C modules?
Like where to begin, what may be skipped in the first pass, etc.

3

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 :wink:

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 :slight_smile:

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 :slight_smile:

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 :slight_smile: 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.

···

On Fri, Jun 20, 2003 at 11:31:08AM +0900, Shashank Date wrote:

–
_ _

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

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

4

this is incredibly useful info - can we (you, i, somebody) create a wiki page
with the following format:

sourcea.c: definition
sourcebc: definition
…

then people can add to it at will and i could soon become a really valuable
resource.

perhaps http://www.rubygarden.org/ruby?RubyCore

??

-a

···

On Fri, 20 Jun 2003, Mauricio [iso-8859-1] Fernández wrote:

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 :slight_smile:

–

Ara Howard
NOAA Forecast Systems Laboratory
Information and Technology Services
Data Systems Group
R/FST 325 Broadway
Boulder, CO 80305-3328
Email: ara.t.howard@noaa.gov
Phone: 303-497-7238
Fax: 303-497-7259
~ > ruby -e ‘p(%.\x2d\x29…intern)’
====================================

5

“daz” dooby@d10.karoo.co.uk wrote in message

If you can accept the recommendation of someone with 10 minutes
experience, I’d suggest you open up array.c; skip to the bottom
where there’s a list of ‘rb_define_method’ which are instance
methods for Array; pick one that has a familiar outcome like …

rb_define_method(rb_cArray, “compact”, rb_ary_compact, 0);

… search for rb_ary_compact, ignore ‘rb_ary_compact_bang’ for
a moment and you’ll see that pretty soon one calls the other.
You can see the whole thing in a few lines.

Yes, I will definitely accept this recommendation because it makes sense.

[snip]

Whenever I try to compile anything on Windows, I get
an error message saying:-
“Go away, you idiot.” even though I’ve raked together every
Mingw, UNIXtool, Borland free compiler, DevC++ package that

I have used MSVC++ 6.0 and it works fine. No surprise there.

Thanks for listening,

Thanks for talking.

daz

– shanko

6

“Mauricio Fernández” batsman.geo@yahoo.com wrote in message

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).

And eval.c was the first file I tried to read … no wonder I was
overwhelmed.

[snip]

Well, you have made very good suggestions.

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 :slight_smile:

This is simply great !

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 :slight_smile: 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.

Thanks very much. This helps a lot !
– shanko

7

I prefer RubyInterpreterSourceCode, quite verbose but precise. And then
make a hierarchy (because everything in one page could be too big) w/

  • /Core
  • /BuiltinClasses

I’m adding this to the Wiki unless somebody complains here soon :slight_smile:

···

On Fri, Jun 20, 2003 at 10:55:20PM +0900, ahoward wrote:

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 :slight_smile:

this is incredibly useful info - can we (you, i, somebody) create a wiki page
with the following format:

sourcea.c: definition
sourcebc: definition
…

then people can add to it at will and i could soon become a really valuable
resource.

perhaps http://www.rubygarden.org/ruby?RubyCore

–
_ _

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

Thinking is dangerous. It leads to ideas.
– Seen on #Debian