mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

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

Browse source
This commit is contained in:
Mark Lee 2020-12-07 20:28:59 -08:00 • committed by GitHub
parent 6001f03e46
commit 3bc220db29
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/tutorial/using-native-node-modules.md
View file

@ -1,8 +1,9 @@
# Using Native Node Modules # Using Native Node Modules
Native Node modules are supported by Electron, but since Electron is very Native Node.js modules are supported by Electron, but since Electron has a different
likely to use a different V8 version from the Node binary installed on your [application binary interface (ABI)][abi] from a given Node.js binary (due to
system, the modules you use will need to be recompiled for Electron. Otherwise, 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: you will get the following class of error when you try to run your app:
```sh ```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 for Electron with the [`electron-rebuild`][electron-rebuild] package. This
module can automatically determine the version of Electron and handle the module can automatically determine the version of Electron and handle the
manual steps of downloading headers and rebuilding native modules for your app. 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 For example, to install the standalone `electron-rebuild` tool and then rebuild
via the command line: modules with it via the command line:
```sh ```sh
npm install --save-dev electron-rebuild npm install --save-dev electron-rebuild
@ -33,12 +36,12 @@ npm install --save-dev electron-rebuild
# Every time you run "npm install", run this: # Every time you run "npm install", run this:
./node_modules/.bin/electron-rebuild ./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 .\node_modules\.bin\electron-rebuild.cmd
``` ```
For more information on usage and integration with other tools, consult the For more information on usage and integration with other tools such as [Electron
project's README. Packager][electron-packager], consult the project's README.
### Using `npm` ### 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 native Node modules with prebuilt binaries for multiple versions of Node
and Electron. and Electron.
If modules provide binaries for the usage in Electron, make sure to omit If the `prebuild`-powered module provide binaries for the usage in Electron,
`--build-from-source` and the `npm_config_build_from_source` environment make sure to omit `--build-from-source` and the `npm_config_build_from_source`
variable in order to take full advantage of the prebuilt binaries. environment variable in order to take full advantage of the prebuilt binaries.
## Modules that rely on `node-pre-gyp` ## Modules that rely on `node-pre-gyp`
The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node 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. modules with prebuilt binaries, and many popular modules are using it.
Usually those modules work fine under Electron, but sometimes when Electron uses Sometimes those modules work fine under Electron, but when there are no
a newer version of V8 than Node and/or there are ABI changes, bad things may Electron-specific binaries available, you'll need to build from source.
happen. So in general, it is recommended to always build native modules from Because of this, it is recommended to use `electron-rebuild` for these modules.
source code. `electron-rebuild` handles this for you automatically.
If you are following the `npm` way of installing modules, then this is done If you are following the `npm` way of installing modules, you'll need to pass
by default, if not, you have to pass `--build-from-source` to `npm`, or set the `--build-from-source` to `npm`, or set the `npm_config_build_from_source`
`npm_config_build_from_source` environment variable. environment variable.
[abi]: https://en.wikipedia.org/wiki/Application_binary_interface
[electron-rebuild]: https://github.com/electron/electron-rebuild [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 [node-pre-gyp]: https://github.com/mapbox/node-pre-gyp