source: trip-planner-front/node_modules/node-gyp/README.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 9.7 KB
Line 
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
5`node-gyp` is a cross-platform command-line tool written in Node.js for
6compiling native addon modules for Node.js. It contains a vendored copy of the
7[gyp-next](https://github.com/nodejs/gyp-next) project that was previously used
8by the Chromium team, extended to support the development of Node.js native addons.
9
10Note that `node-gyp` is _not_ used to build Node.js itself.
11
12Multiple target versions of Node.js are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
13etc.), regardless of what version of Node.js is actually installed on your system
14(`node-gyp` downloads the necessary development files or headers for the target version).
15
16## Features
17
18 * The same build commands work on any of the supported platforms
19 * Supports the targeting of different versions of Node.js
20
21## Installation
22
23You can install `node-gyp` using `npm`:
24
25``` bash
26$ npm install -g node-gyp
27```
28
29Depending on your operating system, you will need to install:
30
31### On Unix
32
33 * Python v2.7, v3.5, v3.6, v3.7, or v3.8
34 * `make`
35 * A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org)
36
37### On macOS
38
39**ATTENTION**: If your Mac has been _upgraded_ to macOS Catalina (10.15), please read [macOS_Catalina.md](macOS_Catalina.md).
40
41 * Python v2.7, v3.5, v3.6, v3.7, or v3.8
42 * [Xcode](https://developer.apple.com/xcode/download/)
43 * 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`.
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 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,
68v3.7, or v3.8. 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.
Note: See TracBrowser for help on using the repository browser.