Rustler Precompiled

https://hexdocs.pm/rustler_precompiled/
Admin
Rustler Precompiled is a tool for Elixir library maintainers to safely download and use precompiled...
Tokens:7,086
Snippets:96
Trust Score:9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Build Matrix for Targets

Source: https://hexdocs.pm/rustler_precompiled/precompilation_guide.html

Defines the build matrix for cross-compiling NIFs across different operating systems, architectures, and NIF versions.

```yaml
matrix:
  nif: ["2.15"]
  job:
    - { target: aarch64-unknown-linux-gnu   , os: ubuntu-22.04 , use-cross: true }
    - { target: aarch64-apple-darwin        , os: macos-15      }
    - { target: x86_64-apple-darwin         , os: macos-15-intel }
    - { target: x86_64-unknown-linux-gnu    , os: ubuntu-22.04  }
    - { target: x86_64-unknown-linux-musl   , os: ubuntu-22.04 , use-cross: true }
    - { target: x86_64-pc-windows-gnu       , os: windows-2022  }
    - { target: x86_64-pc-windows-msvc      , os: windows-2022  }
```

--------------------------------

### Configure Force Build for a Specific OTP App

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

This example demonstrates how to configure the `:force_build` option for a specific OTP app using application environment settings. This ensures that Rustler is used for building the NIFs for that app.

```elixir
config :rustler_precompiled, :force_build, your_otp_app: true
```

--------------------------------

### Configure Variants for Specific Targets

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

This example shows how to configure variants for a specific target, such as `x86_64-unknown-linux-gnu`. The `old_glibc` variant is defined using a function that checks for the presence of an old glibc. The order of variants matters as the first one returning true is selected.

```elixir
%{"x86_64-unknown-linux-gnu" => [old_glibc: fn _config -> has_old_glibc?() end]}
```

--------------------------------

### Get Target Triple for Download/Compile

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

Retrieves the target triple used for downloading or compiling and loading NIFs. This function translates system architecture information into a format usable by Rust. It can be used with default configurations or custom ones.

```elixir
iex> RustlerPrecompiled.target()
{:ok, "nif-2.16-x86_64-unknown-linux-gnu"}
```

```elixir
iex> RustlerPrecompiled.target()
{:ok, "nif-2.15-aarch64-apple-darwin"}
```

--------------------------------

### Configure Rustler NIF Version in Cargo.toml

Source: https://hexdocs.pm/rustler_precompiled/troubleshooting.html

Specify Rustler dependencies and features in your `Cargo.toml` to enable specific NIF versions. This example shows how to enable NIF version 2.15 and how to explicitly depend on version 2.16.

```toml
[dependencies]
rustler = { version = "0.37", default-features = false }

# And then, your features.
[features]
default = ["nif_version_2_15"]
nif_version_2_15 = ["rustler/nif_version_2_15"]
nif_version_2_16 = ["rustler/nif_version_2_16"]
nif_version_2_17 = ["rustler/nif_version_2_17"]
```

```toml
[dependencies]
rustler = { version = "0.37", default-features = false, features = ["nif_version_2_16"] }
```

--------------------------------

### Get Target Triple for Download or Compile

Source: https://hexdocs.pm/rustler_precompiled/index.html

Retrieves the target triple used for downloading or compiling and loading NIFs. This function translates system architecture information into a format compatible with Rust. It can be used to determine the correct artifact to fetch or build.

```elixir
RustlerPrecompiled.target()
```

--------------------------------

### Basic RustlerPrecompiled Configuration

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

This snippet shows the basic configuration for RustlerPrecompiled within a module. It specifies the OTP app, crate name, base URL for NIFs, and the version.

```elixir
defmodule MyApp.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
```

--------------------------------

### target/0

Source: https://hexdocs.pm/rustler_precompiled/index.html

Returns the target triple for download or compile and load. This function translates and adds 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"`.

```APIDOC
## target()

### Description
Returns the target triple for download or compile and load.

### Examples
```iex
RustlerPrecompiled.target()
# {:ok, "nif-2.16-x86_64-unknown-linux-gnu"}

