# Rustler

[![Module Version](](
[![Hex Docs](](
[![Total Download](](
[![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 []( To install it, add `:rustler` to your dependencies:

def deps do
    {:rustler, "~> 0.33.0", runtime: false}

## 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

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

    $ mix

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]( 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

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)

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
- MIT license ([LICENSE-MIT](../LICENSE-MIT) or

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.