Overview

Ruby has a C interface for defining extensions to the language. Using this interface, you define functions in C and add them as methods that are callable from ruby code. You may also define classes, modules, globals, and so on.

CGen is a library that makes it relatively easy to code, build, and load extensions from within a ruby program, rather than using a typical C development process. In this way, the construction of the extension is driven by the ruby program. The extension is also available for execution from the program. CGen is a kind of "inline" tool.

The CShadow module is for the special case of T_DATA objects, particularly those whose data is defined by a C struct. A class of such objects can be defined only through the ruby C API. Unlike normal ruby objects such as arrays and strings, a T_DATA object contains a "blob" of data that can only be accessed through methods defined in a C extension.

Including the CShadow module in a class lets you define the structure of the data blob by using simple attribute declarations (no C code needed). CShadow uses these declarations to generate the essential functions: accessors with type conversion and checking, mark/free, marshal, yaml, and initialization. Additional methods can be defined in ruby or using CGenerator. CShadow also manages inheritance of the structure from parent class to child class; the child class may define further attributes.

See the CGenerator, CShadow, and CShadow::Attribute pages for details.

Purpose and history

The intended use of cgen is managing a complex library that may change from one run of the program to the next. The reason for the change might be that the program is written in a DSL (domain-specific language), and that the library functions are generated based on the statements of the DSL.

In fact, the original use of cgen was to support a DSL for designing and simulating dynamic networks of hybrid automata.[RedShift, formerly hosted at redshift.sourceforge.net, now at http://rubyforge.org/projects/redshift]

Cgen was introduced in 2001 with this post:

http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/24443

Getting started

Installing

Cgen is available from http://rubyforge.org/projects/cgen.

Install either as gem:

gem install cgen

or from tarball, by unpacking and then:

ruby install.rb config ruby install.rb setup ruby install.rb install

System Requirements

Cgen is pure ruby, so you don't need a compiler to install it. However, you do need a C compiler to do anything useful with it.

On Unix and GNU/Linux, the gcc compiler works fine. The Sun C compiler has also been tested.

On Windows, you should use a compiler that is compatible with your ruby interpreter. The following compilers have been tested:

  • MSVC 6.0 (with the traditional one-click ruby installer--the OCI)
  • MSVC 2003
  • Mingw32 (gcc; the foundation of the new OCI by Luis Lavena)

Examples

The cgen package comes with a substantial examples directory, but it is not yet very well organized. Here are the best ones to start with:

sample.rb:: introduction to CGenerator

complex.rb:: introduction to CShadow

matrix.rb:: second example of CShadow

Web site

http://rubyforge.org/projects/cgen http://cgen.rubyforge.org/

License

Ruby license.

Author

Copyright 2001-2013, Joel VanderWerf, mailto:[email protected].