# `ZiglerPrecompiled`
[🔗](https://github.com/dannote/zigler_precompiled/blob/v0.1.3/lib/zigler_precompiled.ex#L1)

Download and use precompiled Zig NIFs safely with checksums.

ZiglerPrecompiled is a tool for library maintainers that rely on
[Zigler](https://github.com/E-xyza/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"`.

# `available_nifs`

Returns URLs for all platform NIFs based on stored metadata.

# `current_target_nifs`

Returns the NIF URLs for the current platform.

# `download_nif_artifacts_with_checksums!`

Downloads all NIF artifacts and returns a list of checksum maps.

Each map has `:path`, `:checksum`, and `:checksum_algo` keys.

# `target`

Returns the Zig-style target triple for the current system.

The triple has the format `"ARCH-OS-ABI"`, e.g. `"x86_64-linux-gnu"`,
`"aarch64-macos-none"`.

# `write_checksum!`

Writes the checksum file for a module.

---

*Consult [api-reference.md](api-reference.md) for complete listing*