ExclosuredPrecompiled (exclosured_precompiled v0.1.0)

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

Summary

Functions

archive_name(module_name, version)

Generate the archive filename for a module.

cached_path(archive_name)

Path to the cached archive in the global cache directory.

checksum_file_path(caller_module)

Path to the checksum file for a module.

compute_checksum(file_path)

Compute the SHA-256 checksum of a file.

download(url, dest)

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

download_url(base_url, archive_name)

Build the download URL for an archive.

download_with_retry!(url, dest, attempt \\ 1)

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

ensure_downloaded!(otp_app, base_url, version, modules, caller_module)

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

extract!(tar_path, dest_dir)

Extract a tar.gz archive to a directory.

force_build_reason(otp_app, modules, version \\ nil)

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

generate_checksums(archive_dir)

Generate checksums for all archives in a directory.

load_checksums(caller_module)

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

package_module(module_name, version, opts \\ [])

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

set_force_build_all(value)

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

verify_checksum!(file_path, archive_name, caller_module)

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

write_checksum_file(checksums, caller_module)

Write checksums to a file.

Functions

archive_name(module_name, version)

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(archive_name)

Path to the cached archive in the global cache directory.

checksum_file_path(caller_module)

Path to the checksum file for a module.

compute_checksum(file_path)

Compute the SHA-256 checksum of a file.

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

download(url, dest)

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

download_url(base_url, archive_name)

Build the download URL for an archive.

download_with_retry!(url, dest, attempt \\ 1)

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!(otp_app, base_url, version, modules, caller_module)

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

extract!(tar_path, dest_dir)

Extract a tar.gz archive to a directory.

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

force_build_reason(otp_app, modules, version \\ nil)

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(archive_dir)

Generate checksums for all archives in a directory.

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

load_checksums(caller_module)

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

package_module(module_name, version, opts \\ [])

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

Returns the path to the created archive.

set_force_build_all(value)

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!(file_path, archive_name, caller_module)

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

write_checksum_file(checksums, caller_module)

Write checksums to a file.