# The Definitive Guide To Ruby's C API

**URL:** <https://www.ruby-forum.com/t/the-definitive-guide-to-rubys-c-api/232903>\
**Category:** Ruby\
**Created:** [November 3, 2014, 7:18pm UTC](https://www.ruby-forum.com/t/the-definitive-guide-to-rubys-c-api/232903 "2014-11-03T19:18:54Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![addis\_a](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/a/c4cdca/32.png) [@addis\_a](https://www.ruby-forum.com/u/addis_a)\
**Post date:** [November 3, 2014, 7:18pm UTC](https://www.ruby-forum.com/t/the-definitive-guide-to-rubys-c-api/232903/1 "2014-11-03T19:18:54Z")

</div>

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/](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.

---

<div class="post-metadata">

**Author:** ![maxarchi](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/838e76/32.png) [@maxarchi](https://www.ruby-forum.com/u/maxarchi)\
**Post date:** [November 4, 2014, 6:59pm UTC](https://www.ruby-forum.com/t/the-definitive-guide-to-rubys-c-api/232903/2 "2014-11-04T18:59:53Z")

</div>

Thank you very much for the effort in making this guide. I’ll take a  
read later, thanks.