@@ -6,15 +6,16 @@ directory structure which disambiguates the binaries by their triplets.
66It serves a similar purpose to [ ` prebuildify ` ] and [ ` pkg-prebuilds ` ] .
77
88Design goals:
9- * don't drag in any "unnecessary" dependencies (see [ below] ( #no-unnecessary-dependencies ) )
10- * be build-system agnostic
11- * no magic / explicit configuration over guesswork
12- * be lightweight
13- * provide typed APIs for CLI commands
9+
10+ * don't drag in any "unnecessary" dependencies (see [ below] ( #no-unnecessary-dependencies ) )
11+ * be build-system agnostic
12+ * no magic / explicit configuration over guesswork
13+ * be lightweight
14+ * provide typed APIs for CLI commands
1415
1516Non-goals:
16- * Support node addons implemented with nan / V8 / libuv APIs
1717
18+ * Support node addons implemented with nan / V8 / libuv APIs
1819
1920## Usage
2021
@@ -24,26 +25,31 @@ yarn add @adesso-se/node-api-prebuilts
2425npm install --save @adesso-se/node-api-prebuilts
2526```
2627
27- Add the ` prebuilts/ ` directory to your ` .gitignore ` and include it in your
28+ Add the ` prebuilts/ ` directory to your ` .gitignore ` and include it in your
2829distribution package via the ` package.json#files ` property.
2930
3031Add a post-build step to your native addon that copies the built addon into the
3132` prebuilts ` directory. The invocation should roughly look like this:
33+
3234``` sh
3335node-api-prebuilts --cmd=copy --build-dir=buid/Release --package-dir=. --name=nvefs --napi-version=8
3436```
37+
3538See [ CLI Documentation] ( #cli-documentation ) for more information.
3639
3740Add a ` loader-options.json ` to your package. It defines the supported Node API
3841versions and the addon name in a central place, e.g.:
42+
3943``` json
4044{
4145 "name" : " nvefs" ,
4246 "napi_versions" : [8 ]
4347}
4448```
49+
4550With the scaffolding in place the addon can be loaded like this (assuming the
4651compiled js output is placed in the package root):
52+
4753``` ts
4854import { requireAddon } from ' @adesso-se/node-api-prebuilts' ;
4955const {
@@ -59,16 +65,17 @@ const {
5965
6066Lastly you want to prevent rebuilding the native addon on package-install if a
6167suitable prebuilt binary already exists:
68+
6269``` json
6370{
6471 "scripts" : {
6572 "install" : " node-api-prebuilts --cmd=check-path --loader-options=loader-options.json || <the addon needs to be built>"
6673 }
6774}
6875```
69- The ` check-path ` command sets the exit code to zero if a prebuilt binary has
70- been found and to a non-zero exit code otherwise.
7176
77+ The ` check-path ` command sets the exit code to zero if a prebuilt binary has
78+ been found and to a non-zero exit code otherwise.
7279
7380### API Synopsis
7481
@@ -142,13 +149,13 @@ export function activeTriplet(): Triplet;
142149 */
143150export function tripletId(triplet : Triplet ): string ;
144151```
152+
145153Note that this doesn't describe all public APIs but the most commonly used ones.
146154Consult ` src/index.ts ` for a complete list. All public APIs have JSDoc comments.
147155
148-
149156### CLI Documentation
150157
151- ```
158+ ``` text
152159USAGE
153160 $ node-api-prebuilts [-h | --help]
154161 $ node-api-prebuilts --cmd=<command>
@@ -199,21 +206,19 @@ EXAMPLES
199206 $ node-api-prebuilts --cmd=check-path --loader-options=loader-options.json
200207```
201208
202-
203209## No unnecessary Dependencies
210+
204211At its core this libray has one job: Locate (and load) a native node addon for
205212the execution triplet. Therefore we only want to depend on packages that
206213directly help with this task and are stable. It is also quite annoying to
207214retrieve deprecation/security notices about libraries which are only ever used
208215by install scripts. This implies that we can't use ` yargs ` and the like to parse
209216CLI arguments.
210217
211-
212218## License
213219
214220[ MIT License] ( https://choosealicense.com/licenses/mit/ )
215221
216-
217222[ Node-API ] : https://nodejs.org/dist/latest-v16.x/docs/api/n-api.html#node-api
218223[ `prebuildify` ] : https://www.npmjs.com/package/prebuildify
219224[ `pkg-prebuilds` ] : https://www.npmjs.com/package/pkg-prebuilds
0 commit comments