From 3bc220db29e533888da417dc3034e5a31bb2ae70 Mon Sep 17 00:00:00 2001 From: Mark Lee Date: Mon, 7 Dec 2020 20:28:59 -0800 Subject: [PATCH] docs: clean up the native modules documentation (#26813) --- docs/tutorial/using-native-node-modules.md | 41 ++++++++++++---------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/tutorial/using-native-node-modules.md b/docs/tutorial/using-native-node-modules.md index ea362858df58..a1fd3f42b8cc 100644 --- a/docs/tutorial/using-native-node-modules.md +++ b/docs/tutorial/using-native-node-modules.md @@ -1,8 +1,9 @@ # Using Native Node Modules -Native Node modules are supported by Electron, but since Electron is very -likely to use a different V8 version from the Node binary installed on your -system, the modules you use will need to be recompiled for Electron. Otherwise, +Native Node.js modules are supported by Electron, but since Electron has a different +[application binary interface (ABI)][abi] from a given Node.js binary (due to +differences such as using Chromium's BoringSSL instead of OpenSSL), the native +modules you use will need to be recompiled for Electron. Otherwise, you will get the following class of error when you try to run your app: ```sh @@ -23,9 +24,11 @@ You can install modules like other Node projects, and then rebuild the modules for Electron with the [`electron-rebuild`][electron-rebuild] package. This module can automatically determine the version of Electron and handle the manual steps of downloading headers and rebuilding native modules for your app. +If you are using [Electron Forge][electron-forge], this tool is used automatically +in both development mode and when making distributables. -For example, to install `electron-rebuild` and then rebuild modules with it -via the command line: +For example, to install the standalone `electron-rebuild` tool and then rebuild +modules with it via the command line: ```sh npm install --save-dev electron-rebuild @@ -33,12 +36,12 @@ npm install --save-dev electron-rebuild # Every time you run "npm install", run this: ./node_modules/.bin/electron-rebuild -# On Windows if you have trouble, try: +# If you have trouble on Windows, try: .\node_modules\.bin\electron-rebuild.cmd ``` -For more information on usage and integration with other tools, consult the -project's README. +For more information on usage and integration with other tools such as [Electron +Packager][electron-packager], consult the project's README. ### Using `npm` @@ -147,23 +150,25 @@ for an example delay-load hook if you're implementing your own. native Node modules with prebuilt binaries for multiple versions of Node and Electron. -If modules provide binaries for the usage in Electron, make sure to omit -`--build-from-source` and the `npm_config_build_from_source` environment -variable in order to take full advantage of the prebuilt binaries. +If the `prebuild`-powered module provide binaries for the usage in Electron, +make sure to omit `--build-from-source` and the `npm_config_build_from_source` +environment variable in order to take full advantage of the prebuilt binaries. ## Modules that rely on `node-pre-gyp` The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node modules with prebuilt binaries, and many popular modules are using it. -Usually those modules work fine under Electron, but sometimes when Electron uses -a newer version of V8 than Node and/or there are ABI changes, bad things may -happen. So in general, it is recommended to always build native modules from -source code. `electron-rebuild` handles this for you automatically. +Sometimes those modules work fine under Electron, but when there are no +Electron-specific binaries available, you'll need to build from source. +Because of this, it is recommended to use `electron-rebuild` for these modules. -If you are following the `npm` way of installing modules, then this is done -by default, if not, you have to pass `--build-from-source` to `npm`, or set the -`npm_config_build_from_source` environment variable. +If you are following the `npm` way of installing modules, you'll need to pass +`--build-from-source` to `npm`, or set the `npm_config_build_from_source` +environment variable. +[abi]: https://en.wikipedia.org/wiki/Application_binary_interface [electron-rebuild]: https://github.com/electron/electron-rebuild +[electron-forge]: https://electronforge.io/ +[electron-packager]: https://github.com/electron/electron-packager [node-pre-gyp]: https://github.com/mapbox/node-pre-gyp