作者：王舒源

本文预计阅读时长约为 20min

本文为公司内部的分享，部分内容是 live coding 现场编写，需要参考代码示例

完整的代码示例可以在这里找到

前言

对于 NAPI-RS 来说，大家一定已经不陌生了。和 Neon，WASM-Bindgen 相同，它们均是用来生成对于某种 Binding 的工具库，前者 Neon 和 NAPI-RS 基本是同类产品，用于生成和 Node 的 Binding。

Binding 是什么？

这里的 binding 等价于 Language binding，摘录一段维基百科中的描述：

In programming and software design, binding is an application programming interface (API) that provides glue code specifically made to allow a programming language to use a foreign library or operating system service (one that is not native to that language). From Wikipedia

大部分同类型的工具的架构都比较类似，对于 NAPI-RS 来说是这样的：

NAPI-SYS：NAPI 的 SYS crate，负责和 Node 通信。社区上通常使用 *-sys 命名这些底层调用的库。
NAPI: NAPI crate 则是对 NAPI-SYS 库的上层封装。由于 Sys crate 通常是原生的底层 API，因此基本所有原生库都会存在一个对语言友好的封装，进而降低用户的使用成本与代码的准确性。

为什么 Sys crate 通常和 Wrapper crate 分开存在？

对于 Sys crate 来说，它们的工作是和底层的 lib 相绑定，API 的变化通常不会那么频繁，而对于 wrapper 层来说它们是极易产生 breaking change 的。当 Sys 和 Wrapper 放在同一个 crate 中则非常容易产生 breaking change，如此时进行大版本升级，则可能会导致项目中单独使用 Sys crate 的 Dependency（无论是间接，还是直接）们都需要进行升级，因此这是不合理的。详情见 Semver Compatability

NAPI Macro 与 NAPI Macro backend：通常为使用 NAPI 的 Rust API 在编译时生成相关模板代码，解放用户的双手。如 NAPI Macro 还做了一些 TS 类型生成的工作。

对于上层的 crate 我们不会在本篇中做过多的介绍，对于它们来说，更多的重心则是放在“怎么让用户降低开发成本”（例如是基于 Macro 的编译时生成模板代码、对 Promise 类型的封装使得它能够对接 Rust Future等）与“怎么让用户的代码变得更加的安全”（例如：对于某些 Opaque 类型的上层封装）上。

本篇，我们会将更多的目光聚焦于 Sys crate 和 Node 的通信上，因为这是 NAPI 的本质。

总结成一句话来说：NAPI-SYS 和 Node 的通信是建立在 C ABI 之上的 FFI 的调用。

C ABI ?

看到这里，有些人可能会对这个概念有一些歧义，我们将会在下方做进一步解释。

我们会以一个简单的 NAPI-SYS crate 的实现作为结束。同时为了让整体的衔接不至于太过僵硬，下方会使用另外一个案例进行具体分析。那么，接下来让我们详细展开。

Build Script ｜文档

从编译的角度来看，当一个 Package 被编译时，Cargo 会首先编译这个 build script，再进行后续的编译操作。你可以认为 Build Script 只是另一个 Package，并在当前的 Package 编译前先进行了编译。事实上确实如此，我们能在 Target 中找到两组产物，其中一组便是 Build script 的产物。

从事务的角度出发，Build Script 对于 Sys crate 来说，一般会做一些源码编译、lib 搜索相关的事务，而对于 Turbopack 来说，则是进行了注册、代码生成相关的事项。总之，尽管它被叫做 build script，而现实世界中，理论上你可以用来对他做任何事情，甚至是发送一个 HTTP 请求或做一些危及计算机安全的事情，Rust 的 Secure code team 还为此发起了相关是否要做 Build-time Sandbox 的*讨论* 。

默认情况下，你可以直接在 Package 的根目录中生成一个带有 fn main 的 build.rs 来作为 build script：

