There comes a time in every Javascript developer’s life when Javascript just won’t do what they want. At this time, they have but one place to turn: native addons, usually in C and C++.
Native addons scare many people, myself included, since usually the only time we realize they exist is when they fail to compile or give a segmentation fault. Recently I had the chance to do some major work on an existing C addon that had been abandoned, so I spent some time struggling through the process of learning all about it and bring it back to life.
While I wouldn’t say writing a C addon is easy, I would encourage anyone to give it a try. The major challenge is mostly the fact that you have to learn so many different things.
More interestingly, while its true that the quality of documentation in the open source world is often lacking, being thrust back into the world of C has reminded me how good (relatively) we have it in the Javascript and Ruby world. We have some great folks that really care about other developers, and have spent the time and effort to write great documentation that helps guide people through the entire process. This doesn’t seem to happen too much in the C world.
While I couldn’t write a book on C addons, I can at least give an overview of what you need to learn, as well as some helpful tips and useful websites.
The Big Stuff
Again, the hardest part of writing an addon is not any part of the process itself, but that there are quite a few pieces in play, so there’s a lot to learn. In any situation like this, it’s often helpful to start with the fundamental things and work up.
C++
Node.js is built on V8, the Javascript interpreter from Google. V8 (and therefore Node.js) is written in C++, so if you haven’t already set up everything you need to write and compile C++, it’s probably best to start here. It’s been a long time since I’ve learned C++, so I don’t know of a good basic tutorial, but if anyone knows of say, a blog post that brings you from a new Ubuntu or OSX install to having compiled an run a basic C++ program, I’d love to link to it.
V8
V8 is an open source project, and it has decent getting started documentation, but not much after that. The best place to start is the introduction page. Read through every page on the sidebar to the left. This will start with walking you through downloading and building V8 from source, then explain some basic concepts, and finally show you a couple simple examples. You won’t need to build V8 from source to work with Node.js, but the process should be educational, and will help make sure your machine is fully set up with all the dependencies you’ll need. Having V8 set up to run and experiment with those simple examples could also help if you need a place to really focus on V8 without the added complexities of Node.js. Note that you’ll probably want a nice internet connection for this part: installing V8 requires using a bunch of Big Google Tools. They’re a little tedious, but not difficult, to set up. It does download a lot of data though.
One painful part of working with V8 is that the interface seems to change a lot. Fortunately I found a Google doc (of course), that contains an up to date API change log.
Later, when you are inevitably running into issues compiling some code written for an older version
of V8, you can probably ctrl+f in this document to search for the stubborn keyword, and find
what to use instead.
After the initial tutorials, V8 seems to have little in the way of intermediate documentation. It jumps abruptly to some auto-generated reference docs generated by Doxygen. I generally hate these sorts of docs: while they cover everything, they usually don’t cover anything very well, and don’t do a lot of explaining. You have to know what to search for and figure out how to use it. You don’t learn how to drive by taking apart a car
That said, you will certainly be using these docs all the time. I found myself keeping permanent tabs of the Local, Persistent and, of course, String class pages. You don’t know what these mean yet, but you will. Oh yes, you will.
Speaking of strings, you’ll probably be working with them a lot. Both V8 and C++ have their own String class. Converting between the two needs to happen sometimes, and this StackOverflow answer shows you how.
Node.js
Learning what V8 is, and that Node.js uses it probably helps Node.js make a lot more sense. What is Node.js? It’s Javascript, but with a bunch of extra stuff like an asynchronous interface, streams, and a bunch of other helpful things.
Now you know the Javascript part comes from V8. The rest of this stuff comes from the Node.js code itself.
Node.js native addons are how you add more stuff to Node.js. As you might now expect, this means
you’ll be writing C or C++ that works with code for Node.js as well as V8. V8 has a tool to help
with compiling things called GYP. Node.js has a tool to help with compiling things called
node-gyp. It comes packaged with Node.js, but apparently you’re supposed to also install it
globally with something like sudo npm install -g node-gyp.
Once node-gyp is installed you can start compiling Node.js modules. The best way to start that
I’ve found is to look at the great examples in the
node-addon-examples repository. It includes some
basic and some more complex examples of all the common things you’ll do. Each example includes three
versions: one that works with Node.js 0.10, one that works with Node.js 0.12 (and above), and one
written with Nan that should work anywhere. Don’t worry about the Nan one’s yet, we’ll cover that
later. Having both the 0.10 and 0.12 versions is invaluable when you’re working with old code that
you want to rewrite to work on newer versions of Node.
Sometimes you want real examples too. node-microtime might be the best place to start. It’s about as simple as a Node addon can get (just one system call), but because it actually does something, you know everything it’s doing is done for a reason. Examples can sometimes hurt more than they help, since they can be designed to show off esoteric parts of the interface, rather than actually accomplish something in an easy to read way.
Nan
Nan is another library to help make your Node addon work across different versions of Node.js and V8. The first time you wirte a Node addon, you probably don’t want to use it: it’s yet another layer of things to learn. Every time after that though, you do. There’s no sense in redoing all the work to support different Node versions, when some nice folks from the internet have already done it for you.
Unlike V8, Nan has great docs built right into their readme. They also have a cool example that also teaches you a bit about Pi and Monte Carlo estimation methods.
Again, real modules can also serve as documentation. Here’s a giant pull request that converts node-taglib to use Nan.
TODO
https://github.com/nikhilm/uvbook https://github.com/kkaefer/node-cpp-modules http://blog.scottfrees.com/c-processing-from-node-js-part-4-asynchronous-addons