ZiglerPrecompiled

Download and use precompiled Zigler NIFs safely with SHA-256 checksums.

Removes the need for end users to install the Zig compiler. Library maintainers build NIFs in CI for each platform, upload them as release artifacts, and ship a checksum file with the Hex package.

Installation

def deps do
  [
    {:zigler_precompiled, "~> 0.1.0"}
  ]
end

For library maintainers who also need to compile from source:

def deps do
  [
    {:zigler_precompiled, "~> 0.1.0"},
    {:zigler, "~> 0.15", optional: true}
  ]
end

Quick start

Defining a precompiled NIF module

defmodule MyApp.Native do
  version = Mix.Project.config()[:version]

  use ZiglerPrecompiled,
    otp_app: :my_app,
    base_url: "https://github.com/me/my_project/releases/download/v#{version}",
    version: version,
    nifs: [
      add: 2,
      multiply: 2
    ]
end

The :nifs option is required — it declares which NIF functions the module exports as {name, arity} pairs. These generate stub functions that are replaced when the precompiled .so loads.

When force_build: true (or a pre-release version like "0.1.0-dev"), the :nifs option is ignored and compilation is delegated to use Zig with Zigler’s full wrapper generation.

Building and releasing

1. Tag a release and push
2. CI builds the NIF for each target and uploads .tar.gz artifacts
3. Run mix zigler_precompiled.download MyApp.Native --all --print
4. Include checksum-*.exs in your Hex package files
5. Publish to Hex

See PRECOMPILATION_GUIDE.md for the full walkthrough.

How it works

Zigler generates rich NIF wrapper functions (type marshalling, error tracing) at compile time by analyzing Zig source. The compiled .so registers NIF functions under marshalled-<name> names. ZiglerPrecompiled generates matching stubs that delegate to these, so when :erlang.load_nif runs at @on_load, the stubs are replaced with the real implementations.

This has been verified to work end-to-end with QuickBEAM (20 NIFs including resources, dirty schedulers, C interop with QuickJS and Lexbor).

License

MIT