# Crucial Files for Understanding the Core Functionality of apple/container

> Discover crucial files in apple/container for understanding core functionality. Explore Builder Swift, BuildPipelineHandler, and more to grasp the build lifecycle and gRPC client.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: internals
- Published: 2026-06-27

---

**The crucial files for understanding the core functionality of apple/container are concentrated in [`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift), which orchestrates the gRPC client and build lifecycle, alongside [`BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/BuildPipelineHandler.swift), [`BuildFSSync.swift`](https://github.com/apple/container/blob/main/BuildFSSync.swift), [`BuildImageResolver.swift`](https://github.com/apple/container/blob/main/BuildImageResolver.swift), and [`BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/BuildRemoteContentProxy.swift) that handle the pipeline from filesystem synchronization to final OCI image export.**

The apple/container repository implements a lightweight container-build system written in Swift. At its heart lies a **gRPC-driven build daemon** that processes build requests through a structured pipeline of handlers. Understanding this architecture requires examining the specific source files that manage the end-to-end flow from build context preparation to image resolution.

## The Entry Point: Builder.swift

[`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift) serves as the primary entry point for the entire build system. This file defines the `Builder` class, which creates a gRPC client connection over a Unix-domain socket and exposes the public API for container operations.

The `Builder` initializes with a `FileHandle` for the socket, a `MultiThreadedEventLoopGroup`, and a `Logger`. It launches a background task to maintain the persistent gRPC connection. The two critical public methods are:

- **`info()`** – Retrieves build daemon information.
- **`build(_:)`** – Accepts a `BuildConfig` struct, assembles build-time metadata, opens an async stream for client-to-server messages, and invokes `client.performBuild`.

When a TTY is requested, `Builder` also wires up a terminal resize handler that registers a `SIGWINCH` signal handler. This handler injects a `ClientStream` message containing new terminal dimensions (lines 108–135), ensuring the remote build process updates its progress display correctly.

## The Build Pipeline Architecture

[`Sources/ContainerBuild/BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildPipelineHandler.swift) defines the abstractions that power the concurrent build processing. This file contains the `BuildPipelineHandler` protocol, which requires two methods:

- **`accept(_:)`** – Determines whether the handler should process a given `ServerStream` packet.
- **`handle(_:)`** – Performs the actual processing work.

The same file (or an associated actor in the same module) implements the `BuildPipeline` actor. This actor maintains an ordered list of pipeline handlers and manages concurrent execution. The pipeline runs all handlers concurrently, aborting immediately when the first handler reports an error, ensuring fail-fast behavior during the build process.

## Core Pipeline Handlers

The build pipeline delegates specific tasks to specialized handlers, each defined in their own file within `Sources/ContainerBuild/`.

### Filesystem Synchronization: BuildFSSync.swift

[`Sources/ContainerBuild/BuildFSSync.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildFSSync.swift) implements the handler responsible for mirroring the build context directory into the container’s build-time filesystem. It reads the context directory, computes tar streams of the files, and writes them to the gRPC pipe. This ensures that file changes are visible to subsequent handlers before the actual build steps execute.

### Remote Content Resolution: BuildRemoteContentProxy.swift

[`Sources/ContainerBuild/BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildRemoteContentProxy.swift) resolves remote resources referenced in the build definition, such as `COPY --from` images. It consults the `ContentStore` to stream fetched content to the builder while handling caching and deduplication. This handler acts as a proxy between the local build process and remote registries.

### Image Resolution and Export: BuildImageResolver.swift

[`Sources/ContainerBuild/BuildImageResolver.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildImageResolver.swift) handles the final stage of the build pipeline. It pulls base images when the `pull` parameter is true, computes the layered filesystem, and writes the final OCI image (or other export formats) to the requested destination. This file interacts heavily with the `Containerization` and `ContainerizationOCI` modules to create the image manifest and tarball.

### Standard I/O Streaming: BuildStdio.swift

[`Sources/ContainerBuild/BuildStdio.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildStdio.swift) forwards build logs, progress bars, and error messages to the appropriate output destination (TTY or `stderr`). It parses `ServerStream` messages containing log entries and forwards them to an `AsyncStream` continuation that the client side consumes, enabling real-time build log streaming.

## Supporting Infrastructure

Beyond the core build pipeline, several directories provide essential infrastructure:

- **`Sources/ContainerAPIClient`** – Contains generated gRPC client bindings for the `container.build.v1.Builder` service.
- **`Sources/ContainerPersistence`** – Provides abstractions for the content store, snapshot handling, and configuration loading.
- **`Sources/Containerization`**, **`Sources/ContainerizationOCI`**, **`Sources/ContainerizationOS`** – Lower-level utilities for handling OCI image specifications, filesystem snapshots, and OS-specific operations such as Linux namespace setup.

These modules provide data structures like `BuildConfig` and `ContainerSystemConfig`, along with helper functions (`URL+Extensions`, `TerminalCommand`, `Globber`) that the builder uses to construct the final image.

## Practical Usage Example

The following Swift snippet demonstrates how to programmatically initiate a build using the core `Builder` class. This example creates a builder instance, configures a `BuildConfig`, and invokes the `build(_:)` method:

```swift
import ContainerBuild
import NIO
import Logging

let logger = Logger(label: "example")
let group = MultiThreadedEventLoopGroup(numberOfThreads: System.coreCount)

let socket = FileHandle(forWritingAtPath: "/var/run/container-build.sock")!
let builder = try Builder(socket: socket, group: group, logger: logger)

let config = Builder.BuildConfig(
    buildID: UUID().uuidString,
    contentStore: try ContentStore(path: "/var/lib/container/content"),
    buildArgs: [],
    secrets: [:],
    contextDir: "/path/to/context",
    dockerfile: try Data(contentsOf: URL(fileURLWithPath: "Dockerfile")),
    dockerignore: nil,
    labels: [],
    noCache: false,
    platforms: [.linuxAmd64],
    terminal: nil,
    tags: ["myimage:latest"],
    target: "",
    quiet: false,
    exports: [try Builder.BuildExport(type: "oci", destination: nil, additionalFields: [:], rawValue: "type=oci")],
    cacheIn: [], cacheOut: [],
    pull: true,
    containerSystemConfig: ContainerSystemConfig.default
)

try await builder.build(config)

```

This example (adapted from `examples/container-machine-vscode`) shows the essential integration points: creating the gRPC client, configuring the content store, and executing the build with specific export parameters.

## Summary

Understanding the core functionality of apple/container requires studying these key components:

- **[`Sources/ContainerBuild/Builder.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/Builder.swift)** – Central gRPC client and entry point for build operations.
- **[`Sources/ContainerBuild/BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildPipelineHandler.swift)** – Defines the handler protocol and pipeline orchestration.
- **[`Sources/ContainerBuild/BuildFSSync.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildFSSync.swift)** – Manages build context filesystem synchronization.
- **[`Sources/ContainerBuild/BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildRemoteContentProxy.swift)** – Handles remote resource fetching and caching.
- **[`Sources/ContainerBuild/BuildImageResolver.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildImageResolver.swift)** – Resolves base images and generates OCI exports.
- **[`Sources/ContainerBuild/BuildStdio.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildStdio.swift)** – Streams logs and progress to the client.
- **`Sources/ContainerAPIClient`**, **`Sources/ContainerPersistence`**, **`Sources/Containerization*`** – Provide gRPC bindings, storage, and low-level OCI utilities.

Together, these files implement a complete container-build lifecycle from gRPC request handling through concurrent pipeline processing to final image export.

## Frequently Asked Questions

### What is the primary role of Builder.swift in the apple/container repository?

[`Builder.swift`](https://github.com/apple/container/blob/main/Builder.swift) acts as the main entry point for the container-build system. It establishes the gRPC client connection over a Unix-domain socket, manages the lifecycle of the build daemon connection, and exposes the `build(_:)` method that initiates the entire build process by streaming configuration data and handling terminal resize events.

### How does the build pipeline in apple/container handle errors?

The `BuildPipeline` actor processes handlers concurrently and implements a fail-fast mechanism. As soon as any handler reports an error, the pipeline immediately aborts all pending work. This behavior is defined in [`BuildPipelineHandler.swift`](https://github.com/apple/container/blob/main/BuildPipelineHandler.swift), where the `handle(_:)` method's error propagation triggers pipeline-wide cancellation.

### What distinguishes BuildFSSync from BuildRemoteContentProxy?

`BuildFSSync` (in [`BuildFSSync.swift`](https://github.com/apple/container/blob/main/BuildFSSync.swift)) handles local filesystem operations by tarring and streaming the build context directory into the container, while `BuildRemoteContentProxy` (in [`BuildRemoteContentProxy.swift`](https://github.com/apple/container/blob/main/BuildRemoteContentProxy.swift)) manages external resources by resolving remote content like base images through the `ContentStore` with caching and deduplication support.

### How does apple/container generate OCI-compliant images?

The [`BuildImageResolver.swift`](https://github.com/apple/container/blob/main/BuildImageResolver.swift) file handles OCI image generation by pulling base images when configured, computing filesystem layers, and interacting with the `Containerization` and `ContainerizationOCI` modules. It constructs the image manifest and writes the final tarball to the specified export destination, supporting various export formats beyond standard OCI layouts.