| 1 | # node-gyp-build
|
|---|
| 2 |
|
|---|
| 3 | > Build tool and bindings loader for [`node-gyp`][node-gyp] that supports prebuilds.
|
|---|
| 4 |
|
|---|
| 5 | ```
|
|---|
| 6 | npm install node-gyp-build
|
|---|
| 7 | ```
|
|---|
| 8 |
|
|---|
| 9 | [](https://github.com/prebuild/node-gyp-build/actions/workflows/test.yml)
|
|---|
| 10 |
|
|---|
| 11 | Use together with [`prebuildify`][prebuildify] to easily support prebuilds for your native modules.
|
|---|
| 12 |
|
|---|
| 13 | ## Usage
|
|---|
| 14 |
|
|---|
| 15 | > **Note.** Prebuild names have changed in [`prebuildify@3`][prebuildify] and `node-gyp-build@4`. Please see the documentation below.
|
|---|
| 16 |
|
|---|
| 17 | `node-gyp-build` works similar to [`node-gyp build`][node-gyp] except that it will check if a build or prebuild is present before rebuilding your project.
|
|---|
| 18 |
|
|---|
| 19 | It's main intended use is as an npm install script and bindings loader for native modules that bundle prebuilds using [`prebuildify`][prebuildify].
|
|---|
| 20 |
|
|---|
| 21 | First add `node-gyp-build` as an install script to your native project
|
|---|
| 22 |
|
|---|
| 23 | ``` js
|
|---|
| 24 | {
|
|---|
| 25 | ...
|
|---|
| 26 | "scripts": {
|
|---|
| 27 | "install": "node-gyp-build"
|
|---|
| 28 | }
|
|---|
| 29 | }
|
|---|
| 30 | ```
|
|---|
| 31 |
|
|---|
| 32 | Then in your `index.js`, instead of using the [`bindings`](https://www.npmjs.com/package/bindings) module use `node-gyp-build` to load your binding.
|
|---|
| 33 |
|
|---|
| 34 | ``` js
|
|---|
| 35 | var binding = require('node-gyp-build')(__dirname)
|
|---|
| 36 | ```
|
|---|
| 37 |
|
|---|
| 38 | If you do these two things and bundle prebuilds with [`prebuildify`][prebuildify] your native module will work for most platforms
|
|---|
| 39 | without having to compile on install time AND will work in both node and electron without the need to recompile between usage.
|
|---|
| 40 |
|
|---|
| 41 | Users can override `node-gyp-build` and force compiling by doing `npm install --build-from-source`.
|
|---|
| 42 |
|
|---|
| 43 | Prebuilds will be attempted loaded from `MODULE_PATH/prebuilds/...` and then next `EXEC_PATH/prebuilds/...` (the latter allowing use with `zeit/pkg`)
|
|---|
| 44 |
|
|---|
| 45 | ## Supported prebuild names
|
|---|
| 46 |
|
|---|
| 47 | If so desired you can bundle more specific flavors, for example `musl` builds to support Alpine, or targeting a numbered ARM architecture version.
|
|---|
| 48 |
|
|---|
| 49 | These prebuilds can be bundled in addition to generic prebuilds; `node-gyp-build` will try to find the most specific flavor first. Prebuild filenames are composed of _tags_. The runtime tag takes precedence, as does an `abi` tag over `napi`. For more details on tags, please see [`prebuildify`][prebuildify].
|
|---|
| 50 |
|
|---|
| 51 | Values for the `libc` and `armv` tags are auto-detected but can be overridden through the `LIBC` and `ARM_VERSION` environment variables, respectively.
|
|---|
| 52 |
|
|---|
| 53 | ## License
|
|---|
| 54 |
|
|---|
| 55 | MIT
|
|---|
| 56 |
|
|---|
| 57 | [prebuildify]: https://github.com/prebuild/prebuildify
|
|---|
| 58 | [node-gyp]: https://www.npmjs.com/package/node-gyp
|
|---|
