title: Build options description: Every knob the build takes: the Docker build arguments, the environment variables the scripts read, the pinned dependency versions, and what happens when one is wrong. date: 2026-08-02 tags: [reference, build] authors: [Matt Cockayne matt@phpboyscout.uk]

Build options¶

The complete set of inputs to a build, what each defaults to, and how it fails when it is wrong. Build from source is the task-oriented version of this page; The build explains why the pipeline is shaped this way.

There are two Dockerfiles and four shell scripts. The Dockerfiles take build arguments; the scripts read environment variables. Running the scripts directly (as CI does) means setting the environment variables yourself.

Docker build arguments¶

Both build/Dockerfile (the WASM module) and build/Dockerfile.native (the native driver) accept the same three:

docker build -f build/Dockerfile \
  --build-arg VARIANT=gpl --build-arg PROFILE=intermediate \
  --target artifact -o dist .

The --target artifact stage is a scratch image containing only the built binaries, so -o <dir> extracts them without an intermediate container.

What each build argument produces¶

Artifact naming is decided in the Dockerfile, and the lean profile deliberately keeps the original unprefixed name so existing consumers are unaffected:

What happens when a build argument is wrong¶

VARIANT is validated in deps.sh only. libav.sh treats anything other than gpl as the LGPL path, so a typo reaching libav.sh alone would silently build an LGPL artifact, so always run deps.sh first, as both Dockerfiles and CI do.

Environment variables the build scripts read¶

build/toolchain.sh is sourced by the other three and establishes the compile environment.

Running the scripts by hand is the same three steps CI takes:

FFMPEG_VERSION="$(sh build/ffmpeg-version.sh)"
export FFMPEG_VERSION VARIANT=lgpl PROFILE=lean
sh build/deps.sh
sh build/libav.sh
OUT=dist/ffmpeg-wasi-lgpl.wasm sh build/driver.sh

The just recipes¶

just build covers lean and intermediate only. The native driver has no recipe; invoke build/Dockerfile.native directly.

Pinned dependency versions¶

Every external library is pinned in build/deps.sh and overridable through the environment. The licence shown is the one deps.sh records for it.

x264 is pinned by commit, not tag, because x264 publishes no release tags. Bump X264_COMMIT to advance it.

Tarball digests are pinned alongside the version¶

The libraries fetched as release tarballs (Opus, LAME, Ogg, Vorbis, WebP, FreeType, HarfBuzz, FriBidi and libass) are verified against a SHA-256 hard-coded in build/deps.sh, so a compromised or altered mirror cannot slip modified source into an artifact. Those digests are not environment-overridable.

Overriding the version without editing the digest fails the build. fetch_tarball tries each mirror, rejects every download whose digest does not match, and then aborts with fetch: all mirrors failed (or checksum mismatched). Bump the version constant and its *_SHA256 constant in the same edit.

The git-cloned libraries (openh264, x264, x265, SVT-AV1, dav1d, zlib and FFmpeg itself) carry no digest and are pinned by tag or commit.

build/versions.lock is a record, not an input¶

build/versions.lock documents the wasi-sdk image and several dependency versions in a shell-assignment format. No script sources it. The real values live in two places:

• the base image line in each Dockerfile (the wasi-sdk image);
• the : "${VAR:=default}" defaults in build/deps.sh (every codec library).

Treat it as a summary to keep in step, and change the authoritative file as well.

FFMPEG_VERSION is the exception, and no longer appears in versions.lock at all. build/ffmpeg-version.txt is its single source of truth, resolved by build/ffmpeg-version.sh and read by CI, both Dockerfiles and build/sign-release.sh. On a release tag the two must agree: the tag's version prefix is checked against the file in the validate stage and a disagreement fails the pipeline before any build starts. So bumping FFmpeg is a merge request against that file and because that merge request builds the whole matrix, the tag rests on evidence rather than on the first build ever attempted. See spec 0035.

The size-budget gate¶

build/size-budget.txt sets a per-artifact byte ceiling; build/check-size-budget.sh compares each built artifact against its line and prints the result in the size-budget CI job on every tag. It is a tripwire for a profile ballooning, not a drift alarm, and the ceilings are deliberately generous. The job is advisory (allow_failure) until the ceilings are calibrated against real builds; an overage is reported, not enforced.

Related¶

• Build from source: the recipes, step by step.
• The build: why the toolchain, the shims and the two targets exist.
• Variants & artifacts: what each combination produces and how it is published.