Configure Step

Configure Step

Attach structured configuration to a step without hard-coding values in the callback.

Plugins: use configure({ { "coditary/plugin", { ... } } }) in build.lua and the Plugin Config DSL (defaults, profile_defs, finalize) in beez_plugin.lua. See Plugin System.

configure() — batch plugin and step config

configure({
    { "coditary/cppcheck", {
        check_rev = "2",
        steps = {
            cppcheck_check = { profiles = { "analyze", "security" } },
        },
    }},
    { ":my_local_step", { flag = true } },  -- leading ':' = standalone step
})

configure_plugin(name, config)

Configure one plugin by qualified name (organization/plugin).

configure_step(name, config)

configure_step("lint", {
    patterns = { "src/**/*.cpp" },
    lint_rev = "1",
})

step({
    name = "lint",
    phase = "qa",
    scope = "default",
    run = function(ctx)
        local config = ctx.get_config()
        local files = ctx.glob(config.patterns)
        -- ...
        return 0
    end,
})

Argument	Type	Description
name	string	Step name (must match step({ name = ... }))
config	table	Arbitrary Lua table

Before or after step()

configure_step() can appear before the step() declaration. Beez stores pending config and merges it when the step registers.

configure_step("shader", { shader_version = "450" })

step({
    name = "shader",
    phase = "generate",
    scope = "code",
    config = { output_dir = "build/shaders" },
    run = "echo shader",
})

Inline config on step()

step({
    name = "lint",
    phase = "qa",
    scope = "default",
    config = { patterns = { "src/**/*.cpp" } },
    run = function(ctx) ... end,
})

Inline config and configure_step() merge. Later configure_step() calls merge on top of earlier config for the same step name.

Task config overlay

Tasks can pass config when invoking a step:

task("lint-strict", {
    { name = "lint", config = { warnings_as_errors = true } },
})

Merge order (lowest to highest priority):

1. Inline step({ config = ... })
2. configure_step() (later calls override earlier ones for the same step)
3. Task invocation { config = ... }

Reading config in callbacks

local config = ctx.get_config()
if config == nil then
    return 1
end

Returns nil if the step has no config.

Cache fingerprint

Step config participates in step cache keys. The config table is serialized to a fingerprint string. Changing config invalidates cached results for that step.

Use revision keys when tool behavior changes without source changes:

configure_step("lint", {
    patterns = { "src/**/*.cpp" },
    lint_rev = "2",  -- bump when clang-tidy config changes
})

Success cache (per-file) also uses step config. See Success Cache.

Config content

Any JSON-like Lua table is allowed: strings, numbers, booleans, nested tables, string arrays.

Avoid storing functions in config tables (they are not serialized for caching).

Next steps

• Step Context - ctx.get_config(), ctx.glob()
• Task Declaration - per-invocation config overlay
• DSL Patterns - incremental lint/format pattern