View Source RustlerPrecompiled (rustler_precompiled v0.6.3)
Download and use precompiled NIFs safely with checksums.
Rustler Precompiled is a tool for library maintainers that rely on Rustler. It helps by removing the need to have the Rust compiler installed in the user's machine.
Check the Precompilation Guide for details.
example
Example
defmodule MyNative do
use RustlerPrecompiled,
otp_app: :my_app,
crate: "my_app_nif",
base_url: "https://github.com/me/my_project/releases/download/v0.1.0",
version: "0.1.0"
end
options
Options
:otp_app
- The OTP app name that the dynamic library will be loaded from.:crate
- The name of Rust crate if different from the:otp_app
. This is optional.:base_url
- A valid URL that is used as base path for the NIF file.:version
- The version of precompiled assets (it is part of the NIF filename).:force_build
- Force the build withRustler
. This isfalse
by default, but if your:version
is a pre-release (like "2.1.0-dev"), this option will always be settrue
. You can also configure this option by setting an application env like this:config :rustler_precompiled, :force_build, your_otp_app: true
It is important to add the ":rustler" package to your dependencies in order to force the build. To do that, just add it to your
mix.exs
file:{:rustler, ">= 0.0.0", optional: true}
:targets
- A list of targets supported by Rust for which precompiled assets are available. By default the following targets are configured:aarch64-apple-darwin
aarch64-unknown-linux-gnu
aarch64-unknown-linux-musl
arm-unknown-linux-gnueabihf
riscv64gc-unknown-linux-gnu
x86_64-apple-darwin
x86_64-pc-windows-gnu
x86_64-pc-windows-msvc
x86_64-unknown-linux-gnu
x86_64-unknown-linux-musl
:nif_versions
- A list of OTP NIF versions for which precompiled assets are available. A NIF version is usually compatible with two OTP minor versions, and an older NIF is usually compatible with newer OTPs. The available versions are the following:2.14
- for OTP 21 and above.2.15
- for OTP 22 and above.2.16
- for OTP 24 and above.2.17
- for OTP 26 and above.
By default the following NIF versions are configured:
2.15
2.16
Check the compatibiliy table between Elixir and OTP in: https://hexdocs.pm/elixir/compatibility-and-deprecations.html#compatibility-between-elixir-and-erlang-otp
In case "force build" is used, all options except :base_url
, :version
,
:force_build
, :nif_versions
, and :targets
are going to be passed down to Rustler
.
So if you need to configure the build, check the Rustler
options.
environment-variables
Environment variables
This project reads some system environment variables. They are all optional, but they can change the behaviour of this library at compile time of your project.
They are:
HTTP_PROXY
orhttp_proxy
- Sets the HTTP proxy configuration.HTTPS_PROXY
orhttps_proxy
- Sets the HTTPS proxy configuration.MIX_XDG
- If present, sets the OS as:linux
for the:filename.basedir/3
when getting an user cache dir.TARGET_ARCH
- The CPU target architecture. This is useful for when building your Nerves project, where your host CPU is different from your target CPU.Note that Nerves sets this value automatically when building your project.
Examples:
arm
,aarch64
,x86_64
,riscv64
.TARGET_ABI
- The target ABI (e.g.,gnueabihf
,musl
). This is set by Nerves as well.TARGET_VENDOR
- The target vendor (e.g.,unknown
,apple
,pc
). This is not set by Nerves. If any of theTARGET_
env vars is set, butTARGET_VENDOR
is empty, then we change the target vendor tounknown
that is the default value for Linux systems.TARGET_OS
- The target operational system. This is alwayslinux
for Nerves.
For more details about Nerves env vars, see https://hexdocs.pm/nerves/environment-variables.html
Link to this section Summary
Functions
Returns URLs for NIFs based on its module name.
Returns the file URL to be downloaded for current target.
Returns the target triple for download or compile and load.
Link to this section Functions
Returns URLs for NIFs based on its module name.
The module name is the one that defined the NIF and this information is stored in a metadata file.
Returns the file URL to be downloaded for current target.
It receives the NIF module.
target(config \\ target_config(), available_targets \\ Config.default_targets(), available_nif_versions \\ Config.available_nif_versions())
View SourceReturns the target triple for download or compile and load.
This function is translating and adding more info to the system architecture returned by Elixir/Erlang to one used by Rust.
The returned string has the following format:
"nif-NIF_VERSION-ARCHITECTURE-VENDOR-OS-ABI"
examples
Examples
iex> RustlerPrecompiled.target()
{:ok, "nif-2.16-x86_64-unknown-linux-gnu"}
iex> RustlerPrecompiled.target()
{:ok, "nif-2.15-aarch64-apple-darwin"}