# Technical Documentation: rusterlium/rustler

> ℹ️ **Provenance:** Hybrid Fusion: `rusterlium/rustler` (README + 4 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/rusterlium/rustler) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (rusterlium/rustler)

# Rustler

[Documentation](https://docs.rs/rustler/latest/rustler) | [Getting Started](https://github.com/rusterlium/rustler/blob/master/README.md#getting-started) | [Example](https://github.com/rusterlium/NifIo)

[](https://github.com/rusterlium/rustler/actions/workflows/main.yml)
[](https://hex.pm/packages/rustler)
[](https://crates.io/crates/rustler)
[](https://github.com/rusterlium/rustler/commits/master)

Rustler is a library for writing Erlang NIFs in safe Rust code. That means
there should be no ways to crash the BEAM (Erlang VM). The library provides
facilities for generating the boilerplate for interacting with the BEAM,
handles encoding and decoding of Erlang terms, and catches rust panics before
they unwind into C.

The library provides functionality for both Erlang and Elixir, however Elixir
is favored as of now.

#### Features

**Safety**  
The code you write in a Rust NIF should never be able to crash the BEAM.

**Interop**  
Decoding and encoding rust values into Erlang terms is as easy as a function call.

**Type composition**  
Making a Rust struct encodable and decodable to Erlang or Elixir can be done with a single attribute.

**Resource objects**  
Enables you to safely pass a reference to a Rust struct into Erlang code. The struct will be automatically dropped when it's no longer referenced.

#### Getting started

The easiest way of getting started is the [rustler Elixir library](https://hex.pm/packages/rustler).

- Add the [rustler Elixir library](https://hex.pm/packages/rustler) as a
  dependency of your project.
- Run `mix rustler.new` to generate a new NIF in your project. Follow the
  instructions.
- If you are already using [`serde`](https://serde.rs) and/or have been using
  `serde_rustler` before, please enable the `serde` feature in your NIF crate's
  `Cargo.toml` on the `rustler` dependency.

#### What it looks like

This is the code for a minimal NIF that adds two numbers and returns the result.

```rust
#[rustler::nif]
fn add(a: i64, b: i64) -> i64 {
    a + b
}

rustler::init!("Elixir.Math");
```

#### Minimal Supported Rust Version (MSRV)

Rustler currently has a minimal supported Rust version (MSRV) of 1.91. This
is the configured version in `.clippy.toml`.

#### Supported OTP and Elixir Versions

Rustler aims to support the newest three major OTP versions as well as newest three minor Elixir versions.

#### Supported NIF version

The minimal supported NIF version for a library should be defined via Cargo
features. The default is currently `2.15` (Erlang/OTP 22). To use features from
NIF version `2.16` (Erlang/OTP 24) or `2.17` (Erlang/OTP 26), the respective
feature flag has to be enabled on the dependency:

```toml
[dependencies]
rustler = { version = "...", features = ["nif_version_2_16"] }
```

#### Community

You can find us in the `#rustler:matrix.org` channel on [Matrix](https://matrix.to/#/#rustler:matrix.org)
or in the `#rustler` channel in [the Elixir lang Slack](https://elixir-slackin.herokuapp.com/).

#### License

Licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

##### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

## 2. In-Tree Documentation Chapters (rusterlium/rustler)

## File: README.md

# Rustler

[Documentation](https://docs.rs/rustler/latest/rustler) | [Getting Started](https://github.com/rusterlium/rustler/blob/master/README.md#getting-started) | [Example](https://github.com/rusterlium/NifIo)

[](https://github.com/rusterlium/rustler/actions/workflows/main.yml)
[](https://hex.pm/packages/rustler)
[](https://crates.io/crates/rustler)
[](https://github.com/rusterlium/rustler/commits/master)

Rustler is a library for writing Erlang NIFs in safe Rust code. That means
there should be no ways to crash the BEAM (Erlang VM). The library provides
facilities for generating the boilerplate for interacting with the BEAM,
handles encoding and decoding of Erlang terms, and catches rust panics before
they unwind into C.

The library provides functionality for both Erlang and Elixir, however Elixir
is favored as of now.

#### Features

**Safety**  
The code you write in a Rust NIF should never be able to crash the BEAM.

**Interop**  
Decoding and encoding rust values into Erlang terms is as easy as a function call.

**Type composition**  
Making a Rust struct encodable and decodable to Erlang or Elixir can be done with a single attribute.

**Resource objects**  
Enables you to safely pass a reference to a Rust struct into Erlang code. The struct will be automatically dropped when it's no longer referenced.

#### Getting started

The easiest way of getting started is the [rustler Elixir library](https://hex.pm/packages/rustler).

- Add the [rustler Elixir library](https://hex.pm/packages/rustler) as a
  dependency of your project.
- Run `mix rustler.new` to generate a new NIF in your project. Follow the
  instructions.
- If you are already using [`serde`](https://serde.rs) and/or have been using
  `serde_rustler` before, please enable the `serde` feature in your NIF crate's
  `Cargo.toml` on the `rustler` dependency.

#### What it looks like

This is the code for a minimal NIF that adds two numbers and returns the result.

```rust
#[rustler::nif]
fn add(a: i64, b: i64) -> i64 {
    a + b
}

rustler::init!("Elixir.Math");
```

#### Minimal Supported Rust Version (MSRV)

Rustler currently has a minimal supported Rust version (MSRV) of 1.91. This
is the configured version in `.clippy.toml`.

#### Supported OTP and Elixir Versions

Rustler aims to support the newest three major OTP versions as well as newest three minor Elixir versions.

#### Supported NIF version

The minimal supported NIF version for a library should be defined via Cargo
features. The default is currently `2.15` (Erlang/OTP 22). To use features from
NIF version `2.16` (Erlang/OTP 24) or `2.17` (Erlang/OTP 26), the respective
feature flag has to be enabled on the dependency:

```toml
[dependencies]
rustler = { version = "...", features = ["nif_version_2_16"] }
```

#### Community

You can find us in the `#rustler:matrix.org` channel on [Matrix](https://matrix.to/#/#rustler:matrix.org)
or in the `#rustler` channel in [the Elixir lang Slack](https://elixir-slackin.herokuapp.com/).

#### License

Licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

##### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

---

## File: rustler_benchmarks/README.md

# Rustler Benchmarks

A collection of benchmark to test the performance of certain rustler features.

## Running a benchmark

Each module can be run as a benchmark on the command line. Note that the `benchmark` crate is compiled with mode `release`!

```
$ mix run -e Benchmark.NifStruct.run
Name                        ips        average  deviation         median         99th %
decode                 404.50 K        2.47 μs   ±651.07%        1.63 μs        7.23 μs
decode and encode      117.27 K        8.53 μs   ±306.83%        6.34 μs       33.76 μs

Comparison:
decode                 404.50 K
decode and encode      117.27 K - 3.45x slower +6.06 μs

$ mix run -e Benchmark.NifRecord.run
Name                        ips        average  deviation         median         99th %
decode                   1.20 M        0.83 μs   ±689.21%        0.49 μs        2.22 μs
decode and encode        0.80 M        1.25 μs  ±1472.17%        0.65 μs        3.51 μs

Comparison:
decode                   1.20 M
decode and encode        0.80 M - 1.50x slower +0.42 μs
```

---

## File: rustler_mix/priv/templates/basic/README.md

# NIF for <%= module %>

## To build the NIF module:

- Your NIF will now build along with your project.

## To load the NIF:

```elixir
defmodule <%= module %> do
  use Rustler, otp_app: :<%= otp_app %>, crate: "<%= library_name %>"

  # When your NIF is loaded, it will override this function.
  def add(_a, _b), do: :erlang.nif_error(:nif_not_loaded)
end
```

## Examples

[This](https://github.com/rusterlium/NifIo) is a complete example of a NIF written in Rust.

---

## File: rustler_mix/README.md

# Rustler

[](https://hex.pm/packages/rustler)
[](https://hexdocs.pm/rustler/)
[](https://hex.pm/packages/rustler)
[](https://github.com/rusterlium/rustler/blob/master/LICENSE)
[](https://github.com/rusterlium/rustler/commits/master)

The Mix package for [rustler](https://github.com/rusterlium/rustler), a library to write Erlang Native Implemented Functions (NIFs) in [Rust](https://www.rust-lang.org/) programming language.

## Installation

This package is available on [Hex.pm](https://hex.pm/packages/rustler). To install it, add `:rustler` to your dependencies:

```elixir
def deps do
  [
    {:rustler, "~> 0.38.0", runtime: false}
  ]
end
```

## Usage

1.  Fetch and compile all necessary dependencies:

    ```
    $ mix deps.get && mix deps.compile
    ```
2.  Check your installation by showing help from the installed Mix task:

    ```
    $ mix help rustler.new
    ```

3.  Generate the boilerplate for a new Rustler project. Follow the instructions
    to configure your project:

    ```
    $ mix rustler.new
    ```

4.  [Load the NIF in your program.](#loading-the-nif).

## Crate configuration

The Rust crate compilation can be controlled via Mix compile-time configuration in `config/config.exs`.
See [configuration options](https://hexdocs.pm/rustler/Rustler.html#module-configuration-options) for more details.


## Loading the NIF

Loading a Rustler NIF is done in almost the same way as normal NIFs.

The actual loading is done by calling `use Rustler, otp_app: :my_app` in the module you want to load the NIF in.
This sets up the `@on_load` module hook to load the NIF when the module is first
loaded.

```elixir
defmodule MyProject.MyModule do
  use Rustler,
    otp_app: :my_app,
    crate: :my_crate

  # When loading a NIF module, dummy clauses for all NIF function are required.
  # NIF dummies usually just error out when called when the NIF is not loaded, as that should never normally happen.
  def my_native_function(_arg1, _arg2), do: :erlang.nif_error(:nif_not_loaded)
end
```

Note that `:crate` is the name in the `[lib]` section of your `Cargo.toml`. The
`:crate` option is optional if your crate and `otp_app` use the same name.

See the `Rustler` module for more information.

## Copyright and License

Licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

--- METRICS ---
- Files Extracted: 5
- Estimated Token Budget: ~2889 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/rusterlium/rustler