Distribution and native artifacts

Copy Markdown View Source

Guppy ships a checksummed precompiled NIF for supported targets and falls back to source builds (GUPPY_NATIVE_FORCE_BUILD=1 forces them; the repo itself always source-builds via mise.toml). The native runtime is a single Rustler NIF built from native/guppy_nif; Rustler builds and copies it into priv/native/ during normal Mix compilation.

The current runtime baseline has production-hardening coverage for bounded native requests, stale queued request expiry, Rustler-monitored event-target cleanup, server restart cleanup/reopen behavior, clean-install NIF loading, and generated package smoke loading. Consumers download the published artifact by default; the packaged crate keeps the source-build fallback working.

Hex release runbook

Precompiled artifacts and checksums are required before the first hex cut; do not publish a source-build-only package. The order of operations:

  1. Make sure scripts/check, scripts/clean_install_load_test, scripts/package_smoke, and mix hex.build --unpack are green.
  2. Finalize the CHANGELOG.md entry and tag vX.Y.Z; pushing the tag runs .github/workflows/precompiled-nif.yml, which builds and attaches the aarch64-apple-darwin NIF artifact to the GitHub release.
  3. Validate the artifact: with GUPPY_NATIVE_FORCE_BUILD unset and a clean build, mix compile must download and load it, and mix test must pass.
  4. Generate and commit the checksum file with mix rustler_precompiled.download Guppy.Native.Nif --all --print (mix.exs already packages any checksum-*.exs).
  5. Flip Guppy.Native.Nif from force-source-build to precompiled-by-default (keep an env var to force source builds), and re-run every gate in step 1 plus step 3.
  6. mix hex.publish.

Precompiled artifact plan

rustler_precompiled serves the published artifact by default and checksum-Elixir.Guppy.Native.Nif.exs is committed; GUPPY_NATIVE_FORCE_BUILD=1 forces source builds. The artifact/release process per target:

  1. Keep the RustlerPrecompiled target list constrained to currently supported and CI-built targets.
  2. Build the NIF artifact with .github/workflows/precompiled-nif.yml for every target in Guppy.Native.Nif's @precompiled_targets list.
  3. Add CI jobs that install/load the produced artifact and run at least mix test before claiming precompiled support.
  4. Generate and package the required checksum-*.exs file with mix rustler_precompiled.download Guppy.Native.Nif --all --print after release artifacts exist; mix.exs includes any generated checksum-*.exs file when present while keeping source-only package smoke builds green before artifacts exist.
  5. Document how release artifacts are produced, signed when needed, and attached.
  6. Flip the default from source-build to precompiled-download only after the advertised artifact set is built and load-tested.
  7. Keep Rustler source compilation as the fallback path.
  8. Keep scripts/check, mix compile, scripts/clean_install_load_test, and scripts/package_smoke green for source builds.

Initial target matrix

TargetStatusNotes
aarch64-apple-darwinprecompiled artifact published, checksummed, and load-validatedprimary target; source-build fallback also CI-covered
x86_64-apple-darwinsource-build/precompiled plannedneeds CI/build-host confirmation
aarch64-unknown-linux-gnusource-build/precompiled plannedGPUI runtime behavior needs validation
x86_64-unknown-linux-gnusource-build/precompiled plannedGPUI runtime behavior needs validation
x86_64-pc-windows-msvcsource-build/precompiled plannedGPUI/runtime bootstrap needs validation

Do not claim a target as precompiled-supported until CI builds and load-tests the artifact. Do not add planned targets to Guppy.Native.Nif's @precompiled_targets or the precompiled artifact workflow until they are supported. Avoid publishing broader RustlerPrecompiled defaults such as musl, Windows GNU, ARMv7, or RISC-V unless GPUI support and CI load tests prove them viable.