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
|
7 | compiling 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
|
9 | team, extended to support the development of Node.js native addons.
|
10 |
|
11 | Note that `node-gyp` is _not_ used to build Node.js itself.
|
12 |
|
13 | Multiple target versions of Node.js are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
|
14 | etc.), 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 |
|
24 | You can install `node-gyp` using `npm`:
|
25 |
|
26 | ``` bash
|
27 | $ npm install -g node-gyp
|
28 | ```
|
29 |
|
30 | Depending 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 |
|
47 | Install 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 |
|
51 | 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).
|
52 |
|
53 | #### Option 2
|
54 |
|
55 | Install 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,
|
68 | or v3.7. If you have multiple Python versions installed, you can identify which Python
|
69 | version `node-gyp` should use in one of the following ways:
|
70 |
|
71 | 1. by setting the `--python` command-line option, e.g.:
|
72 |
|
73 | ``` bash
|
74 | $ node-gyp <command> --python /path/to/executable/python
|
75 | ```
|
76 |
|
77 | 2. If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
|
78 | Python installed, then you can set `npm`'s 'python' config key to the appropriate
|
79 | value:
|
80 |
|
81 | ``` bash
|
82 | $ npm config set python /path/to/executable/python
|
83 | ```
|
84 |
|
85 | 3. If the `PYTHON` environment variable is set to the path of a Python executable,
|
86 | then that version will be used, if it is a compatible version.
|
87 |
|
88 | 4. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
|
89 | Python executable, it will be used instead of any of the other configured or
|
90 | builtin Python search paths. If it's not a compatible version, no further
|
91 | searching will be done.
|
92 |
|
93 | ## How to Use
|
94 |
|
95 | To compile your native addon, first go to its root directory:
|
96 |
|
97 | ``` bash
|
98 | $ cd my_node_addon
|
99 | ```
|
100 |
|
101 | The next step is to generate the appropriate project build files for the current
|
102 | platform. Use `configure` for that:
|
103 |
|
104 | ``` bash
|
105 | $ node-gyp configure
|
106 | ```
|
107 |
|
108 | Auto-detection fails for Visual C++ Build Tools 2015, so `--msvs_version=2015`
|
109 | needs 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
|
115 | directory to process. See below for instructions on creating a `binding.gyp` file.
|
116 |
|
117 | Now 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 |
|
124 | Now you have your compiled `.node` bindings file! The compiled bindings end up
|
125 | in `build/Debug/` or `build/Release/`, depending on the build mode. At this point,
|
126 | you 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 |
|
133 | A `binding.gyp` file describes the configuration to build your module, in a
|
134 | JSON-like format. This file gets placed in the root of your package, alongside
|
135 | `package.json`.
|
136 |
|
137 | A 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 |
|
152 | Some 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 |
|
209 | Use the form `npm_config_OPTION_NAME` for any of the command options listed
|
210 | above (dashes in option names should be replaced by underscores).
|
211 |
|
212 | For example, to set `devdir` equal to `/tmp/.gyp`, you would:
|
213 |
|
214 | Run this on Unix:
|
215 |
|
216 | ```bash
|
217 | $ export npm_config_devdir=/tmp/.gyp
|
218 | ```
|
219 |
|
220 | Or this on Windows:
|
221 |
|
222 | ```console
|
223 | > set npm_config_devdir=c:\temp\.gyp
|
224 | ```
|
225 |
|
226 | ### `npm` configuration
|
227 |
|
228 | Use the form `OPTION_NAME` for any of the command options listed above.
|
229 |
|
230 | For 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`
|
237 | is 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
|
242 | file](LICENSE) for details.
|