1# `node-gyp` - Node.js native addon build tool 2 3[![Travis CI](https://travis-ci.com/nodejs/node-gyp.svg?branch=master)](https://travis-ci.com/nodejs/node-gyp) 4[![Build Status](https://github.com/nodejs/node-gyp/workflows/Python_tests/badge.svg)](https://github.com/nodejs/node-gyp/actions?workflow=Python_tests) 5 6`node-gyp` is a cross-platform command-line tool written in Node.js for 7compiling native addon modules for Node.js. It contains a fork of the 8[gyp](https://gyp.gsrc.io) project that was previously used by the Chromium 9team, extended to support the development of Node.js native addons. 10 11Note that `node-gyp` is _not_ used to build Node.js itself. 12 13Multiple target versions of Node.js are supported (i.e. `0.8`, ..., `4`, `5`, `6`, 14etc.), regardless of what version of Node.js is actually installed on your system 15(`node-gyp` downloads the necessary development files or headers for the target version). 16 17## Features 18 19 * The same build commands work on any of the supported platforms 20 * Supports the targeting of different versions of Node.js 21 22## Installation 23 24You can install `node-gyp` using `npm`: 25 26``` bash 27$ npm install -g node-gyp 28``` 29 30Depending on your operating system, you will need to install: 31 32### On Unix 33 34 * Python v2.7, v3.5, v3.6, or v3.7 35 * `make` 36 * A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org) 37 38### On macOS 39 40 * Python v2.7, v3.5, v3.6, or v3.7 41 * [Xcode](https://developer.apple.com/xcode/download/) 42 * You also need to install the `XCode Command Line Tools` by running `xcode-select --install`. Alternatively, if you already have the full Xcode installed, you can find them under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`. This step will install `clang`, `clang++`, and `make`. 43 * If your Mac has been _upgraded_ to macOS Catalina (10.15), please read [macOS_Catalina.md](macOS_Catalina.md). 44 45### On Windows 46 47Install the current version of Python from the [Microsoft Store package](https://docs.python.org/3/using/windows.html#the-microsoft-store-package). 48 49#### Option 1 50 51Install 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). 52 53#### Option 2 54 55Install tools and configuration manually: 56 * Install Visual C++ Build Environment: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 57 (using "Visual C++ build tools" workload) or [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community) 58 (using the "Desktop development with C++" workload) 59 * Launch cmd, `npm config set msvs_version 2017` 60 61 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. 62 63 To target native ARM64 Node.js on Windows 10 on ARM, add the components "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64". 64 65### Configuring Python Dependency 66 67`node-gyp` requires that you have installed a compatible version of Python, one of: v2.7, v3.5, v3.6, 68or v3.7. If you have multiple Python versions installed, you can identify which Python 69version `node-gyp` should use in one of the following ways: 70 711. by setting the `--python` command-line option, e.g.: 72 73``` bash 74$ node-gyp <command> --python /path/to/executable/python 75``` 76 772. If `node-gyp` is called by way of `npm`, *and* you have multiple versions of 78Python installed, then you can set `npm`'s 'python' config key to the appropriate 79value: 80 81``` bash 82$ npm config set python /path/to/executable/python 83``` 84 853. If the `PYTHON` environment variable is set to the path of a Python executable, 86then that version will be used, if it is a compatible version. 87 884. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a 89Python executable, it will be used instead of any of the other configured or 90builtin Python search paths. If it's not a compatible version, no further 91searching will be done. 92 93## How to Use 94 95To compile your native addon, first go to its root directory: 96 97``` bash 98$ cd my_node_addon 99``` 100 101The next step is to generate the appropriate project build files for the current 102platform. Use `configure` for that: 103 104``` bash 105$ node-gyp configure 106``` 107 108Auto-detection fails for Visual C++ Build Tools 2015, so `--msvs_version=2015` 109needs to be added (not needed when run by npm as configured above): 110``` bash 111$ node-gyp configure --msvs_version=2015 112``` 113 114__Note__: The `configure` step looks for a `binding.gyp` file in the current 115directory to process. See below for instructions on creating a `binding.gyp` file. 116 117Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file 118(on Windows) in the `build/` directory. Next, invoke the `build` command: 119 120``` bash 121$ node-gyp build 122``` 123 124Now you have your compiled `.node` bindings file! The compiled bindings end up 125in `build/Debug/` or `build/Release/`, depending on the build mode. At this point, 126you can require the `.node` file with Node.js and run your tests! 127 128__Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or 129`-d`) switch when running either the `configure`, `build` or `rebuild` commands. 130 131## The `binding.gyp` file 132 133A `binding.gyp` file describes the configuration to build your module, in a 134JSON-like format. This file gets placed in the root of your package, alongside 135`package.json`. 136 137A barebones `gyp` file appropriate for building a Node.js addon could look like: 138 139```python 140{ 141 "targets": [ 142 { 143 "target_name": "binding", 144 "sources": [ "src/binding.cc" ] 145 } 146 ] 147} 148``` 149 150## Further reading 151 152Some additional resources for Node.js native addons and writing `gyp` configuration files: 153 154 * ["Going Native" a nodeschool.io tutorial](http://nodeschool.io/#goingnative) 155 * ["Hello World" node addon example](https://github.com/nodejs/node/tree/master/test/addons/hello-world) 156 * [gyp user documentation](https://gyp.gsrc.io/docs/UserDocumentation.md) 157 * [gyp input format reference](https://gyp.gsrc.io/docs/InputFormatReference.md) 158 * [*"binding.gyp" files out in the wild* wiki page](https://github.com/nodejs/node-gyp/wiki/%22binding.gyp%22-files-out-in-the-wild) 159 160## Commands 161 162`node-gyp` responds to the following commands: 163 164| **Command** | **Description** 165|:--------------|:--------------------------------------------------------------- 166| `help` | Shows the help dialog 167| `build` | Invokes `make`/`msbuild.exe` and builds the native addon 168| `clean` | Removes the `build` directory if it exists 169| `configure` | Generates project build files for the current platform 170| `rebuild` | Runs `clean`, `configure` and `build` all in a row 171| `install` | Installs Node.js header files for the given version 172| `list` | Lists the currently installed Node.js header versions 173| `remove` | Removes the Node.js header files for the given version 174 175 176## Command Options 177 178`node-gyp` accepts the following command options: 179 180| **Command** | **Description** 181|:----------------------------------|:------------------------------------------ 182| `-j n`, `--jobs n` | Run `make` in parallel. The value `max` will use all available CPU cores 183| `--target=v6.2.1` | Node.js version to build for (default is `process.version`) 184| `--silly`, `--loglevel=silly` | Log all progress to console 185| `--verbose`, `--loglevel=verbose` | Log most progress to console 186| `--silent`, `--loglevel=silent` | Don't log anything to console 187| `debug`, `--debug` | Make Debug build (default is `Release`) 188| `--release`, `--no-debug` | Make Release build 189| `-C $dir`, `--directory=$dir` | Run command in different directory 190| `--make=$make` | Override `make` command (e.g. `gmake`) 191| `--thin=yes` | Enable thin static libraries 192| `--arch=$arch` | Set target architecture (e.g. ia32) 193| `--tarball=$path` | Get headers from a local tarball 194| `--devdir=$path` | SDK download directory (default is OS cache directory) 195| `--ensure` | Don't reinstall headers if already present 196| `--dist-url=$url` | Download header tarball from custom URL 197| `--proxy=$url` | Set HTTP(S) proxy for downloading header tarball 198| `--noproxy=$urls` | Set urls to ignore proxies when downloading header tarball 199| `--cafile=$cafile` | Override default CA chain (to download tarball) 200| `--nodedir=$path` | Set the path to the node source code 201| `--python=$path` | Set path to the Python binary 202| `--msvs_version=$version` | Set Visual Studio version (Windows only) 203| `--solution=$solution` | Set Visual Studio Solution version (Windows only) 204 205## Configuration 206 207### Environment variables 208 209Use the form `npm_config_OPTION_NAME` for any of the command options listed 210above (dashes in option names should be replaced by underscores). 211 212For example, to set `devdir` equal to `/tmp/.gyp`, you would: 213 214Run this on Unix: 215 216```bash 217$ export npm_config_devdir=/tmp/.gyp 218``` 219 220Or this on Windows: 221 222```console 223> set npm_config_devdir=c:\temp\.gyp 224``` 225 226### `npm` configuration 227 228Use the form `OPTION_NAME` for any of the command options listed above. 229 230For example, to set `devdir` equal to `/tmp/.gyp`, you would run: 231 232```bash 233$ npm config set [--global] devdir /tmp/.gyp 234``` 235 236**Note:** Configuration set via `npm` will only be used when `node-gyp` 237is run via `npm`, not when `node-gyp` is run directly. 238 239## License 240 241`node-gyp` is available under the MIT license. See the [LICENSE 242file](LICENSE) for details. 243