Documentation
Command Helpers
Functions for running programs and shell commands inside the recipe's domain.
Overview
Commands run inside Ginux and need their binaries in the selected image or in dependency tools, whose executables are on PATH. Prefer the exec family: arguments are an array, so nothing is reparsed by a shell. Their output goes to stderr with the rest of the diagnostics.
| Helper | On nonzero exit | Returns |
|---|---|---|
| exec_checked(cmd, args[, options]) | Throws | () |
| exec_output(cmd, args[, options]) | Throws | stdout as a string |
| exec(cmd, args[, options]) | Returns the status | exit status (int) |
| shell(cmd) / shell_in(dir, cmd) | Throws | () |
| shell_output(cmd) / shell_output_in(dir, cmd) | Throws | stdout as a string |
| shell_status(cmd) / shell_status_in(dir, cmd) | Returns the status | exit status, or -1 if it could not run |
exec_checked
Run a program and throw if it exits nonzero. The optional map sets cwd and env for this command only; the worker's own directory and environment don't change.
exec_checked("cargo", ["build", "--release", "--locked", "--offline"], #{
cwd: INPUTS.source,
env: #{ CARGO_HOME: join_path(WORK, "cargo") },
}); exec_output
Run a program and return its stdout. Throws if it exits nonzero.
let version = trim(exec_output("rustc", ["--version"]));
let files = exec_output("find", [src.source, "-name", "*.c"]); exec
Run a program and return its exit status, for a recipe that handles failure itself.
if exec("make", ["check"], #{ cwd: src.source }) != 0 {
warn("test suite failed");
} shell / shell_in
Run a command string with sh -c, in the current or the given directory. Use them only when you need shell syntax, and quote any data you put in the string. For a pipeline, check every stage: bash -o pipefail -c … or separate checked steps.
shell_in(src.source, "./configure --prefix=/usr CFLAGS='-O2 -g'");
exec_checked("bash", ["-o", "pipefail", "-c", "rpm2archive - < pkg.rpm | tar -x"], #{ cwd: WORK }); shell_output / shell_status
let commit = trim(shell_output_in(src.source, "git rev-parse HEAD"));
if shell_status_in(src.source, "test -f Makefile") != 0 {
exec_checked("./configure", [], #{ cwd: src.source });
}