// build.rs
fn main() {
 
}

如果在 build script 的执行过程中发生了 panic，则不会对该 Package 进行后续的编译流程。

值得注意的是，在 build script 中的一切 print 操作是不会被打印到 stdio 上的

// build.rs
fn main() {
 println!("hello from build.rs"); // 没有用
}

对于 print 来说，你可以在产物文件夹下 output 文件中找到对应的输出，对于 dbg! 的相关输出则可以在产物文件夹中的 stderr 文件中找到（这个 macro 的本质是 stderr 的 output）

对于为什么不对 print 相关的内容进行控制台的输出，*官方*给出的理由是不想制造更多的噪音。因为我们在 build script 中还有一件大事可以做，那就是调用 print 生成 Cargo Instructions

Cargo Instructions | 文档

这里列举一些常用的 Instructions:

cargo:rerun-if-changed=PATH — Tells Cargo when to re-run the script.
cargo:rustc-link-arg=FLAG — Passes custom flags to a linker for benchmarks, binaries, cdylib crates, examples, and tests.
cargo:rustc-link-lib=LIB — Adds a library to link.
cargo:rustc-link-search=[KIND=]PATH — Adds to the library search path.
cargo:rustc-cfg=KEY[="VALUE"] — Enables compile-time cfg settings.
cargo:rustc-cdylib-link-arg=FLAG — Passes custom flags to a linker for cdylib crates.

除此之外，我们通常也会在 build script 中获取相关 env 字段，常见的有 OUT_DIR，CARGO_FEATURE_XXX 等等，这些都可以通过 std::env::var 获得，如果你希望忽略 UTF-8 的校验，则可以用性能更好的 std::env::var_os 达到几乎相同的效果。

这些都是日常开发上基本会用到的相关内容，在这之上，对于一个 Sys crate 的编译来说，我们通常会对本机的 lib 进行查找，从而引导 rustc 完成对该 lib 的 linking。

Pattern

暂时无法在飞书文档外展示此内容

通常情况下，我们会在一个版本号区间内查找系统中存在的 lib 包，如果不存在则进行基于源码的构建。

这里我们可以以 libgit2 作为参考，就不在本文中详细展开了。

Foreign Function Interface (FFI)

A foreign function interface (FFI) is a mechani** by which a program written in one programming language can call routines or make use of services written in another. From Wikepedia

FFI 可以让跨语言的程序之间完成相互的调用。就像 IPC(Inter-process communication)一样需要建立一套 protocol，FFI 同样也是一种满足了约定的规则(如：Calling conventions 等, ABI)的调用，Rust 支持的 ABI 可以在这里找到。由于 C 的 ABI 在同一个平台上是兼容的，因此大部分库都是建立在 C ABI 上的。

ABI 和 C ABI?

ABI(Application Binary Interface) 和 API(Application Programming Interface)非常相似，前者描述了 Binary 的兼容性，这其中包括了各种数据类型的 size 和 alignment、内存布局（Layout）以及系统的调用约定（用来描述例如参数是怎么被传递的等等，例如：x86 calling conventions），甚至包括了 Compiler 等等之间的一致性（Conformance）等等。更多

在 C 的标准中，其实是没有对 C ABI 标准的定义的。但对于同一个平台，这些基本是可以被认为是一致的，因此我们基本可以认为它们是兼容的。而对于不同的平台来说，它们系统之间的调用约定可能是不一致的，因此我们认为它们是不兼容的。所以我们在描述 C ABI 的兼容性时，都包涵了一个隐式约定：同一平台

FFI

在 Rust 中我们可以这样来声明，extern “abi”：如 extern “C”

extern "C" {
  fn napi_create_object(...)
}

我们不需要手动定义 unsafe，因为 FFI 的调用永远是 unsafe 的。

Reverse FFI

同样的，我们也可以定义对应的 fn 给其他支持该 ABI 的语言调用：

