First Pipeline

First Pipeline

This walkthrough builds a small pipeline from scratch. It uses generic phase and scope names; adapt them to your project.

Goal

A build.lua that:

1. Generates code and docs (in parallel)
2. Compiles the code
3. Exposes a beez build workflow and a beez hello task

Step 1: Create build.lua

At your repository root:

-- build.lua

step({
    name = "gen-docs",
    phase = "generate",
    scope = "docs",
    output = { "docs.out" },
    run = "echo 'generated docs' > docs.out",
})

step({
    name = "gen-code",
    phase = "generate",
    scope = "code",
    output = { "gen.out" },
    run = "echo 'generated code' > gen.out",
})

step({
    name = "compile",
    phase = "compile",
    scope = "code",
    input = { "gen.out" },
    output = { "build.out" },
    run = "echo 'compiled' > build.out",
})

order("gen-code", "compile")

workflow("build", {
    { parallel = {
        { phase = "generate", scope = "docs" },
        { phase = "generate", scope = "code" },
    }},
    { phase = "compile", scope = "code" },
})

task("hello", "echo hello from beez")

Step 2: Run it

From the same directory:

beez hello          # runs the task
beez build          # runs the workflow
beez --list steps   # shows registered steps
beez --list workflows

Expected flow for beez build:

1. gen-docs and gen-code run in parallel
2. compile runs after gen-code (because of order())
3. gen-docs is not on the critical path to compile

Step 3: Run a subset

Run only one phase+scope:

beez -p generate:docs

Run a single step:

beez -s compile

Step 4: Add project config (optional)

Create config.lua:

return {
    cache = {
        enabled = true,
        path = ".cache",
    },
    env = {
        load_dotenv = true,
    },
}

Load it at the top of build.lua:

beez.config(require("config"))

Step 5: Use environment variables (optional)

Create .env:

BUILD_MODE=release

Read it in build.lua:

local mode = beez.env("BUILD_MODE") or "debug"

Use mode in your shell commands or step config as needed.

What to try next

Change	What you learn
Remove order("gen-code", "compile")	gen-code and compile may run in parallel in the same level (until compile fails without gen.out)
Add input / output globs	Step cache can skip unchanged work (see Caching when available)
Replace shell run with a Lua function	Per-file logic and success cache (Step Context, DSL Patterns)
Add more scopes under compile	Independent variants selectable via workflow or -p

Minimal starting point

If you only need a quick shell command, you do not need steps or workflows yet:

task("hello", "echo hello > hello.out")
task("clean", "rm -f hello.out")

Add steps and workflows when you need grouping, caching, or parallelism.

Related pages

• Core Concepts - steps, tasks, workflows in detail
• Phases and Scopes - naming and CLI filtering
• Parallel Execution and Dependencies - order() and workflow parallelism
• Project Layout - config.lua, .env, .cache/