View Source Rustler (Rustler v0.35.1)
Provides compile-time configuration for a NIF module.
When used, Rustler expects the :otp_app
as option.
The :otp_app
should point to the OTP application that
the dynamic library can be loaded from.
For example:
defmodule MyNIF do
use Rustler, otp_app: :my_nif
end
This allows the module to be configured like so:
config :my_nif, MyNIF,
crate: :my_nif,
load_data: [1, 2, 3]
Configuration options
:cargo
- Specify how to envoke the rust compiler. Options are::system
(default) - usecargo
from the system (must be in$PATH
){:system, <channel>}
- usecargo
from the system with the given channel. Specified as a string, passed directly tocargo
(e.g. "+nightly").{:rustup, <version>}
- userustup
to specify which channel to use. Available options include::stable
,:beta
,:nightly
, or a string which specifies a specific version (e.g."1.39.0"
).{:bin, "/path/to/binary"}
- provide a specific path tocargo
.
:crate
- the name of the Rust crate, if different from yourotp_app
value. If you have more than one crate in your project, you will need to be explicit about which crate you intend to use.:default_features
- a boolean to specify whether the crate's default features should be used.:env
- Specify a list of environment variables when envoking the compiler.:features
- a list of features to enable when compiling the crate.:load_data
- Any valid term. This value is passed into the NIF when it is loaded (default:0
):load_data_fun
-{Module, :function}
to dynamically generateload_data
. Default value:nil
.This parameter is mutually exclusive with
load_data
which means thatload_data
has to be set to it's default value.Example
defmodule NIF do use Rustler, load_data_fun: {Deployment, :nif_data} end defmodule Deployment do def nif_data do :code.priv_dir(:otp_app) |> IO.iodata_to_binary() end end
:load_from
- This option allows control over where the final artifact should be loaded from at runtime. By default the compiled artifact is loaded from the owning:otp_app
'spriv/native
directory. This option comes in handy in combination with the:skip_compilation?
option in order to load pre-compiled artifacts. To override the default behaviour specify a tuple:{:my_app, "priv/native/<artifact>"}
. Due to the way:erlang.load_nif/2
works, the artifact should not include the file extension (i.e..so
,.dll
).:mode
- Specify which mode to compile the crate with (default::release
):path
- By default, rustler expects the crate to be found innative/<crate>
in the root of the project. Use this option to override this.:skip_compilation?
- This option skips envoking the rust compiler. Specify this option in combination with:load_from
to load a pre-compiled artifact.:target
- Specify a compile target triple.:target_dir
- Override the compiler output directory.
Any of the above options can be passed directly into the use
macro like so:
defmodule MyNIF do
use Rustler,
otp_app: :my_nif,
crate: :some_other_crate,
load_data: :something
end