• Home
Name
Date
Size
#Lines
LOC

..--

.github/12-May-2024-218158

bin/12-May-2024-141112

docs/12-May-2024-379300

gyp/12-May-2024-37,39028,793

lib/12-May-2024-2,8402,174

node_modules/12-May-2024-9,6007,293

src/12-May-2024-4020

test/12-May-2024-3,1882,768

CHANGELOG.mdD12-May-202493.1 KiB827623

CONTRIBUTING.mdD12-May-20241.4 KiB3526

LICENSED12-May-20241.1 KiB2520

README.mdD12-May-202410.6 KiB260184

SECURITY.mdD12-May-2024151 22

addon.gypiD12-May-20245.8 KiB205197

macOS_Catalina.mdD12-May-20246.5 KiB10582

macOS_Catalina_acid_test.shD12-May-2024495 2217

package.jsonD12-May-20241.2 KiB5251

update-gyp.pyD12-May-20242.3 KiB6547

README.md

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