codekingpro/portable-devtools
115k
1# `node-gyp` - Node.js native addon build tool
2
3[](https://github.com/nodejs/node-gyp/actions?query=workflow%3ATests+branch%3Amain)
4
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 vendored copy of the
8[gyp-next](https://github.com/nodejs/gyp-next) project that was previously used
9by the Chromium team and extended to support the development of Node.js native
10addons.
11
12Note that `node-gyp` is _not_ used to build Node.js itself.
13
14All current and LTS target versions of Node.js are supported. Depending on 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. List of stable Node.js versions can be found on [Node.js website](https://nodejs.org/en/about/previous-releases).
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> [!Important]
25> Python >= v3.12 requires `node-gyp` >= v10
26
27You can install `node-gyp` using `npm`:
28
29``` bash
30npm install -g node-gyp
31```
32
33Depending on your operating system, you will need to install:
34
35### On Unix
36
37 * [A supported version of Python](https://devguide.python.org/versions/)
38 * `make`
39 * A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org)
40
41### On macOS
42
43 * [A supported version of Python](https://devguide.python.org/versions/)
44 * `Xcode Command Line Tools` which will install `clang`, `clang++`, and `make`.
45 * Install the `Xcode Command Line Tools` standalone by running `xcode-select --install`. -- OR --
46 * Alternatively, if you already have the [full Xcode installed](https://developer.apple.com/xcode/download/), you can install the Command Line Tools under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`.
47
48
49### On Windows
50
51Install tools with [Chocolatey](https://chocolatey.org):
52``` bash
53choco install python visualstudio2022-workload-vctools -y
54```
55
56Or install and configure Python and Visual Studio tools manually:
57
58 * Follow the instructions in [Using Python on Windows](https://docs.python.org/3/using/windows.html) to install
59 the current [version of Python](https://www.python.org/downloads/).
60
61 * Install Visual C++ Build Environment: For Visual Studio 2019 or later, use the `Desktop development with C++` workload from [Visual Studio Community](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community). For a version older than Visual Studio 2019, install [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) with the `Visual C++ build tools` option.
62
63 To target native ARM64 Node.js on Windows on ARM, add the components "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64".
64
65 To use the native ARM64 C++ compiler on Windows on ARM, ensure that you have Visual Studio 2022 [17.4 or later](https://devblogs.microsoft.com/visualstudio/arm64-visual-studio-is-officially-here/) installed.
66
67It's advised to install the following PowerShell module: [VSSetup](https://github.com/microsoft/vssetup.powershell) using `Install-Module VSSetup -Scope CurrentUser`.
68This will make Visual Studio detection logic use a more flexible and accessible method, avoiding PowerShell's `ConstrainedLanguage` mode.
69
70### Configuring Python Dependency
71
72`node-gyp` requires that you have installed a [supported version of Python](https://devguide.python.org/versions/).
73If you have multiple versions of Python installed, you can identify which version
74`node-gyp` should use in one of the following ways:
75
761. by setting the `--python` command-line option, e.g.:
77
78``` bash
79node-gyp <command> --python /path/to/executable/python
80```
81
822. If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
83Python installed, then you can set the `npm_config_python` environment variable
84to the appropriate path:
85``` bash
86export npm_config_python=/path/to/executable/python
87```
88 Or on Windows:
89```console
90py --list-paths # To see the installed Python versions
91set npm_config_python=C:\path\to\python.exe # CMD
92$Env:npm_config_python="C:\path\to\python.exe" # PowerShell
93```
94
953. If the `PYTHON` environment variable is set to the path of a Python executable,
96then that version will be used if it is a supported version.
97
984. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
99Python executable, it will be used instead of any of the other configured or
100built-in Python search paths. If it's not a compatible version, no further
101searching will be done.
102
103### Build for Third Party Node.js Runtimes
104
105When building modules for third-party Node.js runtimes like Electron, which have
106different build configurations from the official Node.js distribution, you
107should use `--dist-url` or `--nodedir` flags to specify the headers of the
108runtime to build for.
109
110Also when `--dist-url` or `--nodedir` flags are passed, node-gyp will use the
111`config.gypi` shipped in the headers distribution to generate build
112configurations, which is different from the default mode that would use the
113`process.config` object of the running Node.js instance.
114
115Some old versions of Electron shipped malformed `config.gypi` in their headers
116distributions, and you might need to pass `--force-process-config` to node-gyp
117to work around configuration errors.
118
119## How to Use
120
121To compile your native addon first go to its root directory:
122
123``` bash
124cd my_node_addon
125```
126
127The next step is to generate the appropriate project build files for the current
128platform. Use `configure` for that:
129
130``` bash
131node-gyp configure
132```
133
134Auto-detection fails for Visual C++ Build Tools 2015, so `--msvs_version=2015`
135needs to be added (not needed when run by npm as configured above):
136``` bash
137node-gyp configure --msvs_version=2015
138```
139
140__Note__: The `configure` step looks for a `binding.gyp` file in the current
141directory to process. See below for instructions on creating a `binding.gyp` file.
142
143Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file
144(on Windows) in the `build/` directory. Next, invoke the `build` command:
145
146``` bash
147node-gyp build
148```
149
150Now you have your compiled `.node` bindings file! The compiled bindings end up
151in `build/Debug/` or `build/Release/`, depending on the build mode. At this point,
152you can require the `.node` file with Node.js and run your tests!
153
154__Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or
155`-d`) switch when running either the `configure`, `build` or `rebuild` commands.
156
157## The `binding.gyp` file
158
159A `binding.gyp` file describes the configuration to build your module, in a
160JSON-like format. This file gets placed in the root of your package, alongside
161`package.json`.
162
163A barebones `gyp` file appropriate for building a Node.js addon could look like:
164
165```python
166{
167 "targets": [
168 {
169 "target_name": "binding",
170 "sources": [ "src/binding.cc" ]
171 }
172 ]
173}
174```
175
176## Further reading
177
178The **[docs](./docs/)** directory contains additional documentation on specific node-gyp topics that may be useful if you are experiencing problems installing or building addons using node-gyp.
179
180Some additional resources for Node.js native addons and writing `gyp` configuration files:
181
182 * ["Going Native" a nodeschool.io tutorial](http://nodeschool.io/#goingnative)
183 * ["Hello World" node addon example](https://github.com/nodejs/node/tree/main/test/addons/hello-world)
184 * [gyp user documentation](https://gyp.gsrc.io/docs/UserDocumentation.md)
185 * [gyp input format reference](https://gyp.gsrc.io/docs/InputFormatReference.md)
186 * [*"binding.gyp" files out in the wild* wiki page](./docs/binding.gyp-files-in-the-wild.md)
187
188## Commands
189
190`node-gyp` responds to the following commands:
191
192| **Command** | **Description**
193|:--------------|:---------------------------------------------------------------
194| `help` | Shows the help dialog
195| `build` | Invokes `make`/`msbuild.exe` and builds the native addon
196| `clean` | Removes the `build` directory if it exists
197| `configure` | Generates project build files for the current platform
198| `rebuild` | Runs `clean`, `configure` and `build` all in a row
199| `install` | Installs Node.js header files for the given version
200| `list` | Lists the currently installed Node.js header versions
201| `remove` | Removes the Node.js header files for the given version
202
203
204## Command Options
205
206`node-gyp` accepts the following command options:
207
208| **Command** | **Description**
209|:----------------------------------|:------------------------------------------
210| `-j n`, `--jobs n` | Run `make` in parallel. The value `max` will use all available CPU cores
211| `--target=v6.2.1` | Node.js version to build for (default is `process.version`)
212| `--silly`, `--loglevel=silly` | Log all progress to console
213| `--verbose`, `--loglevel=verbose` | Log most progress to console
214| `--silent`, `--loglevel=silent` | Don't log anything to console
215| `debug`, `--debug` | Make Debug build (default is `Release`)
216| `--release`, `--no-debug` | Make Release build
217| `-C $dir`, `--directory=$dir` | Run command in different directory
218| `--make=$make` | Override `make` command (e.g. `gmake`)
219| `--thin=yes` | Enable thin static libraries
220| `--arch=$arch` | Set target architecture (e.g. ia32)
221| `--tarball=$path` | Get headers from a local tarball
222| `--devdir=$path` | SDK download directory (default is OS cache directory)
223| `--ensure` | Don't reinstall headers if already present
224| `--dist-url=$url` | Download header tarball from custom URL
225| `--proxy=$url` | Set HTTP(S) proxy for downloading header tarball
226| `--noproxy=$urls` | Set urls to ignore proxies when downloading header tarball
227| `--cafile=$cafile` | Override default CA chain (to download tarball)
228| `--nodedir=$path` | Set the path to the node source code
229| `--python=$path` | Set path to the Python binary
230| `--msvs_version=$version` | Set Visual Studio version (Windows only)
231| `--solution=$solution` | Set Visual Studio Solution version (Windows only)
232| `--force-process-config` | Force using runtime's `process.config` object to generate `config.gypi` file
233
234## Configuration
235
236### package.json
237
238Use the `config` object in your package.json with each key in the form `node_gyp_OPTION_NAME`. Any of the command
239options listed above can be set (dashes in option names should be replaced by underscores).
240
241For example, to set `devdir` equal to `/tmp/.gyp`, your package.json would contain this:
242
243```json
244{
245 "config": {
246 "node_gyp_devdir": "/tmp/.gyp"
247 }
248}
249```
250
251### Environment variables
252
253Use the form `npm_package_config_node_gyp_OPTION_NAME` for any of the command options listed
254above (dashes in option names should be replaced by underscores).
255
256For example, to set `devdir` equal to `/tmp/.gyp`, you would:
257
258Run this on Unix:
259
260```bash
261export npm_package_config_node_gyp_devdir=/tmp/.gyp
262```
263
264Or this on Windows:
265
266```console
267set npm_package_config_node_gyp_devdir=c:\temp\.gyp
268```
269
270Note that in versions of npm before v11 it was possible to use the prefix `npm_config_` for
271environment variables. This was deprecated in npm@11 and will be removed in npm@12 so it
272is recommended to convert your environment variables to the above format.
273
274### `npm` configuration for npm versions before v9
275
276Use the form `OPTION_NAME` for any of the command options listed above.
277
278For example, to set `devdir` equal to `/tmp/.gyp`, you would run:
279
280```bash
281npm config set [--global] devdir /tmp/.gyp
282```
283
284**Note:** Configuration set via `npm` will only be used when `node-gyp`
285is run via `npm`, not when `node-gyp` is run directly.
286
287## License
288
289`node-gyp` is available under the MIT license. See the [LICENSE
290file](LICENSE) for details.
291