Project Layout

Project Layout

A Beez project is usually a repository root with a build.lua file. Beez uses the current working directory as the project root when you invoke it.

cd my-project
beez build

Shell steps run with that directory as their working directory.

Overview

Path	Role
build.lua	Pipeline definition (steps, tasks, workflows)
config.lua	Optional project settings (loaded by build.lua)
.env	Optional environment defaults
.cache/	Runtime cache and logs (created by Beez)
~/.config/beez/config.lua	Optional global user settings

build.lua

The main entry point. Beez looks for build.lua in the project root.

This file registers:

• step({ ... }) declarations
• task(...) shortcuts
• workflow(...) pipelines
• order(before, after) dependencies
• beez.config(...) project overrides

If build.lua is missing, Beez exits with an error.

Minimal example:

task("hello", "echo hello")

See the Lua DSL for the full API and First Pipeline for a hands-on tutorial.

config.lua

Beez does not load config.lua automatically. You load it from build.lua when you want shared project settings:

beez.config(require("config"))

config.lua returns a Lua table with the same shape as user config (performance, cache, ui, env). Keeping settings in a separate file keeps build.lua focused on pipeline logic.

Example config.lua:

return {
    performance = {
        cache_write_strategy = "phase",
    },
    cache = {
        path = ".cache",
        enabled = true,
    },
    env = {
        load_dotenv = true,
        vars = {
            BUILD_TYPE = "Release",
        },
    },
}

.env

When env.load_dotenv is true (the default in many setups), Beez reads .env from the project root and exposes values through beez.env("KEY") in build.lua.

Typical uses:

• build type or profile names
• paths to tools or output directories
• secrets you do not want in build.lua (also consider env.mask_secrets for logs)

Variables listed under env.hash_vars are included in cache fingerprints. See Environment Variables for details.

.cache/

Beez creates this directory at runtime (default path: .cache in the project root, configurable via cache.path).

It holds:

Subpath	Purpose
.cache/entries/	Step cache manifests
.cache/index/	Per-step cache indexes
.cache/success/	Per-file success cache (incremental lint/format, etc.)
.cache/logs/	Run log and worker logs

The cache is safe to delete. Beez rebuilds it on the next run. Use beez --clean-cache or a clean_cache task to clear it without removing build artifacts elsewhere.

Add .cache/ to .gitignore.

Global user config

Per-machine preferences live outside the repo:

~/.config/beez/config.lua

Or, if XDG_CONFIG_HOME is set:

$XDG_CONFIG_HOME/beez/config.lua

Use this for UI theme, default thread count, or personal cache settings. Project beez.config() and CLI flags override global values.

Inspect the merged result:

beez --show-config

Configuration priority

From lowest to highest priority:

1. Global ~/.config/beez/config.lua
2. beez.config({ ... }) in build.lua (including loaded config.lua)
3. Environment (.env and process env, per env settings)
4. CLI flags (--verbose, --no-cache, -j, etc.)

What Beez does not require

Beez does not mandate a particular build system, directory layout, or artifact paths. Your steps can call CMake, Meson, a plain shell script, or anything else. The repo layout beyond build.lua is entirely up to you.

Next steps

• First Pipeline - write your first build.lua
• Core Concepts - steps, tasks, workflows
• Configuration - all config keys explained