Download and use precompiled Zig NIFs safely with checksums.

ZiglerPrecompiled is a tool for library maintainers that rely on Zigler. It removes the need for end users to install the Zig compiler — precompiled shared libraries are downloaded from a release URL and verified against SHA-256 checksums.

How it works

Zigler generates complex NIF wrapper functions (type marshalling, error tracing, etc.) at compile time by analyzing Zig source code. This means the Zig compiler is needed even to generate the Elixir-side wrappers.

ZiglerPrecompiled solves this by requiring library authors to declare their NIF functions with :nifs — a keyword list of {name, arity} pairs. At compile time:

1. If force_build: true (or pre-release version), it delegates to use Zig for full compilation with Zigler's rich wrapper generation.

2. Otherwise, it downloads the precompiled .so/.dll, verifies the SHA-256 checksum, and generates simple NIF stubs that raise :nif_not_loaded until @on_load loads the shared library.

The precompiled .so contains the full NIF implementation including Zigler's marshalling layer, so the simple stubs are sufficient — they are immediately replaced when the NIF loads.

Example

defmodule MyApp.MyNative do
  use ZiglerPrecompiled,
    otp_app: :my_app,
    base_url: "https://github.com/me/my_project/releases/download/v0.1.0",
    version: "0.1.0",
    nifs: [
      add: 2,
      multiply: 2
    ]
end

Options

• :otp_app — The OTP app name that the dynamic library will be loaded from.

• :nifs — Required. A keyword list of {function_name, arity} pairs declaring which NIF functions the module exports. These are used to generate stub functions that are overridden when the NIF loads.

• :base_url — Where to find the precompiled NIFs. Accepts:

  • A URL string — the NIF filename is appended. Works with GitHub Releases.

  • {url, headers} — for private servers requiring auth headers.

  • {module, function} — a function of arity 1 receiving the filename, returning a URL or {url, headers}.

• :version — The version of precompiled assets (part of the NIF filename).

• :module_name — The name used in artifact filenames. Defaults to the full module name (e.g. "Elixir.MyApp.Native").

• :force_build — Force compilation with Zigler instead of downloading. Defaults to false. Always true for pre-release versions (e.g. "0.1.0-dev").

  Can also be set via application env:

  config :zigler_precompiled, :force_build, my_app: true

  Or globally:

  config :zigler_precompiled, force_build_all: true

• :targets — A list of Zig target triples for which precompiled assets are available. Defaults to:

  • aarch64-linux-gnu
  • aarch64-linux-musl
  • aarch64-macos-none
  • arm-linux-gnueabihf
  • arm-linux-musleabihf
  • riscv64-linux-gnu
  • x86_64-linux-gnu
  • x86_64-linux-musl
  • x86_64-macos-none
  • x86_64-windows-gnu
  • x86-linux-gnu
  • x86-windows-gnu

• :max_retries — Maximum download retries before giving up. Defaults to 3.

• :variants — A map of target-specific variant overrides.

When force build is used, all unrecognized options are passed through to use Zig.

Environment variables

• HTTP_PROXY / http_proxy — HTTP proxy.
• HTTPS_PROXY / https_proxy — HTTPS proxy.
• HEX_CACERTS_PATH — Path to custom CA certificates.
• TARGET_ARCH, TARGET_OS, TARGET_ABI — Cross-compilation overrides (Nerves).
• ZIGLER_PRECOMPILED_GLOBAL_CACHE_PATH — Pre-seeded cache for offline builds (NixOS).
• ZIGLER_PRECOMPILED_FORCE_BUILD_ALL — Force build for all packages if "1" or "true".