From e74a6bf5fdeab4efce73f7a7a9a8c3646ad38523 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Thu, 13 Aug 2020 17:55:21 +0800 Subject: [PATCH] doc: better readme --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 95a26a8..27b2405 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,55 @@ > Template project for writing node package with napi-rs. -## Requirement +## Install this test package + +``` +yarn add @napi-rs/package-template +``` + +## Support matrix + +> ⚠️ Linux musl has not been supported now. + +### Operating Systems + +| Linux | macOS | Windows x64 MSVC | +| ----- | ----- | ---------------- | +| ✓ | ✓ | ✓ | + +### NodeJS + +| Node10 | Node 12 | Node14 | +| ------ | ------- | ------ | +| ✓ | ✓ | ✓ | + +## Ability + +### Build + +After `yarn build/npm run build` command, you can see `index.[darwin|win32|linux].node` file in project root. This is the native addon built from [lib.rs](./src/lib.rs). + +### Test + +With [ava](https://github.com/avajs/ava), run `yarn test/npm run test` to testing native addon. You can also switch to another testing framework if you want. + +### CI + +With github actions, every commits and pull request will be built and tested automatically in [`node@10`, `node@12`, `@node14`] x [`macOS`, `Linux`, `Windows`] matrix. You will never be afraid of the native addon broken in these platforms. + +### Release + +Release native package is very difficult in old days. Native packages may ask developers who use its to install `build toolchains` like `gcc/llvm` , `node-gyp` or something more. + +With `Github actions`, we can easily prebuild `binary` for major platforms. And with `N-API`, we should never afraid of **ABI Compatible**. + +The other problem is how to deliver prebuild `binary` to users. Download it in `postinstall` script is a common way which most packages do it right now. The problem of this solution is it introduced many other packages to download binary which has not been used by `runtime codes`. The other problem is some user may not easily download the binary from `github/CDN` if they are behind private network (But in most case, they have a private NPM mirror). + +In this package we choose a better way to solve this problem. We release different `npm packages` for different platform. And add it to `optionalDependencies` before release the `Major` package to npm. + +`NPM` will choose which native package should download from `registry` automatically. You can see [npm](./npm) dir for details. And you can also run `yarn add @napi-rs/package-template` to see how it works. + +## Develop requirements - Install latest `Rust` - Install `NodeJS@8.9+` which supported `N-API`