Lua API Workers

Lua API — Workers (ctx:spawn, ctx:wait)

Run shell commands in the background inside a Lua step callback.

Only available in step({ run = function(ctx) ... end }).

ctx:spawn(options)

Field	Required	Type
cmd	yes	string or { string, ... }
inputs	no	glob list for cache inputs
outputs	no	glob list for cache outputs
name	no	override auto name {step}-{n}

Returns: worker handle (number).

ctx:wait(handle [, options])

Wait for one worker. Pass an options table to select return fields:

Option	Return field
exitCode	result.exitCode
output	result.output (captured stdout/stderr)
duration	result.duration
cached	result.cached
name	result.name
id	result.id
dryRun	result.dryRun

ctx:wait_all(handles [, options])

Same options for every handle. Returns 1-based array of result tables in handle order.

Example

step({
    name = "compile",
    phase = "build",
    scope = "cpp",
    run = function(ctx)
        local jobs = {}
        for _, src in ipairs(beez.fs.glob("src/**/*.cpp")) do
            jobs[#jobs + 1] = ctx:spawn({ cmd = "g++ -c " .. src })
        end
        for _, result in ipairs(ctx:wait_all(jobs, { exitCode = true })) do
            if result.exitCode ~= 0 then error("compile failed") end
        end
        return 0
    end,
})

Full reference: docs/worker-api.md

---

← Lua API Overview