245 lines
10 KiB
Markdown
245 lines
10 KiB
Markdown
|
node-gyp
|
||
|
|
=========
|
||
|
|
## Node.js native addon build tool
|
||
|
|
|
||
|
|
`node-gyp` is a cross-platform command-line tool written in Node.js for compiling
|
||
|
|
native addon modules for Node.js. It bundles the [gyp](https://gyp.gsrc.io)
|
||
|
|
project used by the Chromium team and takes away the pain of dealing with the
|
||
|
|
various differences in build platforms. It is the replacement to the `node-waf`
|
||
|
|
program which is removed for node `v0.8`. If you have a native addon for node that
|
||
|
|
still has a `wscript` file, then you should definitely add a `binding.gyp` file
|
||
|
|
to support the latest versions of node.
|
||
|
|
|
||
|
|
Multiple target versions of node are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
|
||
|
|
etc.), regardless of what version of node is actually installed on your system
|
||
|
|
(`node-gyp` downloads the necessary development files or headers for the target version).
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
* Easy to use, consistent interface
|
||
|
|
* Same commands to build your module on every platform
|
||
|
|
* Supports multiple target versions of Node
|
||
|
|
|
||
|
|
|
||
|
|
Installation
|
||
|
|
------------
|
||
|
|
|
||
|
|
You can install with `npm`:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
$ npm install -g node-gyp
|
||
|
|
```
|
||
|
|
|
||
|
|
You will also need to install:
|
||
|
|
|
||
|
|
### On Unix
|
||
|
|
|
||
|
|
* `python` (`v2.7` recommended, `v3.x.x` is __*not*__ supported)
|
||
|
|
* `make`
|
||
|
|
* A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org)
|
||
|
|
|
||
|
|
### On macOS
|
||
|
|
|
||
|
|
* `python` (`v2.7` recommended, `v3.x.x` is __*not*__ supported) (already installed on macOS)
|
||
|
|
* [Xcode](https://developer.apple.com/xcode/download/)
|
||
|
|
* You also need to install the `Command Line Tools` via Xcode. You can find this under the menu `Xcode -> Preferences -> Locations` (or by running `xcode-select --install` in your Terminal)
|
||
|
|
* This step will install `gcc` and the related toolchain containing `make`
|
||
|
|
|
||
|
|
### On Windows
|
||
|
|
|
||
|
|
#### Option 1
|
||
|
|
|
||
|
|
Install all the required tools and configurations using Microsoft's [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) using `npm install --global --production windows-build-tools` from an elevated PowerShell or CMD.exe (run as Administrator).
|
||
|
|
|
||
|
|
#### Option 2
|
||
|
|
|
||
|
|
Install tools and configuration manually:
|
||
|
|
* Install Visual C++ Build Environment: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools)
|
||
|
|
(using "Visual C++ build tools" workload) or [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
|
||
|
|
(using the "Desktop development with C++" workload)
|
||
|
|
* Install [Python 2.7](https://www.python.org/downloads/) (`v3.x.x` is not supported), and run `npm config set python python2.7` (or see below for further instructions on specifying the proper Python version and path.)
|
||
|
|
* Launch cmd, `npm config set msvs_version 2017`
|
||
|
|
|
||
|
|
If the above steps didn't work for you, please visit [Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules) for additional tips.
|
||
|
|
|
||
|
|
If you have multiple Python versions installed, you can identify which Python
|
||
|
|
version `node-gyp` uses by setting the '--python' variable:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
$ node-gyp --python /path/to/python2.7
|
||
|
|
```
|
||
|
|
|
||
|
|
If `node-gyp` is called by way of `npm` *and* you have multiple versions of
|
||
|
|
Python installed, then you can set `npm`'s 'python' config key to the appropriate
|
||
|
|
value:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
$ npm config set python /path/to/executable/python2.7
|
||
|
|
```
|
||
|
|
|
||
|
|
How to Use
|
||
|
|
----------
|
||
|
|
|
||
|
|
To compile your native addon, first go to its root directory:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
$ cd my_node_addon
|
||
|
|
```
|
||
|
|
|
||
|
|
The next step is to generate the appropriate project build files for the current
|
||
|
|
platform. Use `configure` for that:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
$ node-gyp configure
|
||
|
|
```
|
||
|
|
|
||
|
|
Auto-detection fails for Visual C++ Build Tools 2015, so `--msvs_version=2015`
|
||
|
|
needs to be added (not needed when run by npm as configured above):
|
||
|
|
``` bash
|
||
|
|
$ node-gyp configure --msvs_version=2015
|
||
|
|
```
|
||
|
|
|
||
|
|
__Note__: The `configure` step looks for the `binding.gyp` file in the current
|
||
|
|
directory to process. See below for instructions on creating the `binding.gyp` file.
|
||
|
|
|
||
|
|
Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file
|
||
|
|
(on Windows) in the `build/` directory. Next invoke the `build` command:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
$ node-gyp build
|
||
|
|
```
|
||
|
|
|
||
|
|
Now you have your compiled `.node` bindings file! The compiled bindings end up
|
||
|
|
in `build/Debug/` or `build/Release/`, depending on the build mode. At this point
|
||
|
|
you can require the `.node` file with Node and run your tests!
|
||
|
|
|
||
|
|
__Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or
|
||
|
|
`-d`) switch when running either the `configure`, `build` or `rebuild` command.
|
||
|
|
|
||
|
|
|
||
|
|
The "binding.gyp" file
|
||
|
|
----------------------
|
||
|
|
|
||
|
|
Previously when node had `node-waf` you had to write a `wscript` file. The
|
||
|
|
replacement for that is the `binding.gyp` file, which describes the configuration
|
||
|
|
to build your module in a JSON-like format. This file gets placed in the root of
|
||
|
|
your package, alongside the `package.json` file.
|
||
|
|
|
||
|
|
A barebones `gyp` file appropriate for building a node addon looks like:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
{
|
||
|
|
"targets": [
|
||
|
|
{
|
||
|
|
"target_name": "binding",
|
||
|
|
"sources": [ "src/binding.cc" ]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Some additional resources for addons and writing `gyp` files:
|
||
|
|
|
||
|
|
* ["Going Native" a nodeschool.io tutorial](http://nodeschool.io/#goingnative)
|
||
|
|
* ["Hello World" node addon example](https://github.com/nodejs/node/tree/master/test/addons/hello-world)
|
||
|
|
* [gyp user documentation](https://gyp.gsrc.io/docs/UserDocumentation.md)
|
||
|
|
* [gyp input format reference](https://gyp.gsrc.io/docs/InputFormatReference.md)
|
||
|
|
* [*"binding.gyp" files out in the wild* wiki page](https://github.com/nodejs/node-gyp/wiki/%22binding.gyp%22-files-out-in-the-wild)
|
||
|
|
|
||
|
|
|
||
|
|
Commands
|
||
|
|
--------
|
||
|
|
|
||
|
|
`node-gyp` responds to the following commands:
|
||
|
|
|
||
|
|
| **Command** | **Description**
|
||
|
|
|:--------------|:---------------------------------------------------------------
|
||
|
|
| `help` | Shows the help dialog
|
||
|
|
| `build` | Invokes `make`/`msbuild.exe` and builds the native addon
|
||
|
|
| `clean` | Removes the `build` directory if it exists
|
||
|
|
| `configure` | Generates project build files for the current platform
|
||
|
|
| `rebuild` | Runs `clean`, `configure` and `build` all in a row
|
||
|
|
| `install` | Installs node header files for the given version
|
||
|
|
| `list` | Lists the currently installed node header versions
|
||
|
|
| `remove` | Removes the node header files for the given version
|
||
|
|
|
||
|
|
|
||
|
|
Command Options
|
||
|
|
--------
|
||
|
|
|
||
|
|
`node-gyp` accepts the following command options:
|
||
|
|
|
||
|
|
| **Command** | **Description**
|
||
|
|
|:----------------------------------|:------------------------------------------
|
||
|
|
| `-j n`, `--jobs n` | Run make in parallel
|
||
|
|
| `--target=v6.2.1` | Node version to build for (default=process.version)
|
||
|
|
| `--silly`, `--loglevel=silly` | Log all progress to console
|
||
|
|
| `--verbose`, `--loglevel=verbose` | Log most progress to console
|
||
|
|
| `--silent`, `--loglevel=silent` | Don't log anything to console
|
||
|
|
| `debug`, `--debug` | Make Debug build (default=Release)
|
||
|
|
| `--release`, `--no-debug` | Make Release build
|
||
|
|
| `-C $dir`, `--directory=$dir` | Run command in different directory
|
||
|
|
| `--make=$make` | Override make command (e.g. gmake)
|
||
|
|
| `--thin=yes` | Enable thin static libraries
|
||
|
|
| `--arch=$arch` | Set target architecture (e.g. ia32)
|
||
|
|
| `--tarball=$path` | Get headers from a local tarball
|
||
|
|
| `--devdir=$path` | SDK download directory (default=~/.node-gyp)
|
||
|
|
| `--ensure` | Don't reinstall headers if already present
|
||
|
|
| `--dist-url=$url` | Download header tarball from custom URL
|
||
|
|
| `--proxy=$url` | Set HTTP proxy for downloading header tarball
|
||
|
|
| `--cafile=$cafile` | Override default CA chain (to download tarball)
|
||
|
|
| `--nodedir=$path` | Set the path to the node source code
|
||
|
|
| `--python=$path` | Set path to the python (2) binary
|
||
|
|
| `--msvs_version=$version` | Set Visual Studio version (win)
|
||
|
|
| `--solution=$solution` | Set Visual Studio Solution version (win)
|
||
|
|
|
||
|
|
|
||
|
|
Configuration
|
||
|
|
--------
|
||
|
|
|
||
|
|
__`node-gyp` responds to environment variables or `npm` configuration__
|
||
|
|
1. Environment variables take the form `npm_config_OPTION_NAME` for any of the
|
||
|
|
options listed above (dashes in option names should be replaced by underscores).
|
||
|
|
These work also when `node-gyp` is invoked directly:
|
||
|
|
`$ export npm_config_devdir=/tmp/.gyp`
|
||
|
|
or on Windows
|
||
|
|
`> set npm_config_devdir=c:\temp\.gyp`
|
||
|
|
2. As `npm` configuration, variables take the form `OPTION_NAME`.
|
||
|
|
This way only works when `node-gyp` is executed by `npm`:
|
||
|
|
`$ npm config set [--global] devdir /tmp/.gyp`
|
||
|
|
`$ npm i buffertools`
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
License
|
||
|
|
-------
|
||
|
|
|
||
|
|
(The MIT License)
|
||
|
|
|
||
|
|
Copyright (c) 2012 Nathan Rajlich <nathan@tootallnate.net>
|
||
|
|
|
||
|
|
Permission is hereby granted, free of charge, to any person obtaining
|
||
|
|
a copy of this software and associated documentation files (the
|
||
|
|
'Software'), to deal in the Software without restriction, including
|
||
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
||
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
||
|
|
permit persons to whom the Software is furnished to do so, subject to
|
||
|
|
the following conditions:
|
||
|
|
|
||
|
|
The above copyright notice and this permission notice shall be
|
||
|
|
included in all copies or substantial portions of the Software.
|
||
|
|
|
||
|
|
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
||
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||
|
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||
|
|
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||
|
|
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||
|
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||
|
|
|
||
|
|
|
||
|
|
[python-v2.7.10]: https://www.python.org/downloads/release/python-2710/
|
||
|
|
[msvc2013]: https://www.microsoft.com/en-gb/download/details.aspx?id=44914
|
||
|
|
[win7sdk]: https://www.microsoft.com/en-us/download/details.aspx?id=8279
|
||
|
|
[compiler update for the Windows SDK 7.1]: https://www.microsoft.com/en-us/download/details.aspx?id=4422
|