Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md, include readme in crate docs #321

Merged
merged 2 commits into from
Oct 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 22 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Writing native node-js requires lots of boilerplate code. Node-bindgen generate

Install nj-cli command line, which will be used to generate the native library.

```
```sh
cargo install nj-cli
```

Expand All @@ -79,26 +79,26 @@ This is a one time step.
Add two dependencies to your projects' ```Cargo.toml```.

Add ```node-bindgen``` as a regular dependency (as below):
```
```toml
[dependencies]
node-bindgen = { version = "6.0" }
```

Then add ```node-bindgen```'s procedure macro to your build-dependencies as below:
```
```toml
[build-dependencies]
node-bindgen = { version = "6.0", default-features = false, features = ["build"] }
```

Then update crate type to ```cdylib``` to generate node.js compatible native module:
```
```toml
[lib]
crate-type = ["cdylib"]
```

Finally, add ```build.rs``` at the top of the project with following content:

```
```rust,ignore
fn main() {
node_bindgen::build::configure();
}
Expand All @@ -110,7 +110,7 @@ fn main() {
Here is a function that adds two numbers. Note that you don't need to worry about JS conversion.


```rust
```rust,ignore

use node_bindgen::derive::node_bindgen;

Expand All @@ -126,14 +126,14 @@ fn sum(first: i32, second: i32) -> i32 {

To build node.js library, using ```nj-cli``` to build:

```
```sh
nj-cli build
```

This will generate Node.js module in "./dist" folder.

To build a release version:
```
```sh
nj-cli build --release
```

Expand Down Expand Up @@ -169,7 +169,7 @@ undefined

## Function name or method can be renamed instead of default mapping

```rust
```rust,ignore
#[node_bindgen(name="multiply")]
fn mul(first: i32,second: i32) -> i32 {
first * second
Expand All @@ -181,7 +181,7 @@ Rust function mul is re-mapped as ```multiply```
## Optional argument

Argument can be skipped if it is marked as optional
```rust
```rust,ignore
#[node_bindgen]
fn sum(first: i32, second: Option<i32>) -> i32 {
first + second.unwrap_or(0)
Expand All @@ -195,7 +195,7 @@ Then sum can be invoked as

JS callback are mapped as Rust closure.

```rust
```rust,ignore
#[node_bindgen]
fn hello<F: Fn(String)>(first: f64, second: F) {

Expand All @@ -222,7 +222,7 @@ Callback are supported in Async rust as well.

Async rust function is mapped to Node.js promise.

```rust
```rust,ignore

use std::time::Duration;
use flv_future_aio::time::sleep;
Expand Down Expand Up @@ -252,7 +252,7 @@ addon.hello(5).then((val) => {
Structs, including generic structs, can have have the to-JS conversion boilerplate autogenerated.
Just apply the `node_bindgen` macro to your struct:

```rust
```rust,ignore
#[node_bindgen]
struct MyJson {
some_name: String,
Expand Down Expand Up @@ -285,7 +285,7 @@ Field names will be converted to camelCase.

Enums will also have their JS representation autogenerated with the help of `node_bindgen`:

```rust
```rust,ignore
#[node_bindgen]
enum ErrorType {
WithMessage(String, usize),
Expand Down Expand Up @@ -332,7 +332,7 @@ Generics and references are supported, with the same caveats as for structs.

JavaScript class is supported.

```rust
```rust,ignore

struct MyClass {
val: f64,
Expand Down Expand Up @@ -380,8 +380,8 @@ environment has a valid C/C++ compiler.
In the future, this file will be re-written in Rust, removing this dependency.

Just make sure that you are compiling the rust module using
```
$ npx electron-build-env nj-cli build --release
```sh
npx electron-build-env nj-cli build --release
```

otherwise you will get dreaded `A dynamic link library (DLL) initialization routine failed` when importing the rust module in electron
Expand All @@ -398,7 +398,7 @@ In addition, because `tslink` generates TypeScript types definitions, any change

For example,

```ignore
```rust,ignore
#[macro_use] extern crate tslink;
use tslink::tslink;
use node_bindgen::derive::node_bindgen;
Expand Down Expand Up @@ -426,7 +426,7 @@ impl MyScruct {

Would be represented (`*.d.ts`) as

```ignore
```ts
export declare class MyStruct {
constructor(inc: number);
incMyNumber(a: number): number;
Expand All @@ -441,11 +441,11 @@ Also, please **note**, `node-bindgen` by default applies snake case naming to me

File: `./Cargo.toml` (in a `root` of project):

```ignore
```toml
[project]
...
# ...
[lib]
...
# ...
[tslink]
node = "./dist/index.node"
```
Expand Down
2 changes: 2 additions & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
#![doc = include_str!("../README.md")]

#[cfg(feature = "node")]
pub mod core {
pub use nj_core::*;
Expand Down
Loading