From: Clemens.Hintze@...
Date: 1999-07-20T12:19:56+02:00
Subject: [ruby-talk:00509] Extension Tutorial?


Hi,

I have written a small Extension for learning purposes. Then I have
begun to write a README which describes my experiences to give a
startpoint for beginners like me.

But that was also the beginning of a very big fault! I have written and
written and my README has become a big monster. It is very diffus now,
and I am even not satisfied with the contents. So I think, I have no
other choice. I will discard my README, before it becomes so big, that
I cannot handle it anymore. :-(

Instead I intend to write a tutorial about writing Extensions for
Ruby. :-)

I have thought about the structure, and I want to show it to you and
beg you for comments. What do you think, about that structure? Have you
any additional ideas, that should be added?

As you will see, I intend my tutorial to have 5 lessons. For every
lesson there would be a subdirectory with working code.

What do you think, what kind of format I should write that tutorial? I
would like to use TeX, LaTeX or texinfo. Other ideas?

Thanks in advance,
\cle

PS: Please post your proposals on the list.

____________________________________________________________________________
And here comes the structure:

How to write Extensions for ruby
*Purpose of this tutorial
*What is the difference between `ruby' and `Ruby'?
*Why Extensions (or what are Extensions)?
     Explain what Extensions are and why it could be necessary to write them.
*Why do I write Extensions for ruby (and not for Python, Perl, etc.)?
     Explanation of my choice.
*Memory Management (MM) issues
**What are the problems with MM
     Explain the problems with MM in C. Why does interpreters try to prevent
     the programmer from MM issues?
**What is Garbage Collection (GC)?
**How to deal with Ruby's Garbage Collector?
*Some further background about Ruby.
     Explain that Ruby is "pure" OOL. All is class/methods.
*Here we go.
     Some intro. Explain how the lessons are structured.
**Proposal for a extension template.
     My Extensions are written using a template, so that they looks similar.
**1. Lesson - Wrapping a simple C function
     Here I wrap the C function `hypot' from the standard math library.
     Announce function with rb_define_global_function with argc == 2.
**2. Lesson - Wrapping some complex C functions
     I will wrap the functions `sscanf'.
     Announce the function rb_define_global_function with argc == -1.
     If it makes sense to explain how the function should handle arguments
     if it was announced with rb_define_global_function and argc == -2, I will
     wrap function sprintf too.
**3. Lesson - Wrap some C functions and datatype(s) as module
     I will wrap the functions: `time', `mktime', `localtime', `ctime' and
                                `asctime'
     I will silenty (means without explanation) wrap the datatype `struct tm`
     into a class `Struct_tm`, only for usage of the functions wrapped above.
     Here it is not necessary to understand how to define classes. That will
     be introduced in lesson 4.
**4. Lesson - Wrap some C functions and datatype(s) as class
     The same functionalities as in lesson 3. But this time it will be
     implemented as class with methods. Class `Struct_tm' will not be
     necessary anymore.
**5. Lesson - Create a new class which also contains Ruby objects
     I will create a class `Point' which will use Ruby's `Numeric' to describes
     the x and y coordinates. This to show, how to implement an own `mark'
     function for GC.