Skip to content

Commit 3e64c78

Browse files
maclover7rvagg
maclover7
authored and
rvagg
committed
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 41f2b23 commit 3e64c78

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

@@ -69,16 +62,15 @@ version `node-gyp` uses by setting the '--python' variable:
6962
$ node-gyp --python /path/to/python2.7
7063
```
7164

72-
If `node-gyp` is called by way of `npm` *and* you have multiple versions of
65+
If `node-gyp` is called by way of `npm`, *and* you have multiple versions of
7366
Python installed, then you can set `npm`'s 'python' config key to the appropriate
7467
value:
7568

7669
``` bash
7770
$ npm config set python /path/to/executable/python2.7
7871
```
7972

80-
How to Use
81-
----------
73+
## How to Use
8274

8375
To compile your native addon, first go to its root directory:
8476

@@ -99,33 +91,30 @@ needs to be added (not needed when run by npm as configured above):
9991
$ node-gyp configure --msvs_version=2015
10092
```
10193

102-
__Note__: The `configure` step looks for the `binding.gyp` file in the current
103-
directory to process. See below for instructions on creating the `binding.gyp` file.
94+
__Note__: The `configure` step looks for a `binding.gyp` file in the current
95+
directory to process. See below for instructions on creating a `binding.gyp` file.
10496

10597
Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file
106-
(on Windows) in the `build/` directory. Next invoke the `build` command:
98+
(on Windows) in the `build/` directory. Next, invoke the `build` command:
10799

108100
``` bash
109101
$ node-gyp build
110102
```
111103

112104
Now you have your compiled `.node` bindings file! The compiled bindings end up
113-
in `build/Debug/` or `build/Release/`, depending on the build mode. At this point
114-
you can require the `.node` file with Node and run your tests!
105+
in `build/Debug/` or `build/Release/`, depending on the build mode. At this point,
106+
you can require the `.node` file with Node.js and run your tests!
115107

116108
__Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or
117-
`-d`) switch when running either the `configure`, `build` or `rebuild` command.
118-
109+
`-d`) switch when running either the `configure`, `build` or `rebuild` commands.
119110

120-
The "binding.gyp" file
121-
----------------------
111+
## The `binding.gyp` file
122112

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

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

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

149138

150-
Commands
151-
--------
139+
## Commands
152140

153141
`node-gyp` responds to the following commands:
154142

@@ -159,86 +147,74 @@ Commands
159147
| `clean` | Removes the `build` directory if it exists
160148
| `configure` | Generates project build files for the current platform
161149
| `rebuild` | Runs `clean`, `configure` and `build` all in a row
162-
| `install` | Installs node header files for the given version
163-
| `list` | Lists the currently installed node header versions
164-
| `remove` | Removes the node header files for the given version
150+
| `install` | Installs Node.js header files for the given version
151+
| `list` | Lists the currently installed Node.js header versions
152+
| `remove` | Removes the Node.js header files for the given version
165153

166154

167-
Command Options
168-
--------
155+
## Command Options
169156

170157
`node-gyp` accepts the following command options:
171158

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

0 commit comments

Comments
 (0)