Project Config

Project Config

Project settings live in your repository and apply to everyone who builds that project (unless overridden by global config or CLI flags).

Loading project config

Beez does not auto-discover config.lua. You load it from build.lua:

beez.config(require("config"))

Place config.lua next to build.lua. Lua's require resolves it from the project root when Beez loads the build script.

Inline config

You can pass the table directly without a separate file:

beez.config({
    cache = {
        enabled = true,
        path = ".cache",
    },
})

Multiple calls merge in order:

beez.config(require("config"))
beez.config({
    ui = { output_mode = "verbose" },
})

Later calls win for the same key.

Example config.lua

return {
    performance = {
        cache_write_strategy = "phase",
        cache_fs_metadata = true,
    },

    cache = {
        path = ".cache",
        enabled = true,
        compress = {
            algorithm = "gzip",
            mode = "always",
        },
    },

    env = {
        load_dotenv = true,
        vars = {
            BUILD_TYPE = "Release",
        },
        hash_vars = {
            "CC",
            "CXX",
            "BUILD_TYPE",
        },
    },
}

When config is applied

beez.config(...) runs while build.lua is parsed, before any workflow or task executes. That means:

• Settings are available for the whole run
• beez.env() in build.lua sees vars after environment application
• Step callbacks use the merged config from the start of execution

Config vs step config

Do not confuse project Beez settings with per-step config:

Mechanism	Purpose
beez.config({ ... })	Global Beez behavior (cache, UI, env)
configure_step("name", { ... })	Data for one step (patterns, tool revisions)
step({ config = { ... } })	Inline step config at declaration time

Step config is documented in Configure Step and Step Context.

Overriding for one run

Commit shared defaults in config.lua. Override locally or in CI without editing files:

beez --no-cache build
beez -j 1 --verbose test
beez --show-config

Next steps

• Environment Variables - env section in detail
• Cache Settings - cache section
• Project Layout - file locations