Writing Ruby Extension Libraries: Steps for Implementing C Language Extensions and Ruby Calls

In Ruby, while most development work can be accomplished with pure Ruby code, there are times when we need higher performance or access to low-level system resources. In such cases, we can use C language to write extension libraries. This article will detail how to create a simple C extension and call it in Ruby.

Environment Setup

Ensure that the following tools are installed on your computer:

• Ruby development environment
• GCC compiler (for compiling C code)

You can check if these tools are installed by running the following command:

ruby -v
gcc --version

Creating Project Directory

First, create a new directory to store our project files:

mkdir ruby_c_extension_example
cd ruby_c_extension_example

Writing C Extension Code

In the project directory, create a file named <span>example.c</span> and add the following content:

#include "ruby.h"
// Define a method to return the sum of two integers
VALUE add(VALUE self, VALUE a, VALUE b) {
    return INT2NUM(NUM2INT(a) + NUM2INT(b));
}
// Initialize module and method
void Init_example() {
    VALUE MyModule = rb_define_module("MyModule");
    rb_define_method(MyModule, "add", add, 2);
}

Code Explanation

1. Including Header File: <span>#include "ruby.h"</span> is necessary as it provides the interface to the Ruby API.

2. Defining Method: <span>add</span> method takes two parameters and returns their sum. We use <span>NUM2INT</span> to convert Ruby numbers to C integers, and then use <span>INT2NUM</span> to convert the result back to a Ruby number.

3. Initialization Function: <span>Init_example()</span> is the entry point of the extension library. Here, we define a module <span>MyModule</span> and register the <span>add</span> method.

Creating extconf.rb File

To facilitate building our extension, we need to create a file named <span>extconf.rb</span> with the following content:

require 'mkmf'
create_makefile('example')

Code Explanation

• We use <span>mkmf</span> library, which is a tool for generating Makefiles.
• <span>create_makefile('example')</span> generates a Makefile based on our source files for subsequent compilation.

Compiling the Extension Library

Run the following command in the terminal to generate the Makefile and compile:

ruby extconf.rb
make

If everything goes well, you will see output similar to “compiling example.c”, indicating that your C extension is being successfully compiled.

Calling the Extension Library in Ruby

Now, we can call this newly created C extension in a Ruby script. Create a file named <span>test.rb</span> and add the following content:

require './example'
module_instance = MyModule.new 
result = module_instance.add(5, 10)
puts "The sum of 5 and 10 is: #{result}"

Code Explanation

1. Using <span>require './example'</span> to include the C extension we just wrote and compiled.

2. Create a module instance and call its method to add two numbers and print the result.

Testing the Program

Finally, run the test script in the terminal to see the output:

ruby test.rb

You should see the following output:

The sum of 5 and 10 is: 15

This indicates that our C extension example has been successfully loaded and is functioning correctly!

Conclusion

This article introduced how to build a simple Ruby and C topology from scratch, including how to set up the environment, write C source code, generate Makefiles, and finally how to call the topology in Ruby. This is just a basic way of interacting Ruby with C; real applications may involve more complex data structures and functionalities, but I hope this article helps you understand the foundational concepts and lays the groundwork for further learning.