EXTENDING RUBY WITH C++ - A MINI-HOW-TO
Issac Trotts
<itrotts at idol minds dot com>
December 13, 2001

Attempting to create a Ruby extension using a C++ compiler
is likely to give you some unhelpful compile-time and link-time 
errors.  Here are some tips on how to get around them:

COMPILE-TIME

Use the following typedef to make the compiler stop complaining 
about the callbacks you hand to rb_define_method():

    // Use this typedef to make the compiler happy when
    // calling rb_define_method()
    typedef VALUE (ruby_method)(...);

    ...
    // notice the cast to ruby_method pointer here
    rb_define_method(cTest, "foo", (ruby_method*) &t_foo, 0);

LINK-TIME

The linker will say that it can't find various functions you've
defined.  This is because of C++'s name-mangling, which it uses
to do things like overloading functions.  If you don't know what
this means, don't worry.  All you have to do is put extern "C" 
in front of your function definitions, like this:

    extern "C" VALUE t_foo(VALUE self) { 
        //... 
    }

Surprisingly, 'extern "C"' means "Do not mangle the name of this
function."  In the long tradition of C/C++ obfuscation, 'extern "C"' 
does NOT mean "This function is written in the C programming language."
See _More Effective C++_ (Scott Meyers) Item 34 p. 270 for details.

A STEP-BY STEP EXAMPLE

1. Create a file named Test.cpp with the following contents:

    // BEGIN Test.cpp
    #include <ruby.h>
    #include <vector>
    #include <iostream>

    // Use this typedef to make the compiler happy when
    // calling rb_define_method()
    typedef VALUE (ruby_method)(...);

    extern "C" VALUE t_init(VALUE self)
    {
        VALUE arr;
        arr = rb_ary_new();
        rb_iv_set(self, "@arr", arr);

        return self;
    }

    extern "C" VALUE t_add(VALUE self, VALUE obj)
    {
        VALUE arr;
        arr = rb_iv_get(self, "@arr");
        rb_ary_push(arr, obj);
        return arr;
    }

    extern "C" VALUE t_foo(VALUE self)
    {
        // Make a vector of ints and print it out, just because
        // we can.
        std::vector<int> ii;
        for(int i=0; i<10; i++) { ii.push_back(i); }
        int k=0;
        std::vector<int>::iterator i2;
        std::cout<<"Executing foo on <"<<self<<">"<<std::endl;
        for(i2=ii.begin(); i2!=ii.end(); i2++) {
            std::cout<<"ii["<<k++<<"] = "<<*i2<<std::endl; 
        }
        return self;
    }


    VALUE cTest;

    extern "C" void Init_Test() 
    {
        cTest = rb_define_class("Test", rb_cObject);
        rb_define_method(cTest, "initialize", (ruby_method*) &t_init, /*n_args*/0);
        rb_define_method(cTest, "add", (ruby_method*) &t_add, 1);
        rb_define_method(cTest, "foo", (ruby_method*) &t_foo, 0);
    }
    // END Test.cpp

2. Create a file in the same directory called extconf.rb, with the following
   contents:

    require 'mkmf'
    if (/mswin32/ =~ PLATFORM)
        $CFLAGS+=" -GX "    # allow exceptions
    end
    create_makefile("Test")
        
3. ruby extconf.rb

4. invoke make or nmake

5. ruby -e 'require "Test"; t=Test.new; t.foo' 

WHEN ALL ELSE FAILS

Maybe it's time to convert that C++ code into some nice, clean Ruby.
A script called c++2rb is available to partially automate the process:

    http://www.angelfire.com/electronic2/issac/myrubyfiles.html

NOTES

- The code given here was tested using Ruby 1.7.2 [i586-mswin32] 
  and Microsoft Visual C++ 6.0 (a compiler with good optimization
  but poor support for the Standard Template Library.)