C3nif.Precompiled (C3nif v0.2.0)
View SourceFetch and verify precompiled C3 NIF artifacts.
When a module uses use C3nif, otp_app: ..., precompiled: [base_url: ..., version: ...],
this module checks whether a prebuilt shared library is available for the host
target. If present, it is downloaded (or taken from the local cache), SHA-256
verified against a checksum manifest, and extracted into the OTP app's priv/
directory — skipping the c3c source compile entirely.
This mirrors the workflow established by rustler_precompiled for Rust NIFs:
maintainers run mix c3nif.precompile to produce a per-target matrix of
archives and a checksum-<version>.exs file, then upload both to a release
hosting URL. Consumers add the checksum file to their repository so installs
fail loudly when an artifact has been tampered with.
Host triple
Target triples match the short names reported by c3c --list-targets:
linux-x64,linux-aarch64macos-x64,macos-aarch64windows-x64,windows-aarch64
target_triple/0 maps the current BEAM host to one of these. Pass it into
artifact_name/3 to derive the expected archive filename.
Summary
Functions
Derive the archive filename for a module + version + target triple.
Return the local cache directory where downloaded archives are stored.
Honors the XDG_CACHE_HOME env var, falling back to ~/.cache.
Default target triples for the precompile matrix.
Download an artifact from url into the local cache and return its path.
If already cached, skip the download.
Extract a .tar.gz archive into a destination directory.
Returns the list of extracted file paths.
Compute the "sha256:<hex>" checksum of a file.
Return the shared-library extension for a given target triple.
Load and parse a checksum-<version>.exs manifest file.
Return the c3c target triple for the current host, or {:error, reason} if
the host isn't a supported combination.
Try to install a precompiled artifact into priv/ for the given module.
Verify that a file's SHA-256 matches the expected checksum from a manifest.
Functions
Derive the archive filename for a module + version + target triple.
Example: artifact_name("Elixir.MyApp.Nif", "0.1.0", "linux-x64") →
"libElixir.MyApp.Nif-0.1.0-linux-x64.tar.gz".
Return the local cache directory where downloaded archives are stored.
Honors the XDG_CACHE_HOME env var, falling back to ~/.cache.
Default target triples for the precompile matrix.
Download an artifact from url into the local cache and return its path.
If already cached, skip the download.
Extract a .tar.gz archive into a destination directory.
Returns the list of extracted file paths.
Compute the "sha256:<hex>" checksum of a file.
Return the shared-library extension for a given target triple.
Load and parse a checksum-<version>.exs manifest file.
The file is expected to evaluate to a map of filename => "sha256:<hex>".
Returns {:ok, map} on success or {:error, reason} otherwise.
Return the c3c target triple for the current host, or {:error, reason} if
the host isn't a supported combination.
Try to install a precompiled artifact into priv/ for the given module.
Options
:module— the module whose NIF is being installed:otp_app— the OTP app (used to locatepriv/):base_url— the URL prefix where artifacts are hosted:version— the version string used in the artifact filename:checksums_path— absolute path to the checksum manifest.exs:nif_basename— the base filename without extension (e.g.libElixir.MyApp.Nif)
Returns {:ok, dest_path} on success, {:error, reason} otherwise. Callers
should fall back to source compilation when this returns an error.
Verify that a file's SHA-256 matches the expected checksum from a manifest.