# `ExclosuredPrecompiled`

Download precompiled WASM modules for Exclosured libraries.

Library authors compile their Rust code to `.wasm` and `.js` files once,
upload them to a GitHub Release, and publish checksums to Hex. Consumers
get precompiled WASM without needing Rust, cargo, or wasm-bindgen.

Since all Exclosured modules target `wasm32-unknown-unknown`, there is
only **one compilation target**. No platform detection needed.

## Environment Variables

  * `HTTP_PROXY` or `http_proxy` - HTTP proxy configuration
  * `HTTPS_PROXY` or `https_proxy` - HTTPS proxy configuration
  * `HEX_CACERTS_PATH` - Custom CA certificates file path.
    Defaults to `CAStore.file_path/0` if CAStore is available.
  * `MIX_XDG` - If present, uses `:filename.basedir/3` with `:linux`
    for resolving the user cache directory.
  * `EXCLOSURED_PRECOMPILED_GLOBAL_CACHE_PATH` - Override the global
    cache directory. Useful for systems that cannot download at compile
    time (e.g., NixOS). Artifacts must be pre-downloaded to this path.
  * `EXCLOSURED_PRECOMPILED_FORCE_BUILD_ALL` - Set to `"1"` or `"true"`
    to force building from source for all packages, ignoring precompiled
    downloads. Equivalent to `config :exclosured_precompiled, force_build_all: true`.

## For library authors

See the [Precompilation Guide](PRECOMPILATION_GUIDE.md) for a step-by-step
walkthrough.

    defmodule MyLibrary.Precompiled do
      use ExclosuredPrecompiled,
        otp_app: :my_library,
        base_url: "https://github.com/user/repo/releases/download/v0.1.0",
        version: "0.1.0",
        modules: [:my_processor, :my_filter]
    end

## For library consumers

Just add the library to your deps. If it uses `ExclosuredPrecompiled`,
WASM files are downloaded automatically during `mix compile`.

To force building from source:

    config :exclosured_precompiled, force_build: true

Or per-module:

    config :exclosured_precompiled, force_build: [:my_module]

# `archive_name`

Generate the archive filename for a module.

Format: `MODULE-vVERSION-wasm32.tar.gz`

Since all Exclosured modules compile to `wasm32-unknown-unknown`,
there is only one archive per module per version.

# `cached_path`

Path to the cached archive in the global cache directory.

# `checksum_file_path`

Path to the checksum file for a module.

# `compute_checksum`

Compute the SHA-256 checksum of a file.

Returns a string in the format `"sha256:HEX_HASH"`.

# `download`

Download a file from a URL. Returns `:ok` or `{:error, reason}`.

# `download_url`

Build the download URL for an archive.

# `download_with_retry!`

Download a file from a URL to a local path with retry support.

Retries up to 3 times with exponential backoff on failure.
Respects `HTTP_PROXY`, `HTTPS_PROXY`, and `HEX_CACERTS_PATH` environment
variables.

# `ensure_downloaded!`

Download precompiled WASM modules if not already present.
Called at compile time from the `__using__` macro.

# `extract!`

Extract a tar.gz archive to a directory.

Writes a `.sha256` file next to each extracted file for independent
integrity verification.

# `force_build_reason`

Returns the reason for force build, or `nil` if precompiled download should be used.

Pre-release versions (containing `-dev`, `-rc`, etc.) automatically
trigger a force build since no precompiled binaries exist for them.

# `generate_checksums`

Generate checksums for all archives in a directory.

Returns a map of `%{"filename" => "sha256:hex_hash"}`.

# `load_checksums`

Load checksums from the checksum file shipped with the Hex package.

# `package_module`

Package a compiled WASM module into a tar.gz archive for publishing.

Returns the path to the created archive.

# `set_force_build_all`

Check if force build is enabled for any of the given modules.

Force build is triggered by:
  * `EXCLOSURED_PRECOMPILED_FORCE_BUILD_ALL` env var set to `"1"` or `"true"`
  * `config :exclosured_precompiled, force_build_all: true`
  * `config :exclosured_precompiled, force_build: true`
  * `config :exclosured_precompiled, force_build: [:module_name]`

# `verify_checksum!`

Verify the checksum of a downloaded archive against the checksum file.

# `write_checksum_file`

Write checksums to a file.

---

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