Debian wanna-build: Scheduling Architecture Builds

The Debian operating system maintains software packages across a wide array of hardware architectures using an automated compilation network. At the core of this system is wanna-build, a database-backed scheduling tool that coordinates with the Debian Archive Kit (dak) and build daemons (buildd). This article explains how wanna-build tracks package states, resolves architecture-specific dependencies, prioritizes compilation tasks, and dispatches jobs to keep thousands of packages synchronized across all supported CPU architectures.

The Core Infrastructure Components

Debian’s distributed compilation pipeline relies on three primary components working in concert:

  1. Debian Archive Kit (dak): Manages the central archive. When a maintainer uploads a source package (or an architecture-independent binary), dak accepts it, processes the changes, and notifies the build system that new source packages are available.
  2. wanna-build: The database engine and scheduler. It maintains an independent state database for each architecture, tracking whether a package needs to be compiled, is currently building, has failed, or is waiting for dependencies.
  3. buildd: The daemon running on dedicated build machines across various architectures. It polls wanna-build for work, sets up clean build environments using sbuild, performs the build, and uploads the resulting binary packages.

The Package State Machine

For every architecture, wanna-build tracks each package using distinct states:

  • Needs-Build: The package source is available in the archive, but no binary package exists yet for this architecture. It is eligible to be picked up by a build daemon.
  • Building: A buildd instance has claimed the package and is currently compiling it.
  • Uploaded / Installed: Compilation succeeded, and the generated .deb packages have been uploaded to the archive.
  • Dep-Wait: The package cannot build yet because required build dependencies are missing or out of date on this architecture.
  • Failed / Auto-Failed: Compilation was attempted but failed due to source code errors, test failures, or unmet conditions.
  • BD-Uninstallable: The build dependencies cannot be satisfied within the archive’s current dependency graph.

Scheduling and Prioritization Logic

When multiple packages are in the Needs-Build state, wanna-build uses a deterministic scoring algorithm to order the build queue:

  • Urgency: Source uploads in Debian can specify urgencies (low, medium, high, critical). Higher urgency packages move toward the front of the queue to expedite security updates and critical fixes.
  • Archive Section: Core system packages (such as base and libs) receive higher priority than general user applications or games, ensuring foundational libraries are compiled first to unblock dependent software.
  • Previous Failure Penalties: Packages that have repeatedly failed or required manual intervention are deprioritized to prevent them from consuming compute cycles needed by healthy packages.

Handling Architecture-Specific Dependencies

Because architectures compile packages at varying speeds, dependencies often become available asynchronously. When a buildd attempts to build a package and discovers that required libraries are missing or not yet at the required version, the daemon signals wanna-build to place the package into the Dep-Wait state.

The entry records the exact package names and versions required. wanna-build continuously monitors the archive state for that specific architecture. Once the necessary dependencies transition to Installed, wanna-build automatically moves the waiting package back to Needs-Build, re-inserting it into the active queue.

The Dispatch and Build Lifecycle

The operational loop follows a continuous cycle:

  1. Polling: A buildd machine connects to the central wanna-build database over an SSH tunnel. It requests the highest-priority Needs-Build item matching its architecture.
  2. Locking: wanna-build changes the package status to Building and records a timestamp along with the builder ID, preventing race conditions where multiple nodes compile the same package.
  3. Execution: The daemon invokes sbuild to generate an isolated chroot environment, installs the exact build dependencies from the archive, and runs the build process.
  4. Completion:
    • If the build succeeds, buildd signs the package artifacts, uploads them via dput to the archive incoming queue, and notifies wanna-build to mark the package as Uploaded.
    • If the build fails, the daemon uploads the build log, and wanna-build transitions the package state to Failed or Dep-Wait, depending on the exit conditions.
  5. Timeout Handling: If a builder goes offline or a build hangs indefinitely, wanna-build detects the stale Building lock after a designated timeout and resets the package back to Needs-Build.