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

Update the using-native-node-modules.md

Browse source
This commit is contained in:
Cheng Zhao 2016-06-16 17:10:57 +09:00
parent 58bce74255
commit 611791ea30
1 changed files with 69 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,67 +1,93 @@
# Using Native Node Modules
The native Node modules are supported by Electron, but since Electron is
using a different V8 version from official Node, you have to manually specify
the location of Electron's headers when building native modules.
The native Node modules are supported by Electron, but since Electron is very
likely to use a different V8 version from the Node binary installed in your
system, you have to manually specify the location of Electron's headers when
building native modules.
## Native Node Module Compatibility
Native modules might break when Node starts using a new version of V8.
To make sure the module you're interested in will work with Electron, you should
check if it supports the internal Node version used by Electron.
You can check what version of Node is used in Electron by looking it up in
the [releases](https://github.com/electron/electron/releases) page or by using
`process.version` (see [Quick Start](https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md)
for example).
Consider using [NAN](https://github.com/nodejs/nan/) for your own modules, since
it makes it easier to support multiple versions of Node. It's also helpful for
porting old modules to newer versions of Node so they can work with Electron.
## How to Install Native Modules
## How to install native modules
Three ways to install native modules:
### The Easy Way
### Using `npm`
The most straightforward way to rebuild native modules is via the
[`electron-rebuild`](https://github.com/paulcbetts/electron-rebuild) package,
which handles the manual steps of downloading headers and building native modules:
By setting a few environment variables, you can use `npm` to install modules
directly.
```sh
An example of installing all dependencies for Electron:
```bash
# Electron's version.
export npm_config_target=1.2.3
# The architecture of Electron, can be ia32 or x64.
export npm_config_arch=x64
# Download headers for Electron.
export npm_config_disturl=https://atom.io/download/atom-shell
# Tell node-pre-gyp that we are building for Electron.
export npm_config_runtime=electron
# Tell node-pre-gyp to build module from source code.
export npm_config_build_from_source=true
# Install all dependencies, and store cache to ~/.electron-gyp.
HOME=~/.electron-gyp npm install
```
### Installing modules and rebuilding for Electron
You can also choose to install modules like other Node projects, and then
rebuild the modules for Electron with the [`electron-rebuild`][electron-rebuild]
package. This module can get the version of Electron and handle the manual steps
of downloading headers and building native modules for your.
An example of installing `electron-rebuild` and then rebuild modules with it:
```bash
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
# On Windows if you have trouble, try:
.\node_modules\.bin\electron-rebuild.cmd
```
### The npm Way
### Manually building for Electron
You can also use `npm` to install modules. The steps are exactly the same with
Node modules, except that you need to setup some environment variables:
If you are a developer developing a native module and want to test it against
Electron, you might want to rebuild the module for Electron manually. You can
use `node-gyp` directly to build for Electron:
```bash
export npm_config_disturl=https://atom.io/download/atom-shell
export npm_config_target=0.33.1
export npm_config_arch=x64
export npm_config_runtime=electron
HOME=~/.electron-gyp npm install module-name
```
### The node-gyp Way
To build Node modules with headers of Electron, you need to tell `node-gyp`
where to download headers and which version to use:
```bash
$ cd /path-to-module/
$ HOME=~/.electron-gyp node-gyp rebuild --target=0.29.1 --arch=x64 --dist-url=https://atom.io/download/atom-shell
cd /path-to-module/
HOME=~/.electron-gyp node-gyp rebuild --target=1.2.3 --arch=x64 --dist-url=https://atom.io/download/atom-shell
```
The `HOME=~/.electron-gyp` changes where to find development headers. The
`--target=0.29.1` is version of Electron. The `--dist-url=...` specifies
`--target=1.2.3` is version of Electron. The `--dist-url=...` specifies
where to download the headers. The `--arch=x64` says the module is built for
64bit system.
## Troubleshooting
If you installed a native module and found it was not working, you need to check
following things:
* The architecture of module has to match Electron's architecture (ia32 or x64).
* After you upgraded Electron, you usually need to rebuild the modules.
* When in doubt, run `electron-rebuild` first.
## 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 there are ABI changes, bad things may
happen. So in general it is recommended to always build native modules from
source code.
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.
[electron-rebuild]: https://github.com/paulcbetts/electron-rebuild
[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp