diff options
Diffstat (limited to 'deps/npm/node_modules/node-gyp/README.md')
| -rw-r--r-- | deps/npm/node_modules/node-gyp/README.md | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/deps/npm/node_modules/node-gyp/README.md b/deps/npm/node_modules/node-gyp/README.md new file mode 100644 index 0000000000..a5c1325c71 --- /dev/null +++ b/deps/npm/node_modules/node-gyp/README.md @@ -0,0 +1,242 @@ +node-gyp +========= +### Node.js native addon build tool + +`node-gyp` is a cross-platform command-line tool written in Node.js for compiling +native addon modules for Node.js. It bundles the [gyp](https://gyp.gsrc.io) +project used by the Chromium team and takes away the pain of dealing with the +various differences in build platforms. It is the replacement to the `node-waf` +program which is removed for node `v0.8`. If you have a native addon for node that +still has a `wscript` file, then you should definitely add a `binding.gyp` file +to support the latest versions of node. + +Multiple target versions of node are supported (i.e. `0.8`, ..., `4`, `5`, `6`, +etc.), regardless of what version of node is actually installed on your system +(`node-gyp` downloads the necessary development files or headers for the target version). + +#### Features: + + * Easy to use, consistent interface + * Same commands to build your module on every platform + * Supports multiple target versions of Node + + +Installation +------------ + +You can install with `npm`: + +``` bash +$ npm install -g node-gyp +``` + +You will also need to install: + + * On Unix: + * `python` (`v2.7` recommended, `v3.x.x` is __*not*__ supported) + * `make` + * A proper C/C++ compiler toolchain, like [GCC](https://gcc.gnu.org) + * On Mac OS X: + * `python` (`v2.7` recommended, `v3.x.x` is __*not*__ supported) (already installed on Mac OS X) + * [Xcode](https://developer.apple.com/xcode/download/) + * You also need to install the `Command Line Tools` via Xcode. You can find this under the menu `Xcode -> Preferences -> Downloads` + * This step will install `gcc` and the related toolchain containing `make` + * On Windows: + * Option 1: Install all the required tools and configurations using Microsoft's [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) using `npm install --global --production windows-build-tools` from an elevated PowerShell or CMD.exe (run as Administrator). + * Option 2: Install tools and configuration manually: + * Visual C++ Build Environment: + * Option 1: Install [Visual C++ Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) using the **Default Install** option. + + * Option 2: Install [Visual Studio 2015](https://www.visualstudio.com/products/visual-studio-community-vs) (or modify an existing installation) and select *Common Tools for Visual C++* during setup. This also works with the free Community and Express for Desktop editions. + + > :bulb: [Windows Vista / 7 only] requires [.NET Framework 4.5.1](http://www.microsoft.com/en-us/download/details.aspx?id=40773) + + * Install [Python 2.7](https://www.python.org/downloads/) (`v3.x.x` is not supported), and run `npm config set python python2.7` (or see below for further instructions on specifying the proper Python version and path.) + * Launch cmd, `npm config set msvs_version 2015` + + 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. + +If you have multiple Python versions installed, you can identify which Python +version `node-gyp` uses by setting the '--python' variable: + +``` bash +$ node-gyp --python /path/to/python2.7 +``` + +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/python2.7 +``` + +Note that OS X is just a flavour of Unix and so needs `python`, `make`, and C/C++. +An easy way to obtain these is to install XCode from Apple, +and then use it to install the command line tools (under Preferences -> Downloads). + +How to Use +---------- + +To compile your native addon, first go to its root directory: + +``` bash +$ cd my_node_addon +``` + +The next step is to generate the appropriate project build files for the current +platform. Use `configure` for that: + +``` bash +$ node-gyp configure +``` + +Auto-detection fails for Visual C++ Build Tools 2015, so `--msvs_version=2015` +needs to be added (not needed when run by npm as configured above): +``` bash +$ node-gyp configure --msvs_version=2015 +``` + +__Note__: The `configure` step looks for the `binding.gyp` file in the current +directory to process. See below for instructions on creating the `binding.gyp` file. + +Now you will have either a `Makefile` (on Unix platforms) or a `vcxproj` file +(on Windows) in the `build/` directory. Next invoke the `build` command: + +``` bash +$ node-gyp build +``` + +Now you have your compiled `.node` bindings file! The compiled bindings end up +in `build/Debug/` or `build/Release/`, depending on the build mode. At this point +you can require the `.node` file with Node and run your tests! + +__Note:__ To create a _Debug_ build of the bindings file, pass the `--debug` (or +`-d`) switch when running either the `configure`, `build` or `rebuild` command. + + +The "binding.gyp" file +---------------------- + +Previously when node had `node-waf` you had to write a `wscript` file. The +replacement for that is the `binding.gyp` file, which describes the configuration +to build your module in a JSON-like format. This file gets placed in the root of +your package, alongside the `package.json` file. + +A barebones `gyp` file appropriate for building a node addon looks like: + +``` python +{ + "targets": [ + { + "target_name": "binding", + "sources": [ "src/binding.cc" ] + } + ] +} +``` + +Some additional resources for addons and writing `gyp` 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: + +| **Command** | **Description** +|:--------------|:--------------------------------------------------------------- +| `help` | Shows the help dialog +| `build` | Invokes `make`/`msbuild.exe` and builds the native addon +| `clean` | Removes the `build` directory if it exists +| `configure` | Generates project build files for the current platform +| `rebuild` | Runs `clean`, `configure` and `build` all in a row +| `install` | Installs node header files for the given version +| `list` | Lists the currently installed node header versions +| `remove` | Removes the node header files for the given version + + +Command Options +-------- + +`node-gyp` accepts the following command options: + +| **Command** | **Description** +|:----------------------------------|:------------------------------------------ +| `-j n`, `--jobs n` | Run make in parallel +| `--target=v6.2.1` | Node version to build for (default=process.version) +| `--silly`, `--loglevel=silly` | Log all progress to console +| `--verbose`, `--loglevel=verbose` | Log most progress to console +| `--silent`, `--loglevel=silent` | Don't log anything to console +| `debug`, `--debug` | Make Debug build (default=Release) +| `--release`, `--no-debug` | Make Release build +| `-C $dir`, `--directory=$dir` | Run command in different directory +| `--make=$make` | Override make command (e.g. gmake) +| `--thin=yes` | Enable thin static libraries +| `--arch=$arch` | Set target architecture (e.g. ia32) +| `--tarball=$path` | Get headers from a local tarball +| `--devdir=$path` | SDK download directory (default=~/.node-gyp) +| `--ensure` | Don't reinstall headers if already present +| `--dist-url=$url` | Download header tarball from custom URL +| `--proxy=$url` | Set HTTP proxy for downloading header tarball +| `--cafile=$cafile` | Override default CA chain (to download tarball) +| `--nodedir=$path` | Set the path to the node binary +| `--python=$path` | Set path to the python (2) binary +| `--msvs_version=$version` | Set Visual Studio version (win) +| `--solution=$solution` | Set Visual Studio Solution version (win) + + +Configuration +-------- + +__`node-gyp` responds to environment variables or `npm` configuration__ +1. Environment variables take the form `npm_config_OPTION_NAME` for any of the + options listed above (dashes in option names should be replaced by underscores). + These work also when `node-gyp` is invoked directly: + `$ export npm_config_devdir=/tmp/.gyp` + or on Windows + `> set npm_config_devdir=c:\temp\.gyp` +2. As `npm` configuration, variables take the form `OPTION_NAME`. + This way only works when `node-gyp` is executed by `npm`: + `$ npm config set [--global] devdir /tmp/.gyp` + `$ npm i buffertools` + + + +License +------- + +(The MIT License) + +Copyright (c) 2012 Nathan Rajlich <nathan@tootallnate.net> + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +'Software'), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +[python-v2.7.10]: https://www.python.org/downloads/release/python-2710/ +[msvc2013]: https://www.microsoft.com/en-gb/download/details.aspx?id=44914 +[win7sdk]: https://www.microsoft.com/en-us/download/details.aspx?id=8279 +[compiler update for the Windows SDK 7.1]: https://www.microsoft.com/en-us/download/details.aspx?id=4422 |