RustlerPrecompiled.target()
# {:ok, "nif-2.15-aarch64-apple-darwin"}
```
```

--------------------------------

### Include Checksum File in Hex Package Configuration

Source: https://hexdocs.pm/rustler_precompiled/precompilation_guide.html

Configures the `files` key in `mix.exs` to include the generated checksum file in the Hex package. This ensures the precompiled NIFs are correctly distributed.

```elixir
defp package do
  [
    files: [
      "lib",
      "native/my_nif/.cargo",
      "native/my_nif/src",
      "native/my_nif/Cargo*",
      "checksum-*.exs",
      "mix.exs"
    ],
    # ...
  ]
end
```

--------------------------------

### Configure 'musl' ABI Target in Cargo

Source: https://hexdocs.pm/rustler_precompiled/troubleshooting.html

Add this configuration to your `.cargo/cargo.toml` file to support 'musl' ABI targets like `x86_64-unknown-linux-musl`. This is necessary to disable static linking for these targets.

```toml
# This is needed for "musl". See https://github.com/rust-lang/rust/issues/59302
[target.x86_64-unknown-linux-musl]
rustflags = [
  "-C", "target-feature=-crt-static"
]
```

--------------------------------

### target/3

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

Returns the target triple for download or compile and load. This function translates and adds 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"`.

```APIDOC
## target/3

### Description
Returns the target triple for download or compile and load.

### Parameters
#### Path Parameters
- **config** (any) - Optional - Configuration for the target.
- **available_targets** (list) - Optional - A list of available targets.
- **available_nif_versions** (list) - Optional - A list of available NIF versions.

### Response
#### Success Response
- **tuple** - A tuple containing the status and the target triple string.
  - `{:ok, "nif-NIF_VERSION-ARCHITECTURE-VENDOR-OS-ABI"}`

### Request Example
```iex
RustlerPrecompiled.target()
```

### Response Example
```iex
{:ok, "nif-2.16-x86_64-unknown-linux-gnu"}
{:ok, "nif-2.15-aarch64-apple-darwin"}
```
```

--------------------------------

### Configure Force Build for All Rustler Packages

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

This configuration sets `:force_build_all` to true, which forces a build with Rustler for all packages using RustlerPrecompiled. Alternatively, the environment variable `RUSTLER_PRECOMPILED_FORCE_BUILD_ALL` can be used.

```elixir
config :rustler_precompiled, force_build_all: true
```

--------------------------------

### Configure GitHub Actions Permissions

Source: https://hexdocs.pm/rustler_precompiled/precompilation_guide.html

Enable necessary permissions for your GitHub Actions workflow to create releases and use artifact attestations.

```yaml
permissions:
  # For creating a new release.
  contents: write
  # The following are needed for the "actions/attest" GH Action.
  id-token: write
  attestations: write
  artifact-metadata: write
```

--------------------------------

### current_target_nifs/1

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

Returns the file URLs to be downloaded for the current target as a list of tuples: `[{lib_name, {url, headers}}]`. It is in the plural because a target may have some variants for it. It receives the NIF module.

```APIDOC
## current_target_nifs/1

### Description
Returns the file URLs to be downloaded for the current target as a list of tuples: `[{lib_name, {url, headers}}]`.

### Parameters
#### Path Parameters
- **nif_module** (module) - Required - The name of the NIF module.

### Response
#### Success Response
- **list** - A list of tuples, where each tuple contains the library name and a tuple with the URL and headers for the NIF.
  - `[{lib_name, {url, headers}}]`
```

--------------------------------

### current_target_nifs/1

Source: https://hexdocs.pm/rustler_precompiled/index.html

Returns the file URLs to be downloaded for the current target as a list of tuples: `[{lib_name, {url, headers}}]`. It is in the plural because a target may have some variants for it. It receives the NIF module.

```APIDOC
## current_target_nifs(nif_module)

### Description
Returns the file URLs to be downloaded for current target as a list of tuples: `[{lib_name, {url, headers}}]`.

### Parameters
#### Path Parameters
- **nif_module** (module) - Required - The name of the NIF module.
```

