Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
.github/ | 12-May-2024 | - | 218 | 158 | ||
bin/ | 12-May-2024 | - | 141 | 112 | ||
docs/ | 12-May-2024 | - | 379 | 300 | ||
gyp/ | 12-May-2024 | - | 37,390 | 28,793 | ||
lib/ | 12-May-2024 | - | 2,840 | 2,174 | ||
node_modules/ | 12-May-2024 | - | 9,600 | 7,293 | ||
src/ | 12-May-2024 | - | 40 | 20 | ||
test/ | 12-May-2024 | - | 3,188 | 2,768 | ||
CHANGELOG.md | D | 12-May-2024 | 93.1 KiB | 827 | 623 | |
CONTRIBUTING.md | D | 12-May-2024 | 1.4 KiB | 35 | 26 | |
LICENSE | D | 12-May-2024 | 1.1 KiB | 25 | 20 | |
README.md | D | 12-May-2024 | 10.6 KiB | 260 | 184 | |
SECURITY.md | D | 12-May-2024 | 151 | 2 | 2 | |
addon.gypi | D | 12-May-2024 | 5.8 KiB | 205 | 197 | |
macOS_Catalina.md | D | 12-May-2024 | 6.5 KiB | 105 | 82 | |
macOS_Catalina_acid_test.sh | D | 12-May-2024 | 495 | 22 | 17 | |
package.json | D | 12-May-2024 | 1.2 KiB | 52 | 51 | |
update-gyp.py | D | 12-May-2024 | 2.3 KiB | 65 | 47 |
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