We know that node.js is run by V8 engine just like in Chrome. V8 is a JavaScript engine written in C++. So built-in functions in node.js is actually written in C++ and provided by some binding logic. This techinque is open in node.js. So we could write our own business logic in C++ and use the same binding logic and call the code in JavaScript. This is called C++ addons.
Below code I copy from node.js C++ addons document, which shows a simple C++ addon.
// hello.cc
#include <node.h>
namespace demo {
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;
void Method(const FunctionCallbackInfo<Value>& args) {
Isolate* isolate = args.GetIsolate();
args.GetReturnValue().Set(String::NewFromUtf8(
isolate, "world").ToLocalChecked());
}
void Initialize(Local<Object> exports) {
NODE_SET_METHOD(exports, "hello", Method);
}
NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)
} // namespace demo
As you can see, inside the code, the v8 functions are used. Becuase the v8 apis are changed constantly, there is another package called Node-API, which provides a wrapper to make this addons development more easily. Below code shows what node-api for addons looks like.
#include <assert.h>
#include <node_api.h>
static napi_value Method(napi_env env, napi_callback_info info) {
napi_status status;
napi_value world;
status = napi_create_string_utf8(env, "world", 5, &world);
assert(status == napi_ok);
return world;
}
#define DECLARE_NAPI_METHOD(name, func) { name, 0, func, 0, 0, 0, napi_default, 0 }
static napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor desc = DECLARE_NAPI_METHOD("hello", Method);
status = napi_define_properties(env, exports, 1, &desc);
assert(status == napi_ok);
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
As you can see, this code use the header file <node_api.h>, instead of <node.h>.
Now we know the basic concept of adddons, let walk through a simple hello world example.
First, prepare some basic tools. In mac or linux, check if these tools are installed properly.
node --version
npm --version
python --version
git --version
cc --version
make --version
Then create a simple package first.
npm init -y
Inside package.json files, change the content as below.
{
"name": "hello",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "node index.js"
},
"keywords": [],
"author": "",
"license": "ISC",
"gypfile": true
}
As you can see, the most important thing is to set gypfile: true. With this key enabled, later npm install command will try to find the binding.gyp file and use node-gyp tool to compile the project.
Now let's write the binding.gyp file, which is a config file for compiling C++ code into C++ addons.
{
"targets": [
{
"target_name": "hello",
"sources": [ "hello.c" ]
}
]
}
The target_name key is the name of the package. Later we can use this name to require the addon. The sources key contains the C++ code files needed to be compiled.
Next, let write the C++ code using the node api.
#include <assert.h>
#include <node_api.h>
// this is the real method to be called
static napi_value Method(napi_env env, napi_callback_info info) {
napi_status status;
napi_value world;
status = napi_create_string_utf8(env, "world", 5, &world);
assert(status == napi_ok);
return world;
}
#define DECLARE_NAPI_METHOD(name, func) { name, 0, func, 0, 0, 0, napi_default, 0 }
static napi_value Init(napi_env env, napi_value exports) {
napi_status status;
// this defines the method binding
napi_property_descriptor desc = DECLARE_NAPI_METHOD("hello", Method);
status = napi_define_properties(env, exports, 1, &desc);
assert(status == napi_ok);
return exports;
}
// NODE_GYP_MODULE_NAME is the target_name in the binding.gpy file
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
OK, now we have all basic stuff for this addon, let compile the code.
% npm install
> hello@1.0.0 install
> node-gyp rebuild
gyp info it worked if it ends with ok
gyp info using node-gyp@9.0.0
gyp info using node@16.17.0 | darwin | arm64
gyp info find Python using Python version 3.8.9 found at "/Library/Developer/CommandLineTools/usr/bin/python3"
gyp info spawn /Library/Developer/CommandLineTools/usr/bin/python3
gyp info spawn args [
gyp info spawn args '/Users/yao/.nvm/versions/node/v16.17.0/lib/node_modules/npm/node_modules/node-gyp/gyp/gyp_main.py',
gyp info spawn args 'binding.gyp',
gyp info spawn args '-f',
gyp info spawn args 'make',
gyp info spawn args '-I',
gyp info spawn args '/Users/yao/Documents/GitHub/demos/todo/c++-addon/hello/build/config.gypi',
gyp info spawn args '-I',
gyp info spawn args '/Users/yao/.nvm/versions/node/v16.17.0/lib/node_modules/npm/node_modules/node-gyp/addon.gypi',
gyp info spawn args '-I',
gyp info spawn args '/Users/yao/Library/Caches/node-gyp/16.17.0/include/node/common.gypi',
gyp info spawn args '-Dlibrary=shared_library',
gyp info spawn args '-Dvisibility=default',
gyp info spawn args '-Dnode_root_dir=/Users/yao/Library/Caches/node-gyp/16.17.0',
gyp info spawn args '-Dnode_gyp_dir=/Users/yao/.nvm/versions/node/v16.17.0/lib/node_modules/npm/node_modules/node-gyp',
gyp info spawn args '-Dnode_lib_file=/Users/yao/Library/Caches/node-gyp/16.17.0/<(target_arch)/node.lib',
gyp info spawn args '-Dmodule_root_dir=/Users/yao/Documents/GitHub/demos/todo/c++-addon/hello',
gyp info spawn args '-Dnode_engine=v8',
gyp info spawn args '--depth=.',
gyp info spawn args '--no-parallel',
gyp info spawn args '--generator-output',
gyp info spawn args 'build',
gyp info spawn args '-Goutput_dir=.'
gyp info spawn args ]
gyp info spawn make
gyp info spawn args [ 'BUILDTYPE=Release', '-C', 'build' ]
CC(target) Release/obj.target/hello/hello.o
SOLINK_MODULE(target) Release/hello.node
gyp info ok
up to date, audited 1 package in 350ms
found 0 vulnerabilities
If everything runs ok, a build folder should be generated and the ./build/Release/hello.node file is the real addon.
Now let's try to require this addon and call the method we defined.
var addon = require('./build/Release/hello.node');
console.log(addon.hello()); // 'world'
Run the test.
% npm run test
> hello@1.0.0 test
> node index.js
world
OK, this is the basic process about writing an C++ addon. If you want to know more, check this repository node-addon-examples.