moby/moby

Builder

Purpose

Moby ships two image builders in the same daemon:

Classic builder ("v0") — the original Dockerfile interpreter. Source: daemon/builder/.
BuildKit ("v1") — the modern build engine, integrated as a library. Source: daemon/internal/builder-next/.

The roadmap (ROADMAP.md §1.2) calls for replacing the classic builder with BuildKit; both still exist for compatibility.

/build requests carry a version query parameter. The router at daemon/server/router/build/ dispatches to the right backend. BuildKit is selected when the client opts in (the modern Docker CLI does so by default), otherwise the classic builder runs. The actual dispatcher is the Backend interface in daemon/server/buildbackend/.

Classic builder

daemon/builder/
├── builder.go              # Builder interface
├── backend/                # Backend implementation that targets the legacy image store
├── dockerfile/             # Dockerfile lexer, parser, evaluator, dispatcher
└── remotecontext/          # Build-context unpacking (tar, git, URL, named context)

Notable files:

File	Role
`dockerfile/parser/`	Tokenizer + AST.
`dockerfile/dispatchers.go`	One function per Dockerfile instruction (`FROM`, `RUN`, `COPY`, ...).
`dockerfile/builder.go`	Driver loop: parse, evaluate stages, commit layers.
`dockerfile/imagecontext.go`	Multi-stage `--from=` resolution.
`remotecontext/git.go`	Git URL contexts.
`remotecontext/lazycontext.go`	Streaming tar reader.

The classic builder commits each instruction as a new image layer using the legacy image store and distribution code.

BuildKit integration

BuildKit lives in github.com/moby/buildkit (a separate repo) and is consumed as a library. Moby's wrapper:

File	Role
`builder-next/builder.go`	`Backend` implementation that satisfies `buildbackend.Backend`.
`builder-next/controller.go`	Owns the BuildKit `Controller` and its workers.
`builder-next/executor.go`, `executor_linux.go`	Runs build steps as containerd tasks.
`builder-next/exporter/`	Exporters (image, oci, local, docker) into the engine's stores.
`builder-next/worker/`	BuildKit "worker" implementations on top of containerd.
`builder-next/imagerefchecker/`	Reference checker for cache pruning.
`builder-next/adapters/`	Glue to logging, registry, snapshotter, content store.

BuildKit drives builds via gRPC sessions tunneled over the daemon's /grpc endpoint (see daemon/server/router/grpc/ and daemon/server/router/session/).

Build cache

Both builders maintain caches keyed by image config + instruction hashes. Classic builder cache lives in the image graph itself; BuildKit cache lives in containerd's content store with metadata managed by BuildKit. /build/prune clears the cache; on the BuildKit path it calls Controller.Prune.

Output paths

Classic builder always produces a local image. BuildKit can output:

a local image (type=image, the default),
an OCI archive (type=oci),
raw filesystem (type=local),
a tar (type=tar),
a registry push (type=registry).

These map to the BuildKit exporters under builder-next/exporter/.

Sessions

Modern build clients open a "session" (/session) which the builder uses for secret forwarding, SSH agent forwarding, file uploads, and authentication. The session is multiplexed by BuildKit's session library.

Entry points for modification

New Dockerfile instruction (classic only): add a dispatcher in dockerfile/dispatchers.go and update the parser if syntax changes.
BuildKit feature work: most lives upstream in github.com/moby/buildkit. Wiring goes in builder-next/.
Build output formats: BuildKit exporters; the daemon-side wiring is builder-next/exporter/.