#[no_mangle]
pub extern "C" fn napi_register_module_v1(...) {
  // ...
}

需要注意的是，我们需要添加 no_mangle 的标记。否则对应的 symbol name 会被 mangle，而导致调用方无法寻址。你可以使用 nm 命令验证这一点：

$ nm <path/to/generated-binary> | grep napi

macOS 下 symbol 会带有一个下划线，可以看到_napi_register_module_v1 被包含在 Symbol table 中：

0000000000001650 T _napi_register_module_v1

FFI Safety

有了 ABI 的限制，我们可以得到：只有有限的值类型才可以完成跨 FFI 边界的值传递（通信），就像 IPC protocol 也有特定的数据结构的要求，那么，常用的 C ABI 也是一样，简单来说，C 里面无法表达的数据结构，你就不能通过 FFI 这条 Boundary，同样的对于 Rust 的 Error 也是无法通过 FFI 边界的，etc。

要标记一个值为 C ABI Compatible，可以使用 #[repr(C)]，这会让 rustc 开启对应的编译时检查，确保这个类型是 FFI Safe 的：

#[repr(C)]
struct some_data_type {
  foo: [u8;0],
  bar: usize
}

C的范式还限制了 enum 的传递，但可以用 #[repr(u32, i8, etc..)] and #[repr(C)] 来强制将非 C 范式的 enum 拥有特定的 Memory Layout，因此下面两种类型是可以互相 Interop 的：

#[repr(u8)]
pub enum LineStyle {
    Solid,
    Dotted,
    Dashed,
}

enum class LineStyle: uint8_t {
    Solid,
    Dotted,
    Dashed,
}

更多的信息可以在这里找到

Opaque Type

在 FFI 的交互过程中，有很多值是不希望被访问到其实际内容的。对于熟悉 NAPI 可能了解过 External 类型，它是一个 Opaque Type，这个 Opaque Type 将会通过 FFI 调用获取到，再通过 FFI 作为参数进行传递：

napi_status napi_create_external(napi_env env,
                                 void* data, // 需要包裹的值
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result) // 生成的 JS 类型 External Type
                                 
napi_status napi_get_value_external(napi_env env,
                                    napi_value value, // 这个 JS ExternalType
                                    void** result) // 获取到这个值之前被包裹的 Data

得到这两组定义后，我们可以将 data 包裹成一个值做为标志存储在 JS 侧，而 JS 侧是无法感知到内部的数据结构的，一个实际的例子可以参考 NAPI-RS External Type

同样的，我们在 Rust 中也可以定义相关的 Opaque Type：

#[repr(C)]
struct foo_opaque {
 _data: [u8;0],
 _marker: PhantomData<*mut ()> // 标记这个 struct 为 !Send 和 !Sync 的
}

#[no_mangle]
extern "C" fn some_init_function(foo: *const foo_opaque) {
}

这样一来，上述的例子中，在其他语言调用它的时候，你仅能拿到 foo 的指针。

另一个 Opaque Type 的好处在于可以完成类型的区分，我们知道在 C 中，一切任意 Type 的 pointer 都可以用 void 来定义，这在 Rust 中的表示是这样的：

extern "C" fn some_init_function(foo: *const ::std::os::raw::c_void, 
                                 bar: *const ::std::os::raw::c_void) {
  do_something_with_bar(foo); // 可以编译！                                 
}

但当两个 pointer 均为 c_void 时，则无法区分，也就丢失了 rustc 编译时的类型检查，这是我们希望能够避免的。

写一个 *-sys crate

在这一章节，我们将用 libsodium 作为案例编写一个 libsodium-sys，使其能够完成简单的 hasher 的功能。这个 Demo 中将直接使用 rust-bindgen **完成 binding 的生成。 **由于篇幅的关系，我们将不涉及 vendor 时的“从源码构建”。

准备工作

首先需要安装 libsodium

