I’ve always had a love/hate relationship with Ruby’s C API. On the one
hand it’s extremely powerful and it allows you to expand Ruby’s reach in
the programming world. On the other hand, it’s terribly documented and
tasks that seem like they should be simple end up involving hours of
reading posts on this forum and dozens of Ruby blogs and delving through
the Ruby source.
Well I finally got sick of it. I spent the last week performing hundreds
of my own tests, aggregating information from forums and blogs and gems
and mailing lists and bug reports to produce what I call The Definitive
Guide To Ruby’s C API:
http://silverhammermba.github.io/emberb/
Notable topics (which I have found little to no documentation of
elsewhere) include:
- Using Ruby as a scripting language inside a C/C++ application
- Handling blocks when calling/defining methods
- Best practices for exception handling
- Working with the GVL using ruby/thread.h
- rb_scan_arg’s format string
- An HTML-ified version of README.EXT with a table of contents
- Tons of tiny little conveniences for making your C code simpler and
more maintainable
Bid differences from other guides I’ve read:
- This will get you up and running fast. We’re talking 10 minutes at
most to get some compiled code that makes API calls - It includes almost no function signatures, preferring instead
understandable examples demonstrating practical use. If you want
function signatures, you should read the ruby headers. - It’s organized as an introduction to the topic, attempting to
introduce sections of the API when they seem most relevant (rather than
giving a tedious rundown of every String function)
If you’ve ever tried and failed to get into working with the C API, I
would be honored if you give my guide a try. If you’re a C API pro, I
would doubly honored if you read it anyway and help me improve it.