Rust Bindings
An npm package that automates the process of building native Node modules in Rust.
Example
See the nanny-demo repository for a simple but complete example of a native Rust module built with rust-bindings
.
Usage
Project Structure
Set up your project as both a node package and a Rust project. Rust source files go in src
as usual and Node source files go wherever you like, such as the root directory or the lib
directory:
├── package.json
├── Cargo.toml
├── src/
└── lib/
package.json
You should have rust-bindings
in your dependencies, and a postinstall
script set to run rust-bindings build
. This will ensure that the necessary project boilerplate (the binding.gyp
build manifest and top-level C++ addon file) are generated before publishing.
... "dependencies": , "scripts": ...
If you want a debug build, change the postinstall
command to "rust-bindings build --debug"
.
Building
Build your native module simply by running npm install
from the project directory.
Clients who depend on your native module, directly or indirectly, don't have to do anything special. (However, they do have to have the required build tools installed on their machine. Hopefully we can improve this situation in the future.)
Requiring
You can easily require your native module from JS without having to specify the build directory; rust-bindings
figures this out for you:
var my_native_module = ;
You can override defaults by passing an optional options object to the rust-bindings
module:
Option | Description | Type | Default |
---|---|---|---|
root | project root | string | nearest containing directory of caller with package.json or node_modules |
name | library name | string | parse($manifest).package.name |
manifest | manifest path | path | $root/Cargo.toml |
Setup
Note: this is currently only working on OS X.
OS X
% nvm install iojs
Right now multirust is a mandatory dependency because it's used to run on Rust nightly by default. Once the fix for a jemalloc linking bug makes it through the trains to stable, multirust will be an optional dependency and rust-bindings will default to the system Rust compiler.
Known Limitations
- I've only gotten this working on OS X with io.js >= 3.
- It would be ideal to make Rust available as npm packages, to avoid clients of a native module having to install Rust on their system.
- There's no way to fallback on precompiled or portable implementations.
I would love to work with people on fixing these limitations!
License
MIT