Permalink
Browse files

README++

  • Loading branch information...
1 parent 7ea1397 commit 2f0ffbe3e261bec6ddd3d3527350ed43b27ee6fd @TooTallNate TooTallNate committed Feb 3, 2012
Showing with 65 additions and 7 deletions.
  1. +65 −7 README.md
View
@@ -3,23 +3,78 @@ 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. Multiple target versions of node are supported
-(i.e. `0.7`, `0.8`, `1.0`, etc.).
+native addon modules for Node.js, which takes away the pain of dealing with the
+various differences in build platforms.
-Installation
-------------
+Multiple target versions of node are supported (i.e. `0.7`, `0.8`, `1.0`, etc.),
+even if those versions of node are not installed on your system (`node-gyp`
+downloads the necessary development files for the target version).
-Install with `npm`:
+#### Features:
+
+ * Easy to use, consistent interface
+ * Same commands to build your module on every platform
+ * Supports multiple target versions of Node
+
+
+How to Use
+----------
+
+The first step is to install. With `npm`, invoke:
``` bash
$ npm install -g node-gyp
```
+To compile your native addon, first go to its root directory:
-Usage
--------
+``` bash
+$ cd my_node_addon
+```
+
+From here, you can invoke the `node-gyp` executable. The next step is to generate
+the appropriate project build files for the current platform. Use `configure` for
+that:
+
+``` bash
+$ node-gyp configure --target=0.7
+```
+
+After that command you will have either a `Makefile` (on Unix platforms) or a
+`vcxproj` file (on Windows) in the current directory. Next invoke the `build`
+step:
+
+``` bash
+$ node-gyp build
+```
+
+Now you have your compiled `.node` bindings file! The compiled bindings end up in
+`out/Debug` or `out/Release`, depending on the build mode. At this point you can
+require the `.node` file with Node and run your tests!
+
+-------------------
+__(Optional)__ Copy the compiled bindings into an appropriate directory for
+runtime loading detection (with [node-bindings][]), using the `copy` command:
+
+``` bash
+$ node-gyp copy
+```
+So for example, if you are on a 64-bit OS X machine and your target node version
+is `0.7`, then the `copy` command above would move the bindings from
+`out/Release/bindings.gyp` to `compiled/0.7/darwin/x64/bindings.node`.
+
+
+Commands
+--------
+
+`node-gyp` responds to the following commands:
+
+ * `configure` - Generates project build files for the current platform
+ * `build` - Invokes `make`/`msbuild.exe` and builds the native addon
+ * `copy` - Copies a compiled bindings to an appropriate dir for runtime detection
+ * `install` - Installs node developmenet files for the given version
License
@@ -47,3 +102,6 @@ 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.
+
+
+[node-bindings]: https://github.com/TooTallNate/node-bindings

0 comments on commit 2f0ffbe

Please sign in to comment.