Home/Docs

Quick start: one series, one build

This walkthrough creates a series, applies it to a pinned engine revision, builds a Linux x64 target and verifies the result. It assumes BEP is installed and bep doctor is clean.

Updated 2026-10-09Applies to 2.8.1Reading time 8 minutes

1. Create the series

$ bep init my-fork --family chromium --revision 8f2c41d9
created  my-fork/bep.toml
created  my-fork/patches/series.toml
created  my-fork/patches/0100-build-flags.patch
created  my-fork/.gitignore
series my-fork uses the built-in catalogue, 2 patches enabled

init writes a minimal bep.toml, an empty manifest and two starter patches from the catalogue. The revision is an upstream commit prefix; it must be at least eight characters and it must exist in the mirror named in the config.

2. Choose what the build keeps

Open patches/series.toml and remove or comment out patches you do not want. The order in the file is the order in which diffs are applied. Two entries are on by default:

[build-flags]
optional = false
note = "smaller local optimisations, faster links"

[debug-hooks]
optional = true
requires = ["build-flags"]
note = "symbols and a debug port in dev builds"

3. Fetch the sources

$ bep fetch
resolving  chromium @ 8f2c41d9
fetching   into /home/ana/.cache/bep/v3/src/8f2c41d9
received   1.9 GiB in 214 files  (git, 41 s)
checked out 4.2 GiB working tree
lock       wrote bep.lock (revision, 2 patch hashes)

The fetch is resumable. If it stops halfway, run it again; it continues from the last complete pack. Sources are shared by every series that pins the same revision.

4. Apply, dry run first

$ bep apply --dry-run
would apply  0100-build-flags     6 files  clean
would apply  0200-debug-hooks     3 files  clean
2 patches, 0 conflicts, 0 skipped

$ bep apply
applied      0100-build-flags     6 files
applied      0200-debug-hooks     3 files
tree         clean, lock matches

Exit code 2 means a conflict. The report names the patch and the files with rejected hunks; the patch format page explains the two ways to resolve it.

5. Build

$ bep build --target linux-x64 --jobs 12
configure  out/linux-x64  (release, clang 18)
compile    18 402 targets
link       ./out/linux-x64/engine
done       71 min 12 s  (cache hit 86 percent)

The first build is the slow one. Edit a patch, run bep apply and build again; only the files named by that patch are recompiled. A typical single-patch edit costs three to five minutes. If the machine becomes unresponsive during the link step, lower --jobs: each compile job can peak at 2.5 GB, and the linker needs another 6 to 8 GB on its own. On a 16 GB machine, 8 jobs finish a first build in about 105 minutes without swapping, which is faster than 12 jobs that swap.

The build writes one log per target under out/linux-x64/logs/, named by timestamp. It keeps the last ten and deletes older ones at the start of the next build. Nothing is rotated in the cache directory; bep cache gc is the command that removes things.

6. Verify

$ bep verify
manifest   bep.manifest (2 918 entries)
compared   2 918 / 2 918 files
result     match, 0 differences

Verification re-applies the series to a clean copy of the sources and compares file hashes with the manifest written by the last build. It does not rebuild binaries; use bep build --check for that. A mismatch names the file and both hashes, and the run stops at the first twenty differences unless --all is given. Commit bep.lock together with the patch that changed it: the lockfile is how another machine knows which combination produced this build.

Where things are

Next

Read Patch format before writing a patch of your own, and keep CLI reference open while you script the build. If something fails, Troubleshooting lists the messages by their first line.