Skip to content

Commit c5e9802

Browse files
maclover7maclover7
authored
doc: lint README.md
Fixes grammar, removes extra lines and spaces, etc. Also removes a few references to `node-waf`, which was removed ~6 years ago now. Happy to add back if people still need that information. PR-URL: #1498 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Richard Lau <[email protected]>
1 parent 50b8734 commit c5e9802

1 file changed

Lines changed: 72 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 72 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,21 @@
1-
node-gyp
2-
=========
3-
## Node.js native addon build tool
1+
# `node-gyp` - Node.js native addon build tool
42

53
`node-gyp` is a cross-platform command-line tool written in Node.js for compiling
6-
native addon modules for Node.js. It bundles the [gyp](https://gyp.gsrc.io)
4+
native addon modules for Node.js. It bundles the [gyp](https://gyp.gsrc.io)
75
project used by the Chromium team and takes away the pain of dealing with the
8-
various differences in build platforms. It is the replacement to the `node-waf`
9-
program which is removed for node `v0.8`. If you have a native addon for node that
10-
still has a `wscript` file, then you should definitely add a `binding.gyp` file
11-
to support the latest versions of node.
6+
various differences in build platforms.
127

13-
Multiple target versions of node are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
14-
etc.), regardless of what version of node is actually installed on your system
8+
Multiple target versions of Node.js are supported (i.e. `0.8`, ..., `4`, `5`, `6`,
9+
etc.), regardless of what version of Node.js is actually installed on your system
1510
(`node-gyp` downloads the necessary development files or headers for the target version).
1611

1712
## Features
1813

1914
* Easy to use, consistent interface
2015
* Same commands to build your module on every platform
21-
* Supports multiple target versions of Node
16+
* Supports multiple target versions of Node.js
2217

23-
24-
Installation
25-
------------
18+
## Installation
2619

2720
You can install with `npm`:
2821

@@ -80,16 +73,15 @@ version `node-gyp` uses by setting the '--python' variable:
8073
$ node-gyp --python /path/to/python2.7
8174
```
8275

83-
If `node-gyp` is called by way of `npm` *and* you have multiple versions of
76+
If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
8477
Python installed, then you can set `npm`'s 'python' config key to the appropriate
8578
value:
8679

8780
``` bash
8881
$ npm config set python /path/to/executable/python2.7
8982
```
9083

91-
How to Use
92-
----------
84+
## How to Use
9385

9486
To compile your native addon, first go to its root directory:
9587

@@ -110,33 +102,30 @@ needs to be added (not needed when run by npm as configured above):
110102
$ node-gyp configure --msvs_version=2015
111103
```
112104

113-
__Note__: The `configure` step looks for the `binding.gyp` file in the current
114-
directory to process. See below for instructions on creating the `binding.gyp` file.
105+
__Note__: The `configure` step looks for a `binding.gyp` file in the current
106+
directory to process. See below for instructions on creating a `binding.gyp` file.
115107

116108
Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file
117-
(on Windows) in the `build/` directory. Next invoke the `build` command:
109+
(on Windows) in the `build/` directory. Next, invoke the `build` command:
118110

119111
``` bash
120112
$ node-gyp build
121113
```
122114

123115
Now you have your compiled `.node` bindings file! The compiled bindings end up
124-
in `build/Debug/` or `build/Release/`, depending on the build mode. At this point
125-
you can require the `.node` file with Node and run your tests!
116+
in `build/Debug/` or `build/Release/`, depending on the build mode. At this point,
117+
you can require the `.node` file with Node.js and run your tests!
126118

127119
__Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or
128-
`-d`) switch when running either the `configure`, `build` or `rebuild` command.
129-
120+
`-d`) switch when running either the `configure`, `build` or `rebuild` commands.
130121

131-
The "binding.gyp" file
132-
----------------------
122+
## The `binding.gyp` file
133123

134-
Previously when node had `node-waf` you had to write a `wscript` file. The
135-
replacement for that is the `binding.gyp` file, which describes the configuration
136-
to build your module in a JSON-like format. This file gets placed in the root of
137-
your package, alongside the `package.json` file.
124+
A `binding.gyp` file describes the configuration to build your module, in a
125+
JSON-like format. This file gets placed in the root of your package, alongside
126+
`package.json`.
138127

139-
A barebones `gyp` file appropriate for building a node addon looks like:
128+
A barebones `gyp` file appropriate for building a Node.js addon could look like:
140129