# 通过 brew 安装
$ brew install libsodium

# 通过其他方式进行安装 https://libsodium.gitbook.io/doc/installation

安装完成后可以通过命令验证是否成功：

$ pkg-config --libs libsodium

新建一个 libsodium-sys

Cargo.toml:

[package]
edition = "2021"
name = "libsodium-sys"
version = "0.1.0"

[build-dependencies]
pkg-config = "0.3.1"
bindgen = "0.63.0"

我们通过 pkg-config 查找系统依赖，它可以自动设置 rustc 依赖的参数
bindgen 用于基于 libsodium 的 header 生成 FFI Binding

定义 wrapper.h

#include "sodium.h"

我们将需要的 header 文件 sodium.h 添加到 wrapper.h，rust-bindgen 将会编译生成 FFI 声明

编写 build script

fn main() {
  // 通过 pkg_config 查找 syslib
  let lib = pkg_config::Config::new()
        .atleast_version("1.0.18")
        .probe("libsodium")
        .unwrap();
        
  println!("cargo:rerun-if-changed=wrapper.h");
  
  // The bindgen::Builder is the main entry point
  // to bindgen, and lets you build up options for
  // the resulting bindings.
  let bindings = bindgen::Builder::default()
    // The input header we would like to generate
    // bindings for.
    .header("wrapper.h")
    .clang_args(
        lib.include_paths
            .iter()
            .map(|p| format!("-I{}", p.display())),
     )
    .allowlist_function("crypto_generichash")
    .allowlist_function("sodium_init")
    .allowlist_var("crypto_generichash_.*")
    // Tell cargo to invalidate the built crate whenever any of the
    // included header files changed.
    .parse_callbacks(Box::new(bindgen::CargoCallbacks))
    // Finish the builder and generate the bindings.
    .generate()
    // Unwrap the Result and panic on failure.
    .expect("Unable to generate bindings");

  // Write the bindings to the $OUT_DIR/bindings.rs file.
  let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
  bindings
    .write_to_file(out_path.join("bindings.rs"))
    .expect("Couldn't write bindings!");
}

我们通过 pkg-config 查找并 set rustc flags，将 include_paths 添加到 bindgen 的 clang_args 参数
同时当 wrapper.h 变化时，我们需要重新执行 build script
allow_list 中添加本次 DEMO 需要用到的 fn, const
最终的 bindings.rs 我们可以在 OUT_DIR 中找到，它是这样的：

编写 binding 并测试

我们可以通过 libsodium 官网的 FFI 定义了解各个字段的作用：Generic hashing

#![allow(unused)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]

mod ffi {
  // 内联 bindings.rs 的 codegen 的结果到 mod ffi
  include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}

pub use ffi::*;

测试部分可以参考

Tips

可以使用 pkg-config crate 进行 libs 的查找，查询成功后会自动添加相应的 cargo instructions，省去了手动添加
使用 Bindgen 生成的代码是一个“大杂烩”，可以限制导出的内容，如：使用 allowlist 等
不建议在 sys crate 中编写除 ffi 声明以外的逻辑，避免 breaking change
可以通过 cargo instructions 暴露相关的 metadata 给依赖方，以保持如全局的 lib 版本统一

写一个简单的 `napi-sys`

在这一章节，我们将创建一个 dynamic library 并调用 napi 完成简单的注册，添加模块导出等功能，并在 Node 中进行测试。

准备工作

我们将会新建两个 crate，第一个 crate 为 napi-sys 用于声明一些 Node 给我们提供的 FFI，完整的 FFI 列表可以参考 N-API 文档。其次，我们将会创建第二个 crate NAPI 用于编写 binding 的测试。

用到的 FFI :

napi_create_string_utf8

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result)

napi_set_named_property

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value);

用到的 Reverse FFI :

由于当前插件为 dynamic library，我们需要在 crate NAPI 中导出注册的钩子，用于在运行时完成 Module 的注册：

