From 2e96297e1a606978b4910fc886919ad146a0ff7f Mon Sep 17 00:00:00 2001 From: LongYinan Date: Wed, 27 Apr 2022 13:17:30 +0800 Subject: [PATCH] chore: drop node 17, add node 18 --- .github/workflows/test.yaml | 2 +- README.md | 256 +----------------------------------- crates/napi/README.md | 109 +++++++++------ 3 files changed, 69 insertions(+), 298 deletions(-) mode change 100644 => 120000 README.md diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 3230f94b..e9918b78 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -14,7 +14,7 @@ jobs: strategy: fail-fast: false matrix: - node: ['14', '16', '17'] + node: ['14', '16', '18'] os: [ubuntu-latest, macos-latest, windows-latest] name: stable - ${{ matrix.os }} - node@${{ matrix.node }} diff --git a/README.md b/README.md deleted file mode 100644 index eed475df..00000000 --- a/README.md +++ /dev/null @@ -1,255 +0,0 @@ -# napi-rs - -Stake to support us - -chat - - -> This project was initialized from [xray](https://github.com/atom/xray) - -A minimal library for building compiled `Node.js` add-ons in `Rust`. - -_Main branch is now under napi@next developing. Checkout [v1 docs](https://napi.rs) for `napi@1.x`._ - -

- - - -

- -## Ecosystem - -

- - Prisma - -   -   - - swc - -   -   - - Parcel - -   - - next.js -   - nextjs.svg - -

