Skip to content

Commit

Permalink
doc: adjustments to the README.md for new users
Browse files Browse the repository at this point in the history
PR-URL: #1919
Reviewed-By: Rod Vagg <rod@vagg.org>
  • Loading branch information
Dan Pike authored and rvagg committed Nov 18, 2019
1 parent b7c8233 commit cdec002
Showing 1 changed file with 18 additions and 20 deletions.
38 changes: 18 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,7 @@
`node-gyp` is a cross-platform command-line tool written in Node.js for
compiling native addon modules for Node.js. It contains a fork of the
[gyp](https://gyp.gsrc.io) project that was previously used by the Chromium
team and takes away the pain of dealing with the various differences in build
platforms.
team, extended to support the development of Node.js native addons.

Note that `node-gyp` is _not_ used to build Node.js itself.

Expand All @@ -14,23 +13,18 @@ etc.), regardless of what version of Node.js is actually installed on your syste

## Features

* Easy to use, consistent interface
* Same commands to build your module on every platform
* Supports multiple target versions of Node.js
* The same build commands work on any of the supported platforms
* Supports the targetting of different versions of Node.js

## Installation

You can install with `npm`:
You can install `node-gyp` using `npm`:

``` bash
$ npm install -g node-gyp
```

You will also need to install:

NOTE: node-gyp is compatible with Python v2.7, v3.5, v3.6, or v3.7. If the
Python to use is not explicitly configured (see "Configuring Python Dependency"
below) it will attempt to find a compatible Python executable.
Depending on your operating system, you will need to install:

### On Unix

Expand Down Expand Up @@ -67,27 +61,30 @@ Install tools and configuration manually:

### Configuring Python Dependency

If you have multiple Python versions installed, you can identify which Python
version `node-gyp` uses by setting the `--python` variable:
`node-gyp` requires that you have installed a compatible version of Python, one of: v2.7, v3.5, v3.6,
or v3.7. If you have multiple Python versions installed, you can identify which Python
version `node-gyp` should use in one of the following ways:

1. by setting the `--python` command-line option, e.g.:

``` bash
$ node-gyp <command> --python /path/to/executable/python
```

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

``` bash
$ npm config set python /path/to/executable/python
```

If the `PYTHON` environment variable is set to the path of a Python executable,
it will be used if it is a compatible Python.
3. If the `PYTHON` environment variable is set to the path of a Python executable,
then that version will be used, if it is a compatible version.

If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
4. If the `NODE_GYP_FORCE_PYTHON` environment variable is set to the path of a
Python executable, it will be used instead of any of the other configured or
builtin Python search paths. If its not a compatible Python, no further
builtin Python search paths. If it's not a compatible version, no further
searching will be done.

## How to Use
Expand Down Expand Up @@ -147,15 +144,16 @@ A barebones `gyp` file appropriate for building a Node.js addon could look like:
}
```

Some additional resources for addons and writing `gyp` files:
## Further reading

Some additional resources for Node.js native addons and writing `gyp` configuration files:

* ["Going Native" a nodeschool.io tutorial](http://nodeschool.io/#goingnative)
* ["Hello World" node addon example](https://github.com/nodejs/node/tree/master/test/addons/hello-world)
* [gyp user documentation](https://gyp.gsrc.io/docs/UserDocumentation.md)
* [gyp input format reference](https://gyp.gsrc.io/docs/InputFormatReference.md)
* [*"binding.gyp" files out in the wild* wiki page](https://github.com/nodejs/node-gyp/wiki/%22binding.gyp%22-files-out-in-the-wild)


## Commands

`node-gyp` responds to the following commands:
Expand Down

0 comments on commit cdec002

Please sign in to comment.