napi_register_module_v1：现在 Register 的版本号为 1，可以参考这里

napi_value napi_register_module_v1(napi_env env,
                                   napi_value exports)

用到的返回值：

napi_status: NAPI 调用成功与否，0 为成功

我们需要在 Rust 侧创建一个 named export，它的 key 为 foo，值为 bar，最终的效果是这样的：

const foo = require("./binding.node").foo;
console.log(foo) // bar

[live-coding]

完整的代码示例：https://github.com/h-a-n-a/build-script-ffi-and-napi

可能遇到的问题

在 Clang(macOS 默认) 中你需要使用 -undefined, dynamic_lookup 来标记 linker symbol 查找的行为（在 Runtime 中查找，-C 表示 codegen flags），否则会产生找不到 Symbol 的编译报错：

[target.x86_64-apple-darwin]
rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
]

[target.aarch64-apple-darwin]
rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
]

图 1.1： LLVM 架构图 https://blog.gopheracademy.com/advent-2018/llvm-ir-and-go/

图 1.2: Linker **https://en.wikipedia.org/wiki/Linker_(computing)

Linker 有什么用?

编译器的架构：Frontend(C -> Clang) -> LLVM Optimizer -> LLVM Backend（图1.1）

Linker 的作用(图 1.2)

由于我们希望生成的是一个基于 C ABI 的 dynamic library，因此需要在 cargo.toml 中标记：

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

Tips

可以用 nm 查看 binary 中的 Symbol，如：

                 U _napi_create_string_utf8
00000000000015b0 T _napi_register_module_v1
                 U _napi_set_named_property

T 代表 Global text symbol

U 代表 Undefined symbol，这正是我们期望的，它将会在宿主环境中提供，例如我们可以简单验证 node 中是否定义了 napi_create_string_utf8：

$ nm $(which node) | grep napi_create_string_utf8

我们便能得到对应的 FFI 定义

0000000100087c00 T _napi_create_string_utf8

FFI 的定义和声明的区别是什么？

在上述例子中，我们的 napi-sys crate 仅仅完成了 FFI 的声明，就好比你直接引用了 napi 的 header file，而只有在对应 Node binary 中定义了这些 FFI 后你才能使用。这也是为什么 FFI 永远是 unsafe 的原因之一

可以用 file 查看文件的类型，如：

file binding.node

我们可以得到这是一个 x86_64-apple-darwin（通过 Apple iMac 3.8 GHz 8-Core Intel Core i7 编译）的 shared library：

binding.node: Mach-O 64-bit dynamically linked shared library x86_64

交叉编译

通常情况而言，一个平台只能编译出当前平台支持的可执行代码，而交叉编译则是想解决跨平台编译的问题。如在 M1(aarch64-apple-darwin) 上编译出 x86_64-linux-gnu 的代码（每一种 compiler 的 triple 写法都不太一样，这里列举了 Rust 的）。Rust 提供了开箱即用的 cross-compilation 支持，你只需要安装 target 对应的 toolchain 即可：

$ rustup target add x86_64-unknown-linux-gnu

然后使用 Cargo build --target 进行编译：

$ cargo build --target x86_64-unknown-linux-gnu

对于编译一个项目来说，仅仅支持不同 target 的标准库是大概率不够用的，对于不同的 target 你也许需要使用不同的 Linker 等，这些都可以在 .cargo/config.toml 文件中定义，详细内容可以参考 The Cargo Book。大致的设置是这样的：

[target.x86_64-unknown-linux-gnu]
linker = "x86_64-unknown-linux-gnu-gcc"

Linux 的一些 C 标准库

GNU (glibc)
Musl

对于 gnu 输出的一般是动态链接的 binary，需要在使用方的电脑上安装 glibc。而 musl 则是静态链接（你可以认为就是一个 Tree-shaked 过的 Bundle）的，Bundle 的体积会变大一些，但优势在于它不需要任何的 Dependency。

你会发现，如果我们需要 cross-compile 多个平台，则需要完成多个平台的参数的调优（不同的 Compiler 的参数还不太一样），这让人非常头疼。这个时候，Zig cc 可以非常好地帮助我们解决这一系列问题。

Zig

从语言的角度看，Zig 是一个非常轻量级的静态语言，它没有Macro 等等。除此之外，它提供了非常好的 C Interoperability，你甚至可以直接 include 一个 C 的 header。除此之外它还是一个 C/C++ Compiler，底层调用的是 Clang，令人吃惊的是它竟然兼容了 Clang 和 gcc 的编译参数！从原理上来说，它承担了和 Clang 沟通的角色，截获部分需要的指令，如 --target 等，加以处理后交给 Clang 进行后续的编译流程，如：

$ zig cc -target x86_64-linux-gnu ...
⬇️
$ clang xxx

那么如何将 Zig 应用到我们的工作流上呢？首先在任意位置创建一个 zcc 的文件（Zig cc），如：

#!/bin/sh
zig cc -target x86_64-linux-gnu $@

在对应的 .cargo/config.toml 中完成对 linker 的设置：

[target.x86_64-unknown-linux-gnu]
linker = "path/to/zcc"

调用 Cargo build 即可：

$ cargo build --target x86_64-unknown-linux-gnu

测试

如果需要对 binding 进行测试，建议还是 follow docker。推荐所有大型项目，能不用交叉编译就不用，因为最后它们均要完成在各个平台上的测试，以验证编译后的产物的正确性。

Reference

Build Script

https://doc.rust-lang.org/cargo/reference/build-scripts.html

FFI

https://www.youtube.com/watch?v=pePqWoTnSmQ

https://doc.rust-lang.org/nightly/nomicon/other-reprs.html#reprc

https://doc.rust-lang.org/nightly/nomicon/ffi.html#representing-opaque-structs

http://nickdesaulniers.github.io/blog/2016/08/13/object-files-and-symbols/

交叉编译

https://actually.fyi/posts/zig-makes-rust-cross-compilation-just-work/

https://doc.rust-lang.org/cargo/reference/config.html#target

https://rustc-dev-guide.rust-lang.org/backend/codegen.html

https://andrewkelley.me/post/zig-cc-powerful-drop-in-replacement-gcc-clang.html

http://www.aosabook.org/en/llvm.html

NAPI-RS 是怎么工作的: 从 NAPI 到 Build Script & FFI原创

前言

Build Script ｜文档

Cargo Instructions | 文档

Pattern

Foreign Function Interface (FFI)

FFI

Reverse FFI

FFI Safety

Opaque Type

写一个 *-sys crate

准备工作

新建一个 libsodium-sys

定义 wrapper.h

编写 build script

编写 binding 并测试

Tips

写一个简单的 `napi-sys`

准备工作

[live-coding]

可能遇到的问题

Tips

交叉编译

Zig

测试

Reference

推荐阅读

本月精选性能专题

本月精选线上案例

本月精选原创好文

联系我们

网媒渠道

友情链接

NAPI-RS 是怎么工作的: 从 NAPI 到 Build Script & FFI原创

前言

Build Script ｜文档

Cargo Instructions | 文档

Pattern

Foreign Function Interface (FFI)

FFI

Reverse FFI

FFI Safety

Opaque Type

写一个 *-sys crate

准备工作

新建一个 libsodium-sys

定义 wrapper.h

编写 build script

编写 binding 并测试

Tips

写一个简单的 napi-sys

准备工作

[live-coding]

可能遇到的问题

Tips

交叉编译

Zig

测试

Reference

推荐阅读

本月精选性能专题

本月精选线上案例

本月精选原创好文

联系我们

网媒渠道

友情链接

写一个简单的 `napi-sys`