- -## Platform Support - -![Lint](https://github.com/napi-rs/napi-rs/workflows/Lint/badge.svg) -![Linux musl](https://github.com/napi-rs/napi-rs/workflows/Linux%20musl/badge.svg) -![macOS/Windows/Linux x64](https://github.com/napi-rs/napi-rs/workflows/macOS/Windows/Linux%20x64/badge.svg) -![Linux-aarch64](https://github.com/napi-rs/napi-rs/workflows/Linux-aarch64/badge.svg) -![Linux-armv7](https://github.com/napi-rs/napi-rs/workflows/Linux-armv7/badge.svg) -![macOS-Android](https://github.com/napi-rs/napi-rs/workflows/macOS-Android/badge.svg) -[![Android-armv7](https://github.com/napi-rs/napi-rs/actions/workflows/android-armv7.yml/badge.svg)](https://github.com/napi-rs/napi-rs/actions/workflows/android-armv7.yml) -![Windows i686](https://github.com/napi-rs/napi-rs/workflows/Windows%20i686/badge.svg) -[![Windows arm64](https://github.com/napi-rs/napi-rs/actions/workflows/windows-arm.yml/badge.svg)](https://github.com/napi-rs/napi-rs/actions/workflows/windows-arm.yml) -[![FreeBSD](https://api.cirrus-ci.com/github/napi-rs/napi-rs.svg)](https://cirrus-ci.com/github/napi-rs/napi-rs?branch=main) - -## MSRV - -**Rust** `1.57.0` - -| | node12 | node14 | node16 | node17 | -| --------------------- | ------ | ------ | ------ | ------ | -| Windows x64 | ✓ | ✓ | ✓ | ✓ | -| Windows x86 | ✓ | ✓ | ✓ | ✓ | -| Windows arm64 | ✓ | ✓ | ✓ | ✓ | -| macOS x64 | ✓ | ✓ | ✓ | ✓ | -| macOS aarch64 | ✓ | ✓ | ✓ | ✓ | -| Linux x64 gnu | ✓ | ✓ | ✓ | ✓ | -| Linux x64 musl | ✓ | ✓ | ✓ | ✓ | -| Linux aarch64 gnu | ✓ | ✓ | ✓ | ✓ | -| Linux aarch64 musl | ✓ | ✓ | ✓ | ✓ | -| Linux arm gnueabihf | ✓ | ✓ | ✓ | ✓ | -| Linux aarch64 android | ✓ | ✓ | ✓ | ✓ | -| Linux armv7 android | ✓ | ✓ | ✓ | ✓ | -| FreeBSD x64 | ✓ | ✓ | ✓ | ✓ | - -This library depends on Node-API and requires `Node@10.0.0` or later. - -We already have some packages written by `napi-rs`: [node-rs](https://github.com/napi-rs/node-rs) - -One nice feature is that this crate allows you to build add-ons purely with the `Rust/JavaScript` toolchain and without involving `node-gyp`. - -## Taste - -> You can start from [package-template](https://github.com/napi-rs/package-template) to play with `napi-rs` - -### Define JavaScript functions - -```rust -#[macro_use] -extern crate napi; - -/// import the preludes -use napi::bindgen_prelude::*; - -/// 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 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(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 { - 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 -} -``` - -more examples at [examples](./examples/napi) - -## Building - -This repository is a `Cargo` crate. Any napi-based add-on should contain `Cargo.toml` to make it a Cargo crate. - -In your `Cargo.toml` you need to set the `crate-type` to `"cdylib"` so that cargo builds a C-style shared library that can be dynamically loaded by the Node executable. You'll also need to add this crate as a dependency. - -```toml -[package] -name = "awesome" - -[lib] -crate-type = ["cdylib"] - -[dependencies] -napi = "2" -napi-derive = "2" - -[build-dependencies] -napi-build = "1" -``` - -And create `build.rs` in your own project: - -```rust -// build.rs -extern crate napi_build; - -fn main() { - napi_build::setup(); -} -``` - -So far, the `napi` build script has only been tested on `macOS` `Linux` `Windows x64 MSVC` and `FreeBSD`. - -Install the `@napi-rs/cli` to help you build your `Rust` codes and copy `Dynamic lib` file to `.node` file in case you can `require` it in your program. - -```js -{ - "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" - } -} -``` - -Then you can require your native binding: - -```js -require('./jarvis.node') -``` - -The `module_name` would be your `package` name in your `Cargo.toml`. - -`xxx => ./xxx.node` - -`xxx-yyy => ./xxx_yyy.node` - -You can also copy `Dynamic lib` file to an appointed location: - -```bash -napi build [--release] ./dll -napi build [--release] ./artifacts -``` - -There are [documents](./cli) which contains more details about the `@napi-rs/cli` usage. - -## Testing - -Because libraries that depend on this crate must be loaded into a Node executable in order to resolve symbols, all tests are written in JavaScript in the `test_module` subdirectory. - -To run tests: - -```sh -yarn build:test -yarn test -``` - -## Related projects - -- [neon](https://www.neon-bindings.com) -- [node-bindgen](https://github.com/infinyon/node-bindgen) - -## Features table - -| Rust Type | Node Type | [NAPI Version](https://nodejs.org/api/n-api.html#n_api_node_api_version_matrix) | Minimal Node version | Enable by `napi` feature | -| ------------------------ | ------------------- | ------------------------------------------------------------------------------- | -------------------- | ------------------------ | -| u32 | Number | 1 | v8.0.0 | -| i32/i64 | Number | 1 | v8.0.0 | -| f64 | Number | 1 | v8.0.0 | -| bool | Boolean | 1 | v8.0.0 | -| String/&'a str | String | 1 | v8.0.0 | -| Latin1String | String | 1 | v8.0.0 | latin1 | -| UTF16String | String | 1 | v8.0.0 | -| Object | Object | 1 | v8.0.0 | -| serde_json::Map | Object | 1 | v8.0.0 | serde-json | -| serde_json::Value | any | 1 | v8.0.0 | serde-json | -| Array | Array | 1 | v8.0.0 | -| Vec | Array | 1 | v8.0.0 | -| Buffer | Buffer | 1 | v8.0.0 | -| External | External | 1 | v8.0.0 | | -| Null | null | 1 | v8.0.0 | -| Undefined/() | undefined | 1 | v8.0.0 | -| Result<()> | Error | 1 | v8.0.0 | -| T: Fn(...) -> Result | Function | 1 | v8.0.0 | -| Async/Future | Promise | 4 | v10.6.0 | async | -| AsyncTask | Promise | 1 | v8.5.0 | -| JsGlobal | global | 1 | v8.0.0 | -| JsSymbol | Symbol | 1 | v8.0.0 | -| Int8Array/Uint8Array ... | TypedArray | 1 | v8.0.0 | -| JsFunction | threadsafe function | 4 | v10.6.0 | napi4 | -| BigInt | BigInt | 6 | v10.7.0 | napi6 | diff --git a/README.md b/README.md new file mode 120000 index 00000000..0ad74e10 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +crates/napi/README.md \ No newline at end of file diff --git a/crates/napi/README.md b/crates/napi/README.md index ef1ef806..f8d3e1de 100644 --- a/crates/napi/README.md +++ b/crates/napi/README.md @@ -43,30 +43,35 @@ A minimal library for building compiled `Node.js` add-ons in `Rust`. ## Platform Support ![Lint](https://github.com/napi-rs/napi-rs/workflows/Lint/badge.svg) -![Linux N-API@3](https://github.com/napi-rs/napi-rs/workflows/Linux%20N-API@3/badge.svg) ![Linux musl](https://github.com/napi-rs/napi-rs/workflows/Linux%20musl/badge.svg) ![macOS/Windows/Linux x64](https://github.com/napi-rs/napi-rs/workflows/macOS/Windows/Linux%20x64/badge.svg) ![Linux-aarch64](https://github.com/napi-rs/napi-rs/workflows/Linux-aarch64/badge.svg) ![Linux-armv7](https://github.com/napi-rs/napi-rs/workflows/Linux-armv7/badge.svg) ![macOS-Android](https://github.com/napi-rs/napi-rs/workflows/macOS-Android/badge.svg) +[![Android-armv7](https://github.com/napi-rs/napi-rs/actions/workflows/android-armv7.yml/badge.svg)](https://github.com/napi-rs/napi-rs/actions/workflows/android-armv7.yml) ![Windows i686](https://github.com/napi-rs/napi-rs/workflows/Windows%20i686/badge.svg) [![Windows arm64](https://github.com/napi-rs/napi-rs/actions/workflows/windows-arm.yml/badge.svg)](https://github.com/napi-rs/napi-rs/actions/workflows/windows-arm.yml) [![FreeBSD](https://api.cirrus-ci.com/github/napi-rs/napi-rs.svg)](https://cirrus-ci.com/github/napi-rs/napi-rs?branch=main) -| | node12 | node14 | node16 | -| --------------------- | ------ | ------ | ------ | -| Windows x64 | ✓ | ✓ | ✓ | -| Windows x86 | ✓ | ✓ | ✓ | -| Windows arm64 | ✓ | ✓ | ✓ | -| macOS x64 | ✓ | ✓ | ✓ | -| macOS aarch64 | ✓ | ✓ | ✓ | -| Linux x64 gnu | ✓ | ✓ | ✓ | -| Linux x64 musl | ✓ | ✓ | ✓ | -| Linux aarch64 gnu | ✓ | ✓ | ✓ | -| Linux aarch64 musl | ✓ | ✓ | ✓ | -| Linux arm gnueabihf | ✓ | ✓ | ✓ | -| Linux aarch64 android | ✓ | ✓ | ✓ | -| FreeBSD x64 | ✓ | ✓ | ✓ | +## MSRV + +**Rust** `1.57.0` + +| | node12 | node14 | node16 | node18 | +| --------------------- | ------ | ------ | ------ | ------ | +| Windows x64 | ✓ | ✓ | ✓ | ✓ | +| Windows x86 | ✓ | ✓ | ✓ | ✓ | +| Windows arm64 | ✓ | ✓ | ✓ | ✓ | +| macOS x64 | ✓ | ✓ | ✓ | ✓ | +| macOS aarch64 | ✓ | ✓ | ✓ | ✓ | +| Linux x64 gnu | ✓ | ✓ | ✓ | ✓ | +| Linux x64 musl | ✓ | ✓ | ✓ | ✓ | +| Linux aarch64 gnu | ✓ | ✓ | ✓ | ✓ | +| Linux aarch64 musl | ✓ | ✓ | ✓ | ✓ | +| Linux arm gnueabihf | ✓ | ✓ | ✓ | ✓ | +| Linux aarch64 android | ✓ | ✓ | ✓ | ✓ | +| Linux armv7 android | ✓ | ✓ | ✓ | ✓ | +| FreeBSD x64 | ✓ | ✓ | ✓ | ✓ | This library depends on Node-API and requires `Node@10.0.0` or later. @@ -84,15 +89,15 @@ One nice feature is that this crate allows you to build add-ons purely with the #[macro_use] extern crate napi; -// import the preludes +/// import the preludes use napi::bindgen_prelude::*; -/// module registerion is done by the runtime, no need to explicitly do it now. +/// 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_native(n - 1) + fibonacci_native(n - 2), + _ => fibonacci(n - 1) + fibonacci(n - 2), } } @@ -108,9 +113,25 @@ fn get_cwd Result<()>>(callback: T) { fn test_callback(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 { + 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 +} ``` -Checkout more examples in [examples](./examples) folder +more examples at [examples](./examples/napi) ## Building @@ -203,26 +224,30 @@ yarn test ## Features table -| Rust Type | Node Type | [NAPI Version](https://nodejs.org/api/n-api.html#n_api_node_api_version_matrix) | Minimal Node version | -| ----------------------- | ---------------------- | ------------------------------------------------------------------------------- | -------------------- | -| u32 | Number | 1 | v8.0.0 | -| i32/i64 | Number | 1 | v8.0.0 | -| f64 | Number | 1 | v8.0.0 | -| bool | Boolean | 1 | v8.0.0 | -| String/&'a str | String | 1 | v8.0.0 | -| Latin1String | String | 1 | v8.0.0 | -| UTF16String | String | 1 | v8.0.0 | -| Object | Object | 1 | v8.0.0 | -| Array | Array | 1 | v8.0.0 | -| Vec | Array | 1 | v8.0.0 | -| Buffer | Buffer | 1 | v8.0.0 | -| Null | null | 1 | v8.0.0 | -| Undefined/() | undefined | 1 | v8.0.0 | -| Result<()> | Error | 1 | v8.0.0 | -| T: Fn(...) -> Result | function | 1 | v8.0.0 | -| (NOT YET) | global | 1 | v8.0.0 | -| (NOT YET) | Symbol | 1 | v8.0.0 | -| (NOT YET) | Promise | 1 | b8.5.0 | -| (NOT YET) | ArrayBuffer/TypedArray | 1 | v8.0.0 | -| (NOT YET) | threadsafe function | 4 | v10.6.0 | -| (NOT YET) | BigInt | 6 | v10.7.0 | +| Rust Type | Node Type | [NAPI Version](https://nodejs.org/api/n-api.html#n_api_node_api_version_matrix) | Minimal Node version | Enable by `napi` feature | +| ------------------------ | ------------------- | ------------------------------------------------------------------------------- | -------------------- | ------------------------ | +| u32 | Number | 1 | v8.0.0 | +| i32/i64 | Number | 1 | v8.0.0 | +| f64 | Number | 1 | v8.0.0 | +| bool | Boolean | 1 | v8.0.0 | +| String/&'a str | String | 1 | v8.0.0 | +| Latin1String | String | 1 | v8.0.0 | latin1 | +| UTF16String | String | 1 | v8.0.0 | +| Object | Object | 1 | v8.0.0 | +| serde_json::Map | Object | 1 | v8.0.0 | serde-json | +| serde_json::Value | any | 1 | v8.0.0 | serde-json | +| Array | Array | 1 | v8.0.0 | +| Vec | Array | 1 | v8.0.0 | +| Buffer | Buffer | 1 | v8.0.0 | +| External | External | 1 | v8.0.0 | | +| Null | null | 1 | v8.0.0 | +| Undefined/() | undefined | 1 | v8.0.0 | +| Result<()> | Error | 1 | v8.0.0 | +| T: Fn(...) -> Result | Function | 1 | v8.0.0 | +| Async/Future | Promise | 4 | v10.6.0 | async | +| AsyncTask | Promise | 1 | v8.5.0 | +| JsGlobal | global | 1 | v8.0.0 | +| JsSymbol | Symbol | 1 | v8.0.0 | +| Int8Array/Uint8Array ... | TypedArray | 1 | v8.0.0 | +| JsFunction | threadsafe function | 4 | v10.6.0 | napi4 | +| BigInt | BigInt | 6 | v10.7.0 | napi6 |