+0
日增长
4,894
stars
249
forks
73
watchers
480
prs
281
issues
30
releases
README
Rustler
Documentation | Getting Started | Example
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.
- Add the rustler Elixir library 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 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.17 (Erlang/OTP 26).
To use features from NIF version 2.18 (Erlang/OTP 29), the respective feature
flag has to be enabled on the dependency:
toml
[dependencies]
rustler = { version = "...", features = ["nif_version_2_18"] }
To target an older NIF version, disable default features and explicitly enable
the required version:
toml
[dependencies]
rustler = { version = "...", default-features = false, features = ["nif_version_2_15"] }
Community
You can find us in the rustler:matrix.org channel on Matrix
or in the rustler channel in the Elixir lang Slack.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (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 aTop issues
#200Support for encoding/decoding external structs32 comments · 2019-04-09#83Cross-compilation12 comments · 2017-02-10#44Make sure all relevant erl_nif functionality is represented in some way10 comments · 2016-12-31#628Generate Typed Erlang/Elixir/Gleam Definitions from Rust9 comments · 2024-07-06#127Document use with Erlang9 comments · 2018-01-31#651Rustler recompiles although nothing changed8 comments · 2024-09-04#556Support for fully custom `:load_from` for escripts8 comments · 2023-08-11#13Support NIF code upgrades8 comments · 2016-04-28
Discussions
#687Statically linked nifs for mobile OTP targets6 comments · 2025-03-15#683Improve decoder error type1 comments · 2025-02-03#664Pass feature flags to the underlying running rust code2 comments · 2024-10-30#662Cant run `cargo test` on linux2 comments · 2024-10-16#660How to return {:ok, result} from say NifResult<Type>?4 comments · 2024-10-16#649Help with guaranteeing CoW going from Erlang to Rust2 comments · 2024-08-18#647Target CPU as native or Mac produces symbol(s) not found for architecture arm641 comments · 2024-08-16#626Lifetime issues when I want a resource to hold a NIF term2 comments · 2024-06-28
Latest release
rustler-0.39.0 rustler-0.39.0 2026-10-12What's Changed Add Elixir 1.20 by @filmor in https://github.com/rusterlium/rustler/pull/744 Fix Windows callback-table order for enif_set/is_pid_undefined by @ldgabbay in https://github.com/rusterlium/rustler/pull/748 Enforce panic unwind by @filmor in https://github.com/rusterlium/rustler/pull/747 Go back to pre-generating all API snippets by @filmor in https://github.com/rusterlium/rustler/pull/749 Update num-bigint requirement from 0.4 to 0.5 by @dependabot[bot] in https://github.com/rusterlium/rustler/pull/752 Update syn requirement from 2.0 to 3.0 by @dependabot[bot] in https: