View Source Rustler

Module Version Hex Docs Total Download License Last Updated

The Mix package for rustler, a library to write Erlang Native Implemented Functions (NIFs) in Rust programming language.

Installation

This package is available on Hex.pm. To install it, add :rustler to your dependencies:

def deps do
  [
    {:rustler, "~> 0.35.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..

Crate configuration

The Rust crate compilation can be controlled via Mix compile-time configuration in config/config.exs. See 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.

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.

Licensed under either of

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.