Repository files navigation

Create and package prebuilds for native modules

npm install -g prebuildify

Withprebuildify, all prebuilt binaries are shipped inside the package that is published to npm, which means there's no need for a separate download step like you find inprebuild. The irony of this approach is that it is faster to download all prebuilt binaries for every platform when they are bundled than it is to download a single prebuilt binary as an install script.

Always use prebuildify --@mafintosh

Note. Options, environment variables and prebuild names have changed inprebuildify@3. Please see the documentation below. You will also need to upgradenode-gyp-build.

First go to your native module and make a bunch of prebuilds.

# go to your native modulecd your-native-module# build for all electron/node binary versions and strip out symbolsprebuildify --all --strip# the prebuilds will be stored in ./prebuildsls prebuilds

If your module is using the node coreNode-API, which was previously known as N-API, then you can prebuild using the--napi flag:

# prebuild for node-apiprebuildify --napi

Then only remaining thing you need to do now is make your module use a prebuild if one existsfor the platform/runtime you are using.

Usenode-gyp-build to do this.

# first install node-gyp-buildnpm install --save node-gyp-build

Then addnode-gyp-build as an install script to your module'spackage.json:

{"name":"your-native-module","scripts":{"install":"node-gyp-build"}}

The install script will check if a compatible prebuild is bundled. If so it does nothing. If not it will runnode-gyp rebuild to produce a build.This means that if the user using your module has disabled install scripts your module will still work (!) as long as a compatible prebuild is bundled.

When loading your native binding from yourindex.js you should usenode-gyp-build as will to make sure to get the right binding

// Will load a compiled build if present or a prebuild.// If no build if found it will throw an exceptionvarbinding=require('node-gyp-build')(__dirname)module.exports=binding

An added benefit of this approach is that your native modules will work across multiple node and electron versions without having the userneed to reinstall or recompile them - as long as you produce prebuilds for all versions. With Node-API you only have to produce prebuilds for every runtime.

When publishing your module to npm remember to include the./prebuilds folder.

That's it! Happy native hacking.

Options can be provided via (in order of precedence) the programmatic API, the CLI or environment variables. The environment variables, whether they are defined on the outside or not, are also made available to subprocesses. For example,prebuildify --arch arm64 --strip setsPREBUILD_ARCH=arm64 PREBUILD_STRIP=1.

* A target takes the form of(runtime@)?version, whereruntime defaults to'node'. For example:-t 8.14.0 -t electron@3.0.0. At least one of--target,--all or--napi must be specified.

** Thearch option is passed tonode-gyp as--arch. Target architecture and platform (what you're buildingfor) default to the host platform and architecture (what you're buildingon). They can be overridden for cross-compilation, in which case you'll likely also want to override the strip binary. The platform and architecture dictate the output folder (to be found bynode-gyp-build at runtime). For example on Linux x64 prebuilds end up inprebuilds/linux-x64. Thearch option can also be a multi-arch value separated by+ (for examplex64+arm64 for auniversal binary) mainly to dictate the output folder; only the first architecture is passed on tonode-gyp.

*** The filenames of prebuilds are composed oftags which by default include runtime and eithernapi orabi<version>. For example:electron.abi40.node. To make more specific prebuilds (fornode-gyp-build to select) you can add additional tags. Values for these tags are auto-detected. For example,--napi --tag-uv --tag-armv could result in a build callednode.napi.uv1.armv8.node if the host machine has an ARM architecture. When cross-compiling you can override values either through the relevant option (--tag-armv --armv 7) or the tag (--tag-armv 7) as a shortcut. They're separate because you may want to build a certain version without tagging the prebuild as such, assuming that the prebuild is forward compatible.

**** To enable the use of forks likenodejs-mobile-gyp.

MIT