141130
``` python
142131
{
@@ -158,8 +147,7 @@ Some additional resources for addons and writing `gyp` files:
158147
* [*"binding.gyp" files out in the wild* wiki page](https://github.com/nodejs/node-gyp/wiki/%22binding.gyp%22-files-out-in-the-wild)
159148

160149

161-
Commands
162-
--------
150+
## Commands
163151

164152
`node-gyp` responds to the following commands:
165153

@@ -170,86 +158,74 @@ Commands
170158
| `clean` | Removes the `build` directory if it exists
171159
| `configure` | Generates project build files for the current platform
172160
| `rebuild` | Runs `clean`, `configure` and `build` all in a row
173-
| `install` | Installs node header files for the given version
174-
| `list` | Lists the currently installed node header versions
175-
| `remove` | Removes the node header files for the given version
161+
| `install` | Installs Node.js header files for the given version
162+
| `list` | Lists the currently installed Node.js header versions
163+
| `remove` | Removes the Node.js header files for the given version
176164

177165

178-
Command Options
179-
--------
166+
## Command Options
180167

181168
`node-gyp` accepts the following command options:
182169

183170
| **Command** | **Description**
184171
|:----------------------------------|:------------------------------------------
185-
| `-j n`, `--jobs n` | Run make in parallel
186-
| `--target=v6.2.1` | Node version to build for (default=process.version)
172+
| `-j n`, `--jobs n` | Run `make` in parallel
173+
| `--target=v6.2.1` | Node.js version to build for (default is `process.version`)
187174
| `--silly`, `--loglevel=silly` | Log all progress to console
188175
| `--verbose`, `--loglevel=verbose` | Log most progress to console
189176
| `--silent`, `--loglevel=silent` | Don't log anything to console
190-
| `debug`, `--debug` | Make Debug build (default=Release)
177+
| `debug`, `--debug` | Make Debug build (default is `Release`)
191178
| `--release`, `--no-debug` | Make Release build
192179
| `-C $dir`, `--directory=$dir` | Run command in different directory
193-
| `--make=$make` | Override make command (e.g. gmake)
180+
| `--make=$make` | Override `make` command (e.g. `gmake`)
194181
| `--thin=yes` | Enable thin static libraries
195182
| `--arch=$arch` | Set target architecture (e.g. ia32)
196183
| `--tarball=$path` | Get headers from a local tarball
197-
| `--devdir=$path` | SDK download directory (default=~/.node-gyp)
184+
| `--devdir=$path` | SDK download directory (default is `~/.node-gyp`)
198185
| `--ensure` | Don't reinstall headers if already present
199186
| `--dist-url=$url` | Download header tarball from custom URL
200187
| `--proxy=$url` | Set HTTP proxy for downloading header tarball
201188
| `--cafile=$cafile` | Override default CA chain (to download tarball)
202189
| `--nodedir=$path` | Set the path to the node source code
203-
| `--python=$path` | Set path to the python (2) binary
204-
| `--msvs_version=$version` | Set Visual Studio version (win)
205-
| `--solution=$solution` | Set Visual Studio Solution version (win)
206-
207-
208-
Configuration
209-
--------
210-
211-
__`node-gyp` responds to environment variables or `npm` configuration__
212-
1. Environment variables take the form `npm_config_OPTION_NAME` for any of the
213-
options listed above (dashes in option names should be replaced by underscores).
214-
These work also when `node-gyp` is invoked directly:
215-
`$ export npm_config_devdir=/tmp/.gyp`
216-
or on Windows
217-
`> set npm_config_devdir=c:\temp\.gyp`
218-
2. As `npm` configuration, variables take the form `OPTION_NAME`.
219-
This way only works when `node-gyp` is executed by `npm`:
220-
`$ npm config set [--global] devdir /tmp/.gyp`
221-
`$ npm i buffertools`
222-
223-
224-
225-
License
226-
-------
227-
228-
(The MIT License)
229-
230-
Copyright (c) 2012 Nathan Rajlich &lt;[email protected]&gt;
231-
232-
Permission is hereby granted, free of charge, to any person obtaining
233-
a copy of this software and associated documentation files (the
234-
'Software'), to deal in the Software without restriction, including
235-
without limitation the rights to use, copy, modify, merge, publish,
236-
distribute, sublicense, and/or sell copies of the Software, and to
237-
permit persons to whom the Software is furnished to do so, subject to
238-
the following conditions:
239-
240-
The above copyright notice and this permission notice shall be
241-
included in all copies or substantial portions of the Software.
242-
243-
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
244-
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
245-
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
246-
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
247-
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
248-
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
249-
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
250-
251-
252-
[python-v2.7.10]: https://www.python.org/downloads/release/python-2710/
253-
[msvc2013]: https://www.microsoft.com/en-gb/download/details.aspx?id=44914
254-
[win7sdk]: https://www.microsoft.com/en-us/download/details.aspx?id=8279
255-
[compiler update for the Windows SDK 7.1]: https://www.microsoft.com/en-us/download/details.aspx?id=4422
190+
| `--python=$path` | Set path to the Python 2 binary
191+
| `--msvs_version=$version` | Set Visual Studio version (Windows only)
192+
| `--solution=$solution` | Set Visual Studio Solution version (Windows only)
193+
194+
## Configuration
195+
196+
### Environment variables
197+
198+
Use the form `npm_config_OPTION_NAME` for any of the command options listed
199+
above (dashes in option names should be replaced by underscores).
200+
201+
For example, to set `devdir` equal to `/tmp/.gyp`, you would:
202+
203+
Run this on Unix:
204+
205+
```bash
206+
$ export npm_config_devdir=/tmp/.gyp
207+
```
208+
209+
Or this on Windows:
210+
211+
```console
212+
> set npm_config_devdir=c:\temp\.gyp
213+
```
214+
215+
### `npm` configuration
216+
217+
Use the form `OPTION_NAME` for any of the command options listed above.
218+
219+
For example, to set `devdir` equal to `/tmp/.gyp`, you would run:
220+
221+
```bash
222+
$ npm config set [--global] devdir /tmp/.gyp
223+
```
224+
225+
**Note:** Configuration set via `npm` will only be used when `node-gyp`
226+
is run via `npm`, not when `node-gyp` is run directly.
227+
228+
## License
229+
230+
`node-gyp` is available under the MIT license. See the [LICENSE
231+
file](LICENSE) for details.

0 commit comments

Comments
 (0)