Repository files navigation

Documentation |Getting Started |Example

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

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

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.

The easiest way of getting started is therustler Elixir library.

• Add therustler Elixir library as adependency of your project.
• Runmix rustler.new to generate a new NIF in your project. Follow theinstructions.
• If you are already usingserde and/or have been usingserde_rustler before, please enable theserde feature in your NIF crate'sCargo.toml on therustler dependency.

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

#[rustler::nif]fnadd(a:i64,b:i64) ->i64{    a + b}rustler::init!("Elixir.Math");

Rustler currently has a minimal supported Rust version (MSRV) of 1.70. Thisis the configured version in.clippy.toml.

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

The minimal supported NIF version for a library should be defined via Cargofeatures. The default is currently2.15 (Erlang/OTP 22). To use features fromNIF version2.16 (Erlang/OTP 24) or2.17 (Erlang/OTP 26), the respectivefeature flag has to be enabled on the dependency:

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

You can find us in the#rustler:matrix.org channel onMatrixor in the#rustler channel inthe Elixir lang Slack.

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

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