docs: clean up the native modules documentation (#26813)

electron · Dec 8, 2020 · 3bc220d · 3bc220d
1 parent 6001f03
commit 3bc220d
Showing 1 changed file with 23 additions and 18 deletions.
diff --git 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,22 +24,24 @@ 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
 
 # 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