Crate zlayer_toolchain 

zlayer-toolchain — reusable runtime toolchain provisioning.

This is a leaf crate: it depends only on other leaf crates (zlayer-paths, zlayer-registry, zlayer-types) and external crates. It depends on neither zlayer-agent nor zlayer-builder. It exists to break the zlayer-builder -> zlayer-agent build cycle: the macOS sandboxes (Seatbelt / HCS) have no package manager, so this crate is “our apt-get” — it provisions a named tool into a self-contained, absolute-prefix keg and returns a ToolchainHandle describing how to run it.

Provisioning strategy (macOS)

A keg is produced one of two ways, both relocation-free (no @@HOMEBREW@@):

• Source build (source_build): fetch the Homebrew formula’s urls.stable.url source tarball and build it at an absolute keg prefix with the host Command Line Tools (the homebrew-core C-tool population: git, jq, cmake, …).
• Prebuilt fetch (prebuilt): land a self-contained vendor archive for the language toolchains (go/node/rust/…).

Every keg carries a manifest::KegManifest (toolchain.json) describing its path_dirs + env, so the resolver is generic — no tool is special- cased on the handle path.

Surface

• ensure_toolchain — provision a named tool and return a ToolchainHandle.
• probe_ready_toolchain — non-blocking, filesystem-only .ready probe that reconstructs a handle from an already-provisioned keg.

The old Homebrew bottle resolver/installer (download a prebuilt bottle and rewrite its @@HOMEBREW@@ install-name placeholders) has been removed entirely — see the module docs on source_build for why that path was a dead end under Seatbelt.

Re-exports

pub use error::Result;

pub use error::ToolchainError;

pub use lockfile::ToolchainLockfileExt;

pub use lockfile::LOCKFILE_NAME;

Modules

brew_emulate

Brew-emulate fallback: build a homebrew-core formula with real Homebrew installed at the keg prefix, for the macOS long tail the generic crate::source_build recipe runner cannot reproduce.

error

Error types for the toolchain provisioning subsystem.

formula

The single Homebrew formula parser shared by every macOS provisioning path.

lockfile

On-disk I/O for the toolchain lockfile (zlayer-toolchains.lock).

manifest

The unified keg manifest (toolchain.json).

package_index

HTTP client for the ZLayer package index (packages.zlayer.dev) plus the shared streaming-download-with-integrity primitive.

prebuilt

Fetch self-contained, relocation-free language toolchains as prebuilt vendor archives — “our apt-get” for the macOS sandbox, the prebuilt arm.

source_build

Build runtime toolchains from source into a self-contained, absolute cache keg — “our apt-get” for the macOS sandbox, which has no package manager.

windows

Windows keg provisioning — “our apt” for the HCS sandbox.

Structs

LockedTool

One pinned toolchain entry: an exact, integrity-checked resolution.

ToolchainHandle

A provisioned toolchain: where it lives and how to run it.

ToolchainLockfile

The parsed toolchain lockfile: a schema tag, a generation timestamp, and the set of pinned tools (serialized as a TOML [[tool]] array of tables).

Enums

ToolPlatform

Target platform for a toolchain provisioning request.

Functions

ensure_toolchain

Ensure a runtime tool is provisioned and return a handle describing how to run it.

probe_ready_toolchain

Non-blocking, filesystem-only probe for an already-provisioned keg.

resolve_locked_tool

Resolve a tool to a fully-pinned LockedTool by live-resolving its exact version + download URL, streaming the artifact to a temp file, and hashing the bytes (verifying against the upstream-published digest when one exists).