Docs: Acquire Helpers

Documentation

Acquire Helpers

Functions for downloading, checking out and verifying source materials. Every payload is pinned: downloads need a "<sha256>", Git checkouts a full commit id.

Overview

Source facts (URL, version, digest) belong in the recipe. Declare them in SOURCES and Recipe downloads and unpacks them before build runs. These helpers are for a recipe that declares no SOURCES and has to download inside build, and they put what they fetch into WORK. Every server a recipe contacts, including each redirect target, must be in NEEDS.network, for example ["example.com:443"]. Caller --network-host can only narrow that declaration. These fragments need a complete recipe with real publisher URLs and digests and declared outputs; example.com is a placeholder.

Rhai
fn build(src, out) {
    let archive = join_path(WORK, "foo.tar.gz");
    download("https://example.com/foo.tar.gz", archive, "<sha256>");
    extract(archive, WORK);
}

download

download(url, dest, sha256[, resume]) downloads to the exact path dest and returns it. The full 64-hex SHA256 is required. Bytes are staged and checked (status, length, hash) and replace dest only after they verify, so a failed or truncated transfer never replaces a valid file. Pass true as the fourth argument to resume a partial download; the resumed response's identity and ranges are checked too.

Rhai
let iso = download(
    "https://example.com/large-file.tar.xz",
    join_path(WORK, "large-file.tar.xz"),
    "<sha256>",
    true
);

git_checkout

git_checkout(url, dest, commit) checks out a pinned commit into the exact directory dest and returns it. commit is a full 40- or 64-hex object id; the origin and the checked-out tree are validated. The URL must name the repository directly (Git redirects are disabled), and hooks, fsmonitor, replacement objects and submodule recursion are off. A local repository must be an imported input.

Rhai
let src = git_checkout(
    "https://github.com/neovim/neovim.git",
    join_path(WORK, "neovim"),
    "<full commit id>"
);

github_download_release

github_download_release(repo, pattern, dest_dir, sha256) picks the asset of the repository's latest release whose name matches the glob pattern, downloads it to dest_dir/<asset name> with the same verified download as download, and returns the path. The digest is required.

Rhai
let archive = github_download_release(
    "BurntSushi/ripgrep",
    "ripgrep-*-x86_64-unknown-linux-musl.tar.gz",
    WORK,
    "<sha256>"
);

verify_sha256 / verify_sha512 / verify_blake3

Check an existing file against an expected digest. Each throws if the digest is malformed or does not match.

Rhai
verify_sha256(archive, "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824");
verify_sha512(archive, "<sha512>");
verify_blake3(archive, "<blake3>");

recipe hash FILE prints all three digests for a file you are pinning.

fetch_sha256

fetch_sha256(url, filename) reads a remote checksum file (sha256sum format or SHA256 (filename) = …) and returns the hash listed for filename. It throws if there is none.

Warning
A digest fetched from the same unauthenticated source as the payload is not source verification. Pin the digest in the recipe when the publisher offers no signed checksum.