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 is now part of the NIF module, but Guppy still forces source builds by default because no release artifacts or checksum file are published yet. The remaining work is the artifact/release process:

  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-darwinsource-build supported; precompiled artifact workflow configuredprimary local development target; only current RustlerPrecompiled target
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.