Permalink
Browse files

README++

  • Loading branch information...
1 parent 568cadb commit 11bd07942e49333b32ab042ed9722dbaabfcc699 @TooTallNate committed Jul 10, 2012
Showing with 35 additions and 73 deletions.
  1. +33 −70 README.md
  2. +2 −3 package.json
View
103 README.md
@@ -1,49 +1,19 @@
node-bindings
=============
-### Helper module for loading your native module's bindings
+### Helper module for loading your native module's .node file
-This is a helper module for authors of Node.js native addon modules. In node >=
-0.7.0, it is encouraged to statically precompile your native addons for your
-various supported platforms and architectures, rather than depend on your users
-to do that. This adds two new burdens on the developer that we now need to
-consider while writing our module:
+This is a helper module for authors of Node.js native addon modules.
+It is basically the "swiss army knife" of `require()`ing your native module's
+`.node` file.
- 1. You now have to compile the bindings yourself, before publishing the module.
- 2. You now have to figure out which version of the bindings to load at runtime.
+Throughout the course of Node's native addon history, addons have ended up being
+compiled in a variety of different places, depending on which build tool and which
+version of node was used. To make matters worse, now the _gyp_ build tool can
+produce either a _Release_ or _Debug_ build, each being built into different
+locations.
-`node-bindings` attempts to solve probelm `#2`.
-
-This module solves the organizational problem of how to store these bindings
-files with a simple directory convention:
-
-```
-<module_root>/compiled/<node_version>/<platform>/<arch>/bindings.node
-```
-
-So for example, on a 32-bit Windows platform, running node `v0.6.9`, the
-`bindings.node` file should be placed in:
-
-```
-<module_root>/compiled/0.6/win32/ia32/bindings.node
-```
-
-On 64-bit Mac OS X, running node `v0.7.1`, then the bindings file should be
-placed in:
-
-```
-<module_root>/compiled/0.7/darwin/x64/bindings.node
-```
-
-For reference, the calculations for the various parts that makes up the require
-path are:
-
- * `<module_root>` - The directory where `package.json` is found is the root.
- * `<platform>` - `process.platform`
- * `<arch>` - `process.arch`
- * `<node_version>` - `parseFloat(process.versions.node)`
-
-The default "compiled" directory is `compiled` and the default name of every
-"bindings" file is `bindings.node`. This is configurable if you'd like.
+This module checks _all_ the possible locations that a native addon would be built
+at, and returns the first one that loads successfully.
Installation
@@ -55,6 +25,8 @@ Install with `npm`:
$ npm install bindings
```
+Or add it to the `"dependencies"` section of your _package.json_ file.
+
Example
-------
@@ -63,49 +35,40 @@ Example
and architecture is as simple as:
``` js
-var bindings = require('bindings')()
+var bindings = require('bindings')('mybindings.node')
// Use your bindings defined in your C files
bindings.your_c_function()
```
-You can specify the name of the bindings file if you desire:
-
-``` js
-var bindings = require('bindings')('my_bindings')
-```
-
-Or you can pass in an options Object for full configuration:
-
-
-``` js
-var bindings = require('bindings')({
- bindings: 'my_bindings'
- , compiled: 'builddir'
-})
-```
Nice Error Output
-----------------
+When the `.node` file could not be loaded, `node-bindings` throws an Error with
+a nice error message telling you exactly what was tried.
+
```
Error: Could not load the bindings file. Tried:
- -> /Users/nrajlich/node-ffi/out/Debug/ffi_bindings.node
- -> /Users/nrajlich/node-ffi/Debug/ffi_bindings.node
- -> /Users/nrajlich/node-ffi/out/Release/ffi_bindings.node
- -> /Users/nrajlich/node-ffi/Release/ffi_bindings.node
- -> /Users/nrajlich/node-ffi/compiled/0.6/darwin/x64/ffi_bindings.node
- -> /Users/nrajlich/node-ffi/build/Release/ffi_bindings.node
- -> /Users/nrajlich/node-ffi/build/default/ffi_bindings.node
- at bindings (/Users/nrajlich/node-ffi/node_modules/bindings/bindings.js:80:13)
- at Object.<anonymous> (/Users/nrajlich/node-ffi/lib/ffi.js:3:34)
- at Module._compile (module.js:441:26)
- at Object..js (module.js:459:10)
- at Module.load (module.js:348:31)
- at Function._load (module.js:308:12)
+ → /Users/nrajlich/ref/build/binding.node
+ → /Users/nrajlich/ref/build/Debug/binding.node
+ → /Users/nrajlich/ref/build/Release/binding.node
+ → /Users/nrajlich/ref/out/Debug/binding.node
+ → /Users/nrajlich/ref/Debug/binding.node
+ → /Users/nrajlich/ref/out/Release/binding.node
+ → /Users/nrajlich/ref/Release/binding.node
+ → /Users/nrajlich/ref/build/default/binding.node
+ → /Users/nrajlich/ref/compiled/0.8.2/darwin/x64/binding.node
+ at bindings (/Users/nrajlich/ref/node_modules/bindings/bindings.js:84:13)
+ at Object.<anonymous> (/Users/nrajlich/ref/lib/ref.js:5:47)
+ at Module._compile (module.js:449:26)
+ at Object.Module._extensions..js (module.js:467:10)
+ at Module.load (module.js:356:32)
+ at Function.Module._load (module.js:312:12)
...
```
+
License
-------
View
@@ -1,9 +1,8 @@
{ "name": "bindings"
-, "description": "Helper module for loading your native module's bindings"
-, "keywords": [ "native", "addon", "bindings", "gyp", "waf" ]
+, "description": "Helper module for loading your native module's .node file"
+, "keywords": [ "native", "addon", "bindings", "gyp", "waf", "c", "c++" ]
, "version": "1.0.0"
, "author": "Nathan Rajlich <nathan@tootallnate.net> (http://tootallnate.net)"
, "repository": { "type": "git", "url": "git://github.com/TooTallNate/node-bindings.git" }
, "main": "./bindings.js"
-, "engines": { "node": "*" }
}

0 comments on commit 11bd079

Please sign in to comment.