--------------------------------

### Add Rustler Dependency to Mix.exs

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

To enable the force build functionality, it's necessary to add the `:rustler` package as an optional dependency in your `mix.exs` file.

```elixir
{:rustler, ">= 0.0.0", optional: true}
```

--------------------------------

### Link 'libatomic' for 32-bit ARM Builds

Source: https://hexdocs.pm/rustler_precompiled/troubleshooting.html

Modify your `.cargo/config.yml` to link `libatomic` when targeting 32-bit ARM platforms like `arm-unknown-linux-gnueabihf`. This is often required for compatibility.

```yaml
# Libatomic is needed for 32 bits ARM.
# See: https://github.com/philss/rustler_precompiled/issues/53
[target.arm-unknown-linux-gnueabihf]
rustflags = [
  "-l", "dylib=atomic"
]
```

--------------------------------

### available_nifs/1

Source: https://hexdocs.pm/rustler_precompiled/index.html

Returns URLs for NIFs based on its module name as a list of tuples: `[{lib_name, {url, headers}}]`. The module name is the one that defined the NIF and this information is stored in a metadata file.

```APIDOC
## available_nifs(nif_module)

### Description
Returns URLs for NIFs based on its module name as a list of tuples: `[{lib_name, {url, headers}}]`.

### Parameters
#### Path Parameters
- **nif_module** (module) - Required - The name of the NIF module.
```

--------------------------------

### Generate Checksum File for Hex Package

Source: https://hexdocs.pm/rustler_precompiled/precompilation_guide.html

Generates a checksum file for precompiled NIFs, which is mandatory for Hex packages. This command should be run after the build artifacts are available.

```bash
$ mix rustler_precompiled.download YourRustlerModule --all --print
```

```bash
$ mix rustler_precompiled.download RustlerPrecompilationExample.Native --all --print
```

--------------------------------

### available_nifs/1

Source: https://hexdocs.pm/rustler_precompiled/RustlerPrecompiled.html

Returns URLs for NIFs based on its module name as a list of tuples: `[{lib_name, {url, headers}}]`. The module name is the one that defined the NIF and this information is stored in a metadata file.

```APIDOC
## available_nifs/1

### Description
Returns URLs for NIFs based on its module name as a list of tuples: `[{lib_name, {url, headers}}]`.

### Parameters
#### Path Parameters
- **nif_module** (module) - Required - The name of the NIF module.

### Response
#### Success Response
- **list** - A list of tuples, where each tuple contains the library name and a tuple with the URL and headers for the NIF.
  - `[{lib_name, {url, headers}}]`
```

--------------------------------

### Configure RustlerPrecompiled in Elixir

Source: https://hexdocs.pm/rustler_precompiled/precompilation_guide.html

Defines an Elixir module that uses RustlerPrecompiled to manage precompiled NIFs. It specifies the OTP app, crate name, base URL for downloads, and version. The `force_build` option can be used to enable local compilation.

```elixir
defmodule RustlerPrecompilationExample.Native do
  version = Mix.Project.config()[:version]

  use RustlerPrecompiled,
    otp_app: :rustler_precompilation_example,
    crate: "example",
    base_url:
      "https://github.com/philss/rustler_precompilation_example/releases/download/v#{version}",
    force_build: System.get_env("RUSTLER_PRECOMPILATION_EXAMPLE_BUILD") in ["1", "true"],
    version: version

  # When your NIF is loaded, it will override this function.
  def add(_a, _b), do: :erlang.nif_error(:nif_not_loaded)
end
```

--------------------------------

### Cargo Configuration for Musl Target

Source: https://hexdocs.pm/rustler_precompiled/precompilation_guide.html

Provides additional configuration for the Rust compiler when targeting the musl C library, specifically disabling static CRT.

```toml
# This is needed for "musl". See https://github.com/rust-lang/rust/issues/59302
[target.x86_64-unknown-linux-musl]
rustflags = [
  "-C", "target-feature=-crt-static"
]

# Provides a small build size for the "release" profile, but takes more time to build.
[profile.release]
lto = true
```
Tokens:
Raw