构建


编写源代码后,必须将其编译为二进制 addon.node 文件。 为此,请在项目的顶层创建名为 binding.gyp 的文件,使用类似 JSON 的格式描述模块的构建配置。 该文件由 node-gyp 使用,这是一个专门为编译 Node.js 插件而编写的工具。

{
  "targets": [
    {
      "target_name": "addon",
      "sources": [ "hello.cc" ]
    }
  ]
}

node-gyp 实用工具的一个版本作为 npm 的一部分与 Node.js 捆绑和分发。 此版本不直接提供给开发人员使用,仅旨在支持使用 npm install 命令编译和安装插件的能力。 希望直接使用 node-gyp 的开发人员可以使用命令 npm install -g node-gyp 安装它。 有关更多信息,包括特定于平台的要求,请参阅 node-gyp 安装说明

创建 binding.gyp 文件后,使用 node-gyp configure 为当前平台生成适当的项目构建文件。 这将在 build/ 目录中生成 Makefile(在 Unix 平台上)或 vcxproj 文件(在 Windows 上)。

接下来,调用 node-gyp build 命令生成编译后的 addon.node 文件。 这将被放入 build/Release/ 目录。

当使用 npm install 安装 Node.js 插件时,npm 使用它自己的 node-gyp 捆绑版本来执行相同的一组操作,按需为用户平台生成插件的编译版本。

构建完成后,可以通过将 require() 指向构建的 addon.node 模块在 Node.js 中使用二进制插件:

// hello.js
const addon = require('./build/Release/addon');

console.log(addon.hello());
// 打印: 'world'

因为编译的插件二进制文件的确切路径可能会因编译方式而异(即有时它可能在 ./build/Debug/ 中),插件可以使用绑定包来加载已编译的模块。

虽然 bindings 包实现在如何定位插件模块方面更为复杂,但它本质上使用了类似于以下内容的 try…catch 模式:

try {
  return require('./build/Release/addon.node');
} catch (err) {
  return require('./build/Debug/addon.node');
}

Once the source code has been written, it must be compiled into the binary addon.node file. To do so, create a file called binding.gyp in the top-level of the project describing the build configuration of the module using a JSON-like format. This file is used by node-gyp, a tool written specifically to compile Node.js addons.

{
  "targets": [
    {
      "target_name": "addon",
      "sources": [ "hello.cc" ]
    }
  ]
}

A version of the node-gyp utility is bundled and distributed with Node.js as part of npm. This version is not made directly available for developers to use and is intended only to support the ability to use the npm install command to compile and install addons. Developers who wish to use node-gyp directly can install it using the command npm install -g node-gyp. See the node-gyp installation instructions for more information, including platform-specific requirements.

Once the binding.gyp file has been created, use node-gyp configure to generate the appropriate project build files for the current platform. This will generate either a Makefile (on Unix platforms) or a vcxproj file (on Windows) in the build/ directory.

Next, invoke the node-gyp build command to generate the compiled addon.node file. This will be put into the build/Release/ directory.

When using npm install to install a Node.js addon, npm uses its own bundled version of node-gyp to perform this same set of actions, generating a compiled version of the addon for the user's platform on demand.

Once built, the binary addon can be used from within Node.js by pointing require() to the built addon.node module:

// hello.js
const addon = require('./build/Release/addon');

console.log(addon.hello());
// Prints: 'world'

Because the exact path to the compiled addon binary can vary depending on how it is compiled (i.e. sometimes it may be in ./build/Debug/), addons can use the bindings package to load the compiled module.

While the bindings package implementation is more sophisticated in how it locates addon modules, it is essentially using a try…catch pattern similar to:

try {
  return require('./build/Release/addon.node');
} catch (err) {
  return require('./build/Debug/addon.node');
}