Rustler Precompiled

Rustler defaults to NIF version 2.15 (targeting Erlang/OTP 22+). If your project requires support for newer or older OTP versions, you must disable default features in your Cargo.toml and explicitly enable the desired NIF version feature.

Available NIF versions:

• 2.14: OTP 21+
• 2.15: OTP 22+
• 2.16: OTP 24+
• 2.17: OTP 26+
• 2.18: OTP 29+

Note: When using rustler-precompiled-action, ensure you follow the nif_version_MAJOR_MINOR format (e.g., nif_version_2_16) to allow the GitHub Action to activate the feature automatically.

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

To use precompiled NIFs in your Elixir project, add rustler_precompiled to your deps list in mix.exs. It is recommended to keep rustler as an optional dependency, as it is typically only required during development.

def deps do
  [
    {:rustler_precompiled, "~> 0.9"}
  ]
end

To allow your CI workflow to create releases and use security attestations, you must grant specific write permissions to the GITHUB_TOKEN. Add the permissions: key to your job section in your workflow YAML file.

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

When releasing a Hex package, you must include a checksum file. This file ensures the integrity of the precompiled NIFs and prevents supply chain attacks.

1. Build your artifacts in CI.
2. Run the mix rustler_precompiled.download task with the --all and --print flags.
3. Include the resulting checksum-*.exs file in your mix.exs files: list.

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

Example mix.exs configuration:

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

Follow these steps to ensure a successful release:

1. Release a new tag in your repository.
2. Push the code and tags: git push origin main --tags.
3. Wait for CI to complete all NIF builds.
4. Run mix rustler_precompiled.download YourModule --all to generate the checksum file.
5. Release the package to Hex.pm, ensuring the checksum-*.exs file is included in the package contents.

Certain targets require specific Rust flags. For example, x86_64-unknown-linux-musl requires disabling crt-static to work correctly. You can also configure the release profile for optimizations like LTO (Link Time Optimization).

# 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

The :variants option allows you to specify logic for selecting specific NIF variants based on the target. It is a map where keys are target triples and values are keyword lists of {variant_name, detection_function}.

The detection_function must be a function that accepts either 0 or 1 argument and returns a boolean indicating if the variant should be activated.

Note: All targets specified in the :variants map must also be present in the :targets list.

# Example of defining variants for specific targets
variants: %{
  "x86_64-unknown-linux-gnu" => [
    {:musl, fn -> true end},
    {:gnu, fn _ -> false end}
  ]
}

When targeting systems using the musl ABI, such as Alpine Linux, you must disable static linking. This is achieved by modifying your .cargo/cargo.toml file to include specific rustflags for the target. This is common for x86_64-unknown-linux-musl and aarch64-unknown-linux-musl (often used in containers on Apple Silicon/ARM64 machines).

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

When targeting 32-bit platforms like ARM (e.g., arm-unknown-linux-gnueabihf), you may need to explicitly link libatomic. To do this, modify your .cargo/config.yml file to add the dylib=atomic flag for the specific target.

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