Native releases and publishing

Copy Markdown View Source

OgEx uses RustlerPrecompiled so ordinary Hex consumers download a native artifact instead of compiling Takumi and the OgEx NIF locally.

Consumer installation

Released versions require only the Hex dependency:

{:og_ex, "~> 0.2"}

During mix compile, RustlerPrecompiled selects the current operating system, CPU architecture, and NIF ABI, downloads the corresponding GitHub release archive, and verifies it against the checksum metadata shipped in the Hex package.

Rust is required when developing an unreleased checkout, targeting a platform without an archive, or explicitly testing a source build:

OG_EX_BUILD=1 mix deps.compile og_ex --force

Source builds currently require the Rust version pinned in rust-toolchain.toml.

Set the environment variable on the first command that compiles OgEx. Without it, an unreleased checkout attempts to download an archive for its version and receives a 404 because that GitHub release does not exist yet.

Supported release targets

The release workflow builds NIF ABI 2.15 archives for:

  • Linux GNU on x86-64 and ARM64.
  • Linux musl on x86-64 and ARM64.
  • macOS on Intel and Apple Silicon.
  • Windows MSVC on x86-64.

NIF 2.15 remains compatible with newer NIF 2.x runtimes. New targets can be added to the workflow and native-module configuration without changing the Elixir renderer API.

Maintainer release flow

  1. Set the intended version in mix.exs.
  2. Run the complete Elixir and Rust test suites.
  3. Commit the version and tag the exact commit as v<version>.
  4. Push the commit and tag to GitHub.
  5. Wait for .github/workflows/release.yml to attach every native archive, generate their checksum metadata, test the released NIF, and publish the package and documentation to Hex.

The publish_hex job runs only after every native target succeeds and uses the protected hex-production GitHub environment. Configure that environment with a HEX_API_KEY secret restricted to api:write; an optional required-reviewer rule can keep publication subject to maintainer approval.

For a manual recovery release, generate the mandatory checksum metadata after the final artifacts have been attached:

   mix rustler_precompiled.download OgEx.Native --all --print

Then confirm the checksum file is included:

   mix hex.build --unpack

Finally publish with mix hex.publish.

Do not publish a stable Hex release before every advertised archive and the generated checksum-Elixir.OgEx.Native.exs file are available. Unreleased versions do not have downloadable archives; maintainers and path dependency users must explicitly set OG_EX_BUILD=1 until the corresponding release has been built.