Docs: Command Helpers

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.

HelperOn nonzero exitReturns
exec_checked(cmd, args[, options])Throws()
exec_output(cmd, args[, options])Throwsstdout as a string
exec(cmd, args[, options])Returns the statusexit status (int)
shell(cmd) / shell_in(dir, cmd)Throws()
shell_output(cmd) / shell_output_in(dir, cmd)Throwsstdout as a string
shell_status(cmd) / shell_status_in(dir, cmd)Returns the statusexit 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.

Rhai
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.

Rhai
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.

Rhai
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.

Rhai
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

Rhai
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 });
}