prebuildify

Create and package prebuilds for native modules

npm install -g prebuildify

With prebuildify, 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 in prebuild. 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

Usage

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

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

# go to your native module
cd your-native-module
# build for all electron/node binary versions and strip out symbols
prebuildify --all --strip
# the prebuilds will be stored in ./prebuilds
ls prebuilds

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

# prebuild for node-api
prebuildify --napi

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

Use node-gyp-build to do this.

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

Then add node-gyp-build as an install script to your module's package.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 run node-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 your index.js you should use node-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 exception
var binding = 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 user need 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.

Platform-specific Packages

As an alternate to including all prebuilds directly in your published package, you can use --platform-packages to setup the prebuilds for publishing as separate platform-specific packages. Using this option, each prebuild directory will also include a package.json that specifies the target platform and architectures along with some basic package files. Each of these prebuild directories can then be published as separate packages in NPM. In addition, the main package should specify all the platform packages as optionalDependencies. When installed, npm (or similar) will then only install the optional dependency with the platform & architecture matching the target machine.

This provides both the efficiency of only needing to install the binaries needed for the current platform, and the key benefit of the prebuildify approach in that binaries are downloaded as part of the normal npm install process (without install scripts). When using this option, you should omit the ./prebuilds folder when publishing your main package, since they will be separately downloaded by npm. In npm 7+, only the matching platform package will be downloaded (and installed). In yarn and older versions of npm, all the platform packages will be downloaded (once to the package cache), but only the matching platform package will be installed.

If you do not use this option, when publishing your package to npm, remember to include the ./prebuilds folder.

That's it! Happy native hacking.

Options

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 sets PREBUILD_ARCH=arm64 PREBUILD_STRIP=1.

| CLI | Environment | Default | Description |:---------------------|:---------------------|:-------------------------------|:------------ | --target -t | - | Depends. | One or more targets* | --all -a | - | false | Build all known targets.Takes precedence over --target. | --napi | - | false | Make Node-API build(s).Targets default to latest node which is compatible with Electron > 3, which can be overridden with --target. Note: --all should be avoided for now because it includes targets that don't support Node-API. | --electron-compat | - | false | Make two Node-API builds, one for node and one for Electron. Useful if you support Electron <= 3. | --debug | - | false | Make Debug build(s) | --arch | PREBUILD_ARCH | os.arch() | Target architecture** | --platform | PREBUILD_PLATFORM | os.platform() | Target platform** | --uv | PREBUILD_UV | From process.versions.uv | Major libuv version*** | --armv | PREBUILD_ARMV | Auto-detected on ARM machines | Numeric ARM version (e.g. 7)*** | --libc | PREBUILD_LIBC | glibc, musl on Alpine | libc flavor*** | --tag-uv | - | false | Tag prebuild with uv*** | --tag-armv | - | false | Tag prebuild with armv*** | --tag-libc | - | false | Tag prebuild with libc*** | --platform-packages| - | false | Add package.json and basic files for package publishing | --preinstall | - | - | Command to run before build | --postinstall | - | - | Command to run after build | --shell | PREBUILD_SHELL | 'sh' on Android | Shell to spawn commands in | --artifacts | - | - | Directory containing additional files.Recursively copied into prebuild directory. | --strip | PREBUILD_STRIP | false | Enable stripping | --strip-bin | PREBUILD_STRIP_BIN | 'strip' | Custom strip binary | --node-gyp | PREBUILD_NODE_GYP | 'node-gyp(.cmd)' | Custom node-gyp binary**** | --quiet | - | false | Suppress node-gyp output | --cwd | - | process.cwd() | Working directory

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

** The arch option is passed to node-gyp as --arch. Target architecture and platform (what you're building for) default to the host platform and architecture (what you're building on). 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 by node-gyp-build at runtime). For example on Linux x64 prebuilds end up in prebuilds/linux-x64. The arch option can also be a multi-arch value separated by + (for example x64+arm64 for a universal binary) mainly to dictate the output folder; only the first architecture is passed on to node-gyp.

*** The filenames of prebuilds are composed of tags which by default include runtime and either napi or abi<version>. For example: electron.abi40.node. To make more specific prebuilds (for node-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 called node.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 like nodejs-mobile-gyp.

License

MIT