From: Cheng Zhao Date: Thu, 16 Jun 2016 08:10:57 +0000 (+0900) Subject: Update the using-native-node-modules.md X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=611791ea30c2ada6f4de0cbd741df9fa34d98ded;p=platform%2Fframework%2Fweb%2Fcrosswalk-tizen.git Update the using-native-node-modules.md --- diff --git a/docs/tutorial/using-native-node-modules.md b/docs/tutorial/using-native-node-modules.md index f73c1cd..1b7dbed 100644 --- a/docs/tutorial/using-native-node-modules.md +++ b/docs/tutorial/using-native-node-modules.md @@ -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 +## How to install native modules -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). +Three ways to install native modules: -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. +### Using `npm` -## How to Install Native Modules +By setting a few environment variables, you can use `npm` to install modules +directly. -Three ways to install native modules: +An example of installing all dependencies for Electron: -### The Easy Way +```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 +``` -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: +### Installing modules and rebuilding for Electron -```sh +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 - -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: - -```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 +### Manually building for Electron -To build Node modules with headers of Electron, you need to tell `node-gyp` -where to download headers and which version to use: +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 -$ 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