Packages

rustler

0.22.2
0.38.0 0.37.3 0.37.1 0.37.0 retired 0.36.2 0.36.1 0.36.0 0.35.1 0.35.0 0.34.0 0.33.0 0.32.1 0.31.0 0.30.0 0.29.1 0.29.0 0.28.0 0.27.0 0.26.0 0.25.0 0.24.0 0.23.0 0.22.2 0.22.1 0.22.0 0.22.0-rc.2 0.22.0-rc.1 0.22.0-rc.0 0.21.1 0.21.0 0.20.0 0.19.1 0.19.0 0.18.0 0.17.1 0.17.0 0.16.0 0.10.1 0.10.0 0.9.0 0.8.0 0.7.0 0.6.0 0.5.0 0.4.0 0.3.2 0.3.1 0.3.0 0.2.0 0.1.1 0.1.0 0.0.8 0.0.7 0.0.6 0.0.5 0.0.4 0.0.3 0.0.2 0.0.1

Mix compiler and runtime helpers for Rustler.

HexDocs

Current section

Files

Jump to
Readme
59 Versions
2 Dependencies
Dependants
Files
Activity
rustler README.md
Raw

README.md 

# Rustler



[![Module Version](https://img.shields.io/hexpm/v/rustler.svg)](https://hex.pm/packages/rustler)

[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/rustler/)

[![Total Download](https://img.shields.io/hexpm/dt/rustler.svg)](https://hex.pm/packages/rustler)

[![License](https://img.shields.io/hexpm/l/rustler.svg)](https://github.com/rusterlium/rustler/blob/master/LICENSE)

[![Last Updated](https://img.shields.io/github/last-commit/rusterlium/rustler.svg)](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.22.2"}

  ]

end

```



## Usage



1.  Fetch all necessary dependencies:



    ```

    $ mix deps.get

    ```

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.