DSL Overview

DSL Overview

File location

Beez looks for build.lua in the project root (current working directory when you run beez).

You can use normal Lua at the top level: local variables, functions, require(), and loops to generate steps.

Loading process

1. Beez creates a Lua 5.4 state
2. Opens base and package standard libraries
3. Registers DSL globals (see below)
4. Executes build.lua with script_file
5. Merges any beez.config(...) calls into project settings
6. Populates the registry (tasks, steps, workflows, order hints)

If loading fails, Beez prints Lua error: or DSL error: and exits. No steps run.

Global functions

Function	Purpose
step({ ... })	Register a step
task(name, cmd)	Register a shell task
task(name, { ... })	Register a task with multiple actions
task("org/plugin:task")	Import a task from a plugin
workflow(name, { ... })	Register a workflow
workflow(name, "org/plugin:workflow")	Import a workflow from a plugin
workflows({ name = table_or_ref, ... })	Register or import multiple workflows
configure({ { target, config }, ... })	Batch-configure plugins and steps
configure_plugin("org/plugin", config)	Configure one plugin
order(before, after, ...)	Declare step ordering (chain)
reqpack { ... }	Declare external dependencies and Beez plugins

The beez table

Member	Purpose
beez.config(table)	Merge project Beez settings
beez.env(key)	Read environment variable or .env value
beez.env_or(key, …, default)	Read env with fallback
beez.shell.run, beez.char.quote, beez.increment.run	Plugin helpers — Plugin System
beez.fs, beez.net, beez.data, …	See Lua API Overview

See Beez API for config and env. All other beez.* modules are documented under Lua API in the sidebar.

Registration rules

• Duplicate names: registering the same task, step, or workflow name again replaces the previous entry
• Order of declarations: configure_step() can appear before or after step(); pending config is merged when the step is registered
• Order hints: order() can appear before or after step declarations; hints apply only when both step names appear in the same phase+scope group (missing names are ignored)

What build.lua does not do

• It does not run steps by itself. Execution happens when you invoke the CLI (CLI)
• It is not reloaded during a run. Changes require a new beez invocation
• Callback functions are stored at load time and called later during execution

Lua libraries

Only base and package are opened by Beez. Use require("config") for project modules.

Avoid relying on io, os, or debug unless you open them yourself (not recommended in portable build.lua files).

Errors at load time

Common failures:

Error	Cause
step is missing required field 'name'	Invalid step table
field 'run' must be a string or function	Missing or wrong run
task '...' table form must be a list of actions	Task table is not a command list
workflow parallel step requires at least one phase	Empty parallel block
Lua syntax error	Invalid Lua

Fix the script and rerun. Use beez --list steps to verify registration.

Next steps

• Step Declaration - define work units
• Workflow Declaration - wire phases together
• Plugin System - Beez plugins, config DSL, standard workflows
• ReqPack Declaration - declare tool and library dependencies
• First Pipeline - hands-on tutorial