Documentation
Helpers Overview
Functions available in recipe scripts with const RECIPE_API = 1; and a literal NEEDS declaration. Helpers take explicit paths and return explicit results; paths come from the arguments of build(src, out) and from the engine constants WORK, INPUTS and DEPS.
Where Helpers Run
A recipe that starts no program runs on the host, where helpers reach only the run's own folders (src, out, WORK, INPUTS) and the hosts in NEEDS.network. Any other recipe runs inside its Ginux domain, under its filesystem, task, memory and network limits, where paths refer to the domain's filesystem. Commands need their binaries in the selected image or in dependency tools. Network helpers need an endpoint declared in NEEDS.network. Caller endpoint/limit options only narrow that authority, including dependencies. Declare all imported inputs and returned outputs with their kinds.
A helper that fails throws, and the error fails the step unless the recipe handles it. verify only reads and starts no program.
Example
const RECIPE_API = 1;
const NEEDS = #{ outputs: #{ program: "file" } };
const PACKAGE = #{ name: "helper-demo", version: "1.0", description: "Writes a small script" };
fn build(src, out) {
write_file(out, "#!/bin/sh\nprintf 'hello\\n'\n");
chmod(out, 0o755);
}
fn verify(out) {
if !is_file(out) { throw "the program was not written"; }
} Categories
- Acquire - Verified downloads, pinned Git checkouts and checksums
- Build - Archive extraction and root filesystem assembly
- Install - Copying files into the output, disk space and package tools
- Filesystem - Path checks, directories, links, file contents and globs
- Environment - Environment variables, program lookup and logging
- Commands - Running programs and shell commands
- HTTP - Release metadata and version strings
- Paths - Path and string utilities
System Tree and Saved Values
| Helper | Does |
|---|---|
| put(tree, path, text, mode) | Write text at path in a system tree, with mode in the target metadata. |
| put_link(tree, path, target) | A symbolic link at path to target. |
| tree_text(tree, path) | The text of a packaged file; fails naming the file when the packages no longer ship it. |
| enable_service(tree, unit, service) | Enable a systemd unit on an rpm tree or an OpenRC service on an apk tree. |
| save(name, value) / saved(name) | Keep a value across an interruption, and read it back. |
| checkpoint(name) / reached(name) | Record a checkpoint, and tell whether this run was restored from it or a later one. |
The full list of registered helpers and signatures is man 7 recipe-helpers.