Docs: Build Helpers

Documentation

Build Helpers

Functions for extracting archives and assembling root filesystem trees. For running compilers and build tools, see the Commands helpers.

extract

extract(archive, dest) unpacks an archive into dest, detecting the format from the file name. Every member path is validated; an entry that would escape dest fails the extraction.

FormatExtensions
tar.gz.tar.gz, .tgz
tar.xz.tar.xz, .txz
tar.bz2.tar.bz2, .tbz2
tar.zst.tar.zst, .tzst
zip.zip
Rhai
let archive = download("https://example.com/foo-1.0.tar.xz", join_path(WORK, "foo-1.0.tar.xz"), "<sha256>");
extract(archive, WORK);
// creates WORK/foo-1.0/

extract_with_format

extract_with_format(archive, dest, format) names the format explicitly (tar.gz, tar.xz, tar.bz2, tar.zst or zip), for files whose name doesn't say.

Rhai
extract_with_format(archive, WORK, "tar.gz");

Root Filesystem Helpers

System recipes assemble a complete root filesystem without build-host privileges. These helpers unpack packages into a root directory and record each file's intended owner, mode and extended attributes in the root's target manifest; the image writer applies that metadata, not the build user's.

HelperBehavior
target_extract_rpm(rpm, root)Unpack an RPM into root, recording its ownership, modes and capabilities.
target_extract_tar(archive, root)Unpack a tar archive into root the same way.
target_capture_apks(root, archives)Record the metadata of the packages apk installed under root, read from their pinned .apk archives.
target_mode(root, path, mode)Set the recorded mode of one path, such as 0o440 for a sudoers file.
target_finalize(root)Finish the manifest after the recipe's own changes: paths that no longer exist are dropped and files the recipe created are owned by root.
Rhai
for rpm in glob_list(join_path(INPUTS.rpms, "*.rpm")) {
    target_extract_rpm(rpm, rootfs);
}
target_mode(rootfs, "etc/sudoers.d/10-wheel", 0o440);
target_finalize(rootfs);

Running Build Commands

Run build tools with exec_checked, setting the working directory and environment for that command only:

Rhai
fn build(src, out) {
    exec_checked("./configure", ["--prefix=" + PREFIX], #{ cwd: src.source });
    exec_checked("make", ["-j" + JOBS], #{ cwd: src.source });
}

See the Command Helpers for exec, exec_output and the shell variants.