napi-rs

此项目是从 xray 初始化的。

一个用于通过 Node-API 在 Rust 中构建编译的 Node.js 插件框架。网站： https://napi.rs

平台支持

MSRV

Rust 1.65.0

此库依赖于 Node-API，并且需要 Node@10.0.0 或更高版本。

我们已经有了一些用 napi-rs 编写的包：node-rs

一个很好的特性是，这个crate允许您仅使用 Rust/JavaScript 工具链来构建插件，而不需要涉及 node-gyp。

尝试

您可以从 package-template 开始使用 napi-rs

定义JavaScript函数

/// import the preludes
use napi::bindgen_prelude::*;
use napi_derive::napi;

/// module registration is done by the runtime, no need to explicitly do it now.
#[napi]
fn fibonacci(n: u32) -> u32 {
  match n {
    1 | 2 => 1,
    _ => fibonacci(n - 1) + fibonacci(n - 2),
  }
}

/// use `Fn`, `FnMut` or `FnOnce` traits to defined JavaScript callbacks
/// the return type of callbacks can only be `Result`.
#[napi]
fn get_cwd<T: Fn(String) -> Result<()>>(callback: T) {
  callback(env::current_dir().unwrap().to_string_lossy().to_string()).unwrap();
}

/// or, define the callback signature in where clause
#[napi]
fn test_callback<T>(callback: T)
where T: Fn(String) -> Result<()>
{}

/// async fn, require `async` feature enabled.
/// [dependencies]
/// napi = {version="2", features=["async"]}
#[napi]
async fn read_file_async(path: String) -> Result<Buffer> {
  tokio::fs::read(path)
    .map(|r| match r {
      Ok(content) => Ok(content.into()),
      Err(e) => Err(Error::new(
        Status::GenericFailure,
        format!("failed to read file, {}", e),
      )),
    })
    .await
}

更多示例请参考 examples

构建

此存储库是一个 Cargo crate。任何基于 napi 的插件都应该包含 Cargo.toml 以使其成为 Cargo crate。

在您的 Cargo.toml 文件中，您需要将 crate-type 设置为 "cdylib"，这样 cargo 就会构建一个可以被 Node 可执行文件动态加载的 C 风格共享库。您还需要将此 crate 添加为依赖项。

[package]
name = "awesome"

[lib]
crate-type = ["cdylib"]

[dependencies]
napi = "2"
napi-derive = "2"

[build-dependencies]
napi-build = "1"

并在您的项目中创建 build.rs 文件。

// build.rs
extern crate napi_build;

fn main() {
  napi_build::setup();
}

到目前为止，napi 构建脚本仅在 macOS、Linux、Windows x64 MSVC 和 FreeBSD 上进行了测试。

安装 @napi-rs/cli 以帮助您构建 Rust 代码，并将 Dynamic lib 文件复制到 .node 文件，以便在您的程序中需要时使用。

{
  "package": "awesome-package",
  "devDependencies": {
    "@napi-rs/cli": "^1.0.0"
  },
  "napi": {
    "name": "jarvis" // <----------- Config the name of native addon, or the napi command will use the name of `Cargo.toml` for the binary file name.
  },
  "scripts": {
    "build": "napi build --release",
    "build:debug": "napi build"
  }
}

然后您就可以引入您的本地绑定

require('./jarvis.node')

module_name 应该是您的 Cargo.toml 中的包名。

xxx=> ./xxx.node

xxx-yyy=> ./xxx_yyy.node

您还可以将 Dynamic lib 文件复制到指定的位置

napi build [--release] ./dll
napi build [--release] ./artifacts

有关 @napi-rs/cli 的更多信息，请参阅 文档。

测试

由于依赖于此 crate 的库必须被加载到 Node 可执行文件中才能解析符号，因此所有测试都是在 test_module 子目录中用 JavaScript 编写的。

要运行测试

yarn build:test
yarn test

相关项目

• neon
• node-bindgen

特性表