Configuration
One file per series: bep.toml. It names the engine, the revision, the patch directory and the build defaults. Profiles change a few keys without duplicating the file.
A complete file
# bep.toml: generated by bep init, edited by hand
[engine]
family = "chromium" # chromium | gecko
revision = "8f2c41d9" # upstream commit prefix
mirror = "file:///srv/mirrors/engine.git"
[series]
dir = "patches"
optional = false # force every patch to be mandatory
[build]
out = "out"
target = "linux-x64"
jobs = 12
ccache = true
[verify]
hash = "sha256"
manifest = "bep.manifest"
[ui]
color = "auto" # auto | always | never
[profile.dev]
jobs = 8
extra_apply_flags = ["--3way"]
[profile.ci]
jobs = 4
extra_apply_flags = ["--3way", "--reject"]The file is TOML 1.0. Comments are allowed anywhere; unknown keys are an error, so a typo in jobs stops the run instead of being ignored.
Keys
| Key | Default | Notes |
|---|---|---|
engine.family | none | chromium is stable; gecko is preview in 2.8. |
engine.revision | none | At least 8 hex characters. Changing it invalidates the cache and the lockfile. |
engine.mirror | required | Any URL the configured fetch command understands; git is the default. |
series.dir | patches | Relative to the file. Must contain series.toml. |
series.optional | true | When false, optional = true in a patch is ignored. |
build.out | out | Cleared by bep build --clean. Never placed in the cache. |
build.target | linux-x64 | One of linux-x64, linux-arm64, macos-arm64, win-x64. |
build.jobs | cores − 1 | Capped at 64. Above core count rarely helps; see the note on memory below. |
build.ccache | true | Uses CCACHE_DIR when set, otherwise the cache directory. |
verify.hash | sha256 | sha256 or blake3. The manifest records which one wrote it. |
verify.manifest | bep.manifest | One line per file: hash, size, path. |
ui.color | auto | Auto follows NO_COLOR and whether stdout is a terminal. |
Profiles
A profile is a named set of overrides, selected with --profile dev or the BEP_PROFILE variable. Keys in a profile replace the top-level value of the same name; they do not merge, so a profile that sets jobs to 8 overrides the 12 above. Apply-only flags live in extra_apply_flags because the command line already owns --3way and --reject, and two sources of truth for the same switch are how builds become irreproducible.
$ bep config show --profile ci
build.jobs 4 (profile ci)
build.target linux-x64 (bep.toml)
series.optional true (default)
apply.flags --3way --reject (profile ci)config show is the fastest way to answer “why is it building with four jobs”. It prints the value and where it came from, including defaults.
Precedence
- Command-line flag, for example
--jobs 16. - Environment variable, for example
BEP_JOBS=16. - Selected profile.
bep.toml.- Built-in default.
Environment variables
| Variable | Effect |
|---|---|
BEP_CONFIG | Path to a config file other than ./bep.toml. |
BEP_CACHE | Cache root; must be on a local filesystem. |
BEP_JOBS | Same as --jobs. |
BEP_PROFILE | Same as --profile. |
BEP_LOG | error, warn, info (default), debug. |
CCACHE_DIR | Compiler cache location when ccache is enabled. |
SOURCE_DATE_EPOCH | Fixed timestamp passed to the build; the tool sets a default from the lockfile. |
NO_COLOR | Disables colour regardless of ui.color. |
Memory, not cores, is the limit. Each job can peak at 2.5 GB while compiling a large translation unit. On a 16 GB machine, 12 jobs will swap and a link can fail with the kernel's out-of-memory message. Start at cores − 1 and lower it if the machine becomes unresponsive.
Checking a file
$ bep config check
bep.toml ok
profile dev ok (jobs 8, 2 apply flags)
profile ci ok (jobs 4, 2 apply flags)
warning engine.mirror uses a relative path, resolved against the seriesThe check does not touch the network. It validates types, enumerations and file references, then prints the resolved values for the default profile. Add --strict to make warnings fail the command, which is what the